init

/teamctl:init is the first-run onboarding for teamctl. A pre-flight .team/ guard bows out to /teamctl:adjust if a team already exists. Otherwise: prerequisites and install (Stage 1), then open on the goal — understand what the team is for, with pickable starter goals (the Goal beat) — an intent on-ramp + a discovery conversation that surfaces the user's domains (Stage 2) fed by the user's work, a codebase-investigation pass, or a fast-path scaffold (four routes), then propose the org as a capability setup the user signs off on (Stage 3 — sessions, models, sub-agents, skills, hooks, /loop; the diagram is a small supporting visual, not the headline), iterate until it's right (the refine loop), scaffold .team/ and reveal the YAML (Stage 4 — emits cascading role prompts and the per-agent capability stack: sub-agents, skills, the earned hook), bring it up (Stage 5), wire Telegram + voice-customize (Stage 6), point at the lifecycle commands (Stage 7).

Read RULES.md, INTERACTIVE.md, and capability-catalog.md before the stages that use them. RULES carries the architecture invariants; INTERACTIVE carries the UI invariants — when to reach for AskUserQuestion, the Apply/Modify/Reject gate, the headless-pane fallback, docs-as-ground-truth, voice control; the capability catalog is the palette Stage 3 reasons from and Stage 4 emits (sub-agent / skill / hook archetypes, the bespoke escape hatch, the cron/MCP guard on the generated team). Voice rails: 1-2 sentences per beat, "experienced reliable coworker", emojis sparingly. Body voice is runtime-neutral. "Claude Code runtime" is a fact about the agent and stays; "Claude reads the file" is voice drift and goes. Substrate constraints are non-negotiable. The flow is resumable and idempotent — re-running skips anything already done.

Preamble — detect interactive vs headless

At the top of every invocation, decide which mode you're in:

if [ -n "$TEAMCTL_ROOT" ] && [ -n "$AGENT_ID" ]; then
    echo "headless"
else
    echo "interactive"
fi

headless means a supervised teamctl agent is calling this skill — AskUserQuestion is denied by the wrapper's PreToolUse hook (see #189). Fall back to plain-text Q&A for the whole invocation per INTERACTIVE.md §5. In practice /teamctl:init is overwhelmingly run from a fresh interactive claude session (there's no .team/ yet), so the headless path here is mostly a defensive catch.

The shape of Stage 2 matters. Stage 2 — domain discovery — does not hand users a template menu. It walks them through a discovery conversation that surfaces the domains in their work: the things with their own state, history, and decisions that compound over time. The cut is by domain ownership, not by job function. The Goal beat and the intent on-ramp ("Mode pick" below) are where option menus live; Stage 2 itself stays free-form when it runs. Read docs/src/content/docs/concepts/teams.md before tuning Stage 2 prose; the methodology there is canonical.