/onboard

description: Walk through swarm's core concepts and launch your first team
argument-hint: (no arguments — this command is a walkthrough)
disable-model-invocation: true

/swarm:onboard

You are guiding a new swarm user through the four concepts they need before running `/swarm:launch` for the first time. Follow every step in order. Do NOT skip steps. Do NOT batch AskUserQuestion gates — each gate is its own turn so the user actually reads the concept before clicking.

If the user passed arguments with this command (e.g., `/swarm:onboard build me a feature`), acknowledge once that onboarding doesn't take a task — it teaches — and offer `/swarm:launch` with their task as a starting point when they're ready. Then continue with Step 1 unchanged.

The tone is direct and brief. Explain each concept, then ask a gate question that either advances or lets the user ask for more. Do not narrate your own process.

---

Step 1: Welcome

Output this welcome, verbatim:

> Welcome to swarm. This is a short walkthrough — four concepts you need, then a choice about how to run, then your first team. > > You can quit at any time by saying "stop." Nothing is spawned until you confirm at the end.

Then proceed to Step 2 in the same response.

---

Step 2: Concept — Outcomes

Output this explanation, verbatim:

> **Outcomes.** Swarm wants to know what success looks like, not what to build. > > - **Implementation:** "Add a Redis cache in front of the user service." — describes a solution. > - **Outcome:** "User profile reads return in under 50ms and don't hit the DB when cached." — describes the result. > > Outcomes leave room for the team to reason about *how*. Constraints you want preserved ("don't change the public API") count as outcomes too.

Then use **AskUserQuestion**:

• question: "Got it?"
• header: "Outcomes"
• options:
• label: "Yes, continue"

description: "Move on to the next concept"

• label: "Show me another example"

description: "Give me one more outcome/implementation contrast"

If "Show me another example": output one more contrast example (pick any domain), then re-ask the same AskUserQuestion.

---

Step 3: Concept — Modes

Output this explanation, verbatim:

> **Modes.** Swarm picks different phase semantics for different work. You don't pick a mode first — you describe your outcomes, and swarm infers it. Knowing what's on offer just helps you recognize what's happening. > > - **Code** — building or fixing software. The lead is the only person who writes code. Review is technical. > - **Triage** — diagnosing an issue without changing it. The team traces the cause and maps the blast radius; nothing is edited or committed. > - **Writing** — articles, essays, docs. The lead coordinates; production and editorial follow a specific rhythm. > > Work that fits none of these (research, planning, analysis) runs as a general-purpose team — inferred automatically. > > `/swarm:launch` infers the mode from your outcomes. If you already know which one you want, `/swarm:code`, `/swarm:triage`, and `/swarm:write` are direct entry points.

Then use **AskUserQuestion**:

• question: "Got it?"
• header: "Modes"
• options:
• label: "Yes, continue"

description: "Move on to the next concept"

• label: "Give me an example of inference"

description: "Show me how outcomes map to a mode"

If "Give me an example of inference": output one short example showing how a stated outcome implies a mode (e.g., "Blog post about distributed systems → Writing; fix a checkout bug → Code"), then re-ask the same AskUserQuestion.

---

Step 4: Concept — Phase Arc

Output this explanation, verbatim:

> **The phase arc.** Every team runs the same phases in order: > > **Research → Converge → Approve → Execute → Review → Refine → Deliver** > > - **Research**: teammates investigate independently. > - **Converge**: the facilitator runs a roundtable, surfaces disagreement, drives consensus. > - **Approve**: the team's approach is presented to you. This is where you get a decision. Execute doesn't start until you say yes. > - **Execute**: the lead does the work. > - **Review**: the team checks the work, not you. > - **Refine**: optional — once the team reaches 9/10, you can ask for recursive refinement (9.25 → 9.5 → 9.75 → 10). > - **Deliver**: you get the final artifact with the team's sign-off. > > You watch during Execute and Review. You don't drive. That's the point.

Then use **AskUserQuestion**:

• question: "Make sense?"
• header: "Phase arc"
• options:
• label: "Yes, continue"

description: "Move on to the next concept"

• label: "Explain a phase in more detail"

description: "Tell me which phase and I'll expand just that one"

If "Explain a phase in more detail": ask the user (free text) which phase they want expanded. Output one focused paragraph on ONLY that phase. Do NOT pre-explain any other phase unless the user explicitly names it. If the user names multiple phases, address each one separately, in the order they named them. Then re-ask the same AskUserQuestion.

If the user selects "Other" with custom text, treat their free text as the request and respond to exactly what they asked — do not inject explanations of any other phase.

---

Step 5: Concept — The 9/10 Confidence Gate

Output this explanation, verbatim:

> **The 9/10 gate.** The facilitator won't let work reach you until the team scores it 9 out of 10 or better. > > 9/10 means: the logic is correct, there are no known defects left unaddressed, and the reviewers would ship this. If the score falls short, the lead fixes and the team re-reviews — automatically. You don't mediate. > > This is what keeps quality consistent run to run. Most of the work happens in the cycles you never see.

Then use **AskUserQuestion**:

• question: "Ready for the last two questions?"
• header: "Continue"
• options:
• label: "Yes, continue"

description: "Move on to setup"

• label: "Go back and review a concept"

description: