onboard

Onboard / Re-onboard

Bro orchestrates an AskUserQuestion ceremony in 3-5 rounds — Round 0 runs only when the session is nested below the project or another trajectory DB exists, Round 3 only when shape == 'remote'. Pass answers between AUQ and the server; all deterministic logic lives in the onboard_* MCP tools.

1. Read state (one MCP call)

Call onboard_state_get(agent='bro'). Returns { first_run, current, probe, nesting, scan }. The server re-probes internally on each call, so bro never feeds the probe back — read state.probe only to spot a shape/remote conflict in Round 1, state.nesting for Round 0, and state.scan for Round 2. scan is the offline pre-onboard scan of every registered repo: scan.summary (repo_count, hosts, with_dev_branch, main_only, uniform) and one scan.repos[] entry per repo with its evidence and recommendation.

2. Ask the questions

Run the AskUserQuestion ceremony in up to five rounds.

Every question from onboard_get_questions carries evidence (short facts from the scan) and recommended_reason (why the option marked recommended: true comes first, or null when the evidence picks none). Before each AskUserQuestion, write that round's evidence lines in chat as a short list, each line once, then each question's recommended_reason as one sentence. They stay in chat prose: feed the option labels and descriptions to AskUserQuestion exactly as the server built them. The Human confirms what the scan found instead of guessing.

Round 0 — Which project (only when nested)

nesting is { session_dir, project_root, nested, other_dbs: [{path, issues, tasks, empty}] }. Skip this round when nested is false and other_dbs is empty.

Otherwise explain in chat first: this session opened in session_dir, but the TMB project it uses is the workspace at project_root; list each other_dbs entry with its path and its issue and task counts. Then ask one AskUserQuestion:

• Use workspace <project_root> (Recommended) — keep the workspace project. For each other_dbs entry with empty: true, ask whether to remove that empty DB (one Yes/No question per DB). Collect the paths the Human said yes to and pass them as remove_stray_dbs=[...] with the final workspace apply in step 3 (or in an onboard_apply(agent='bro', remove_stray_dbs=[...]) call of their own if the ceremony stops early). The server deletes a DB only while it is still empty and below the project root, and reports each refusal; a DB with any issue or task is never offered or removed. Continue with Round 1.
• Make <session_dir> its own TMB project — offer this only when nested is true. Call onboard_apply(agent='bro', standalone=true) on its own. The server writes a standalone marker and a fresh DB under session_dir. Tell the Human to restart the session (quit and relaunch Claude Code in session_dir), then run /onboard again there. Stop this ceremony.
• Cancel — stop. Call no apply; nothing is written.