Implement

BRAINS Phase 3: Implement with Teammates

Launch a fresh Claude Code teammate for each plan-phase, coordinate via beads state, handle failures gracefully. Default mode: --parallel (applies to nurture/secure reviews inside each teammate).

Set the plugin base path:

BRAINS_PATH="<base directory from header>/../.."

Mode Behavior

Modes affect the nurture and secure subagents that run INSIDE each teammate, not implementation itself:

Mode	Flow
--single	Nurture/secure run without star-chamber
--parallel (default)	Nurture/secure findings reviewed by star-chamber
--debate	Nurture/secure run as star-chamber debates

For --parallel and --debate, follow $BRAINS_PATH/references/multi-llm-protocol.md. Under --lean, follow the compact excerpt at $BRAINS_PATH/references/multi-llm-protocol-compact.md; consult the full file only for debate-round synthesis or error handling.

Autopilot (--autopilot)

Orthogonal flag that composes with any mode. Implementation still follows the standard teammate flow; autopilot only changes master's interaction posture:

• Start immediately. Do not prompt for confirmation before launching the first teammate. If chained from /brains:map --autopilot, state is inherited.
• No per-phase confirmation. Advance from plan-phase N to N+1 automatically once N's completion marker reports complete.
• Only stop when one of these happens:
  1. The user intervenes (cancels, types stop, or sends new instructions).
  2. A brains:needs-human task surfaces from a teammate — master pauses and runs the normal needs-human questionnaire flow (see $BRAINS_PATH/references/failure-recovery.md § Needs-Human Variants).
  3. All phases complete (natural end).
• User-response timeout still applies. If the user does not answer a needs-human questionnaire within the configured timeout, master writes paused.md and exits as usual. Resuming with /brains:implement --resume --autopilot continues in autopilot.
• Prerequisite failures still stop. Missing spawn backend (tmux + agent-teams both unavailable) or an unreachable task tracker is a hard stop; autopilot does not suppress these.

Autopilot state is persisted in the plan header (Autopilot: true) and read by --resume. CLI --autopilot / absence-of-flag on resume overrides the persisted value.

Process (Master-Side)

1. Parse arguments

Parse mode, --autopilot, --accept-adrs / --no-accept-adrs, --lean, --skills / --no-skills, --teammate-model <sonnet|opus|haiku> (and sugar aliases --teammate-opus, --teammate-sonnet, --teammate-haiku), --no-escalate-on-retry, --ignore-model-hints, --resume, and optional --slug <slug>. If --resume without --slug, find the most recent docs/plans/*-map.md with open tasks.

Flag resolution for --skills (per ADR-005 reqs 18-19): 5-layer precedence (the standard 4 layers plus a --resume plan-header lookup) — first definitive value wins:

1. Explicit CLI flag — --skills / --no-skills on the command line wins, including on --resume.
2. Plan header — on --resume, the persisted Skills: field in the plan header (see step 2) is consulted next.
3. .claude/brains.local.md Flags table — skills row with true or false.
4. ~/.config/brains/defaults.json flags.skills — boolean.
5. Built-in default — false.

When the resolved value is true, this skill follows $BRAINS_PATH/references/skills-detection.md and $BRAINS_PATH/references/skills-invocation.md. The flag is propagated to spawned teammates as raw text in the initial prompt (mirroring --lean); each teammate re-probes hotskills locally per references/skills-detection.md.

--lean activates the token-efficiency path: teammates receive only skills/implement/teammate.md (not the full master skill body); the compact multi-llm-protocol excerpt is inlined rather than read from the full reference; failure-recovery.md is lazy-loaded on first task failure; role-scoped context is loaded per $BRAINS_PATH/manifests/master-implement.md, manifests/teammate.md, manifests/nurture.md, and manifests/secure.md. Default off (byte-identical to prior behavior).

--teammate-model <sonnet|opus|haiku> selects the model used to spawn per-phase teammate Claude Code instances AND their internal subagents (grooming, implementation, nurture, secure). Star-chamber invocations are unaffected — they run through uvx star-chamber with their own provider configuration.

The sugar aliases --teammate-opus, --teammate-sonnet, --teammate-haiku are equivalent to --teammate-model <tier>. If more than one of these flags (including --teammate-model) is passed in the same invocation, the last one wins and a one-line warning is emitted.

Escalate-on-retry is ON BY DEFAULT: a teammate task that has failed twice on the teammate model is retried a third time on the orchestrator model before brains:needs-human is applied. Pass --no-escalate-on-retry to disable. The default is configurable via settings.local.json key brains.escalateOnRetry (boolean; default true); a CLI --no-escalate-on-retry flag overrides the setting for that invocation.

--ignore-model-hints (default off): disregard model-hint: prefer-opus fields in beads issue records. Without this flag, tasks flagged prefer-opus by grooming escalate to the orchestrator model even if the user selected a lower tier for general teammate work.

1b. Resolve teammate model

Detect the orchestrator tier (the model currently running /brains:implement). Try sources in order; use the first that returns a known tier:

# Source 1: CLAUDE_MODEL_ID env var (Claude Code sets this in recent versions)
# Source 2: `claude --print-model-info` CLI output, if available
# Source 3: plan-header override ORCH_TIER: <tier> (read in step 2 and plumbed back if needed)
# Source 4: user settings ~/.claude/settings.json or .claude/settings.local.json key "model"
MODEL_ID="${CLAUDE_MODEL_ID:-}"
if [[ -z "$MODEL_ID" ]] && command -v claude >/dev/null 2>&1; then
  MODEL_ID="$(claude --print-model-info 2>/dev/null | sed -n 's/^modelId: *//p')"
fi
case "$MODEL_ID" in
  claude-opus-*)   ORCH_TIER=opus ;;
  claude-sonnet-*) ORCH_TIER=sonnet ;;
  claude-haiku-*)  ORCH_TIER=haiku ;;
  *)               ORCH_TIER=unknown ;;
esac

When ORCH_TIER=unknown:

• If --teammate-model (or a sugar alias) was passed, honor it and proceed.
• Otherwise in autopilot: default TEAMMATE_MODEL=sonnet AND emit a warning line: "Orchestrator tier could not be detected (CLAUDE_MODEL_ID unset, claude --print-model-info unavailable). Defaulting teammates to Sonnet; override with --teammate-model."
• Otherwise in interactive mode: prompt "Orchestrator model could not be detected. Choose teammate model: sonnet / opus / haiku [sonnet]:" and respect the answer.

With a known ORCH_TIER, if --teammate-model / sugar alias was passed, honor it verbatim.

Otherwise:

• Orchestrator is Opus AND not --autopilot: prompt the user: "Orchestrator is Opus. Spawn teammates using Sonnet to reduce cost? [Y/n]" (default Y). Store the answer as TEAMMATE_MODEL.
• Orchestrator is Opus AND --autopilot: auto-select Sonnet without prompting. The pre-flight summary block (step 3b below) surfaces this choice — a silent one-line status update is NOT sufficient.
• Orchestrator is Sonnet or Haiku (any mode): default TEAMMATE_MODEL to the orchestrator tier. No prompt.

TEAMMATE_MODEL is propagated to step 5a teammate spawns (as --model to the Claude Code CLI for tmux mode, or as the model field in the agent-teams teammate spec) AND to internal subagent invocations inside the teammate (grooming, implementation, nurture, secure subagents).

Model-hint escalation within a teammate: when a task's beads record has model-hint: prefer-opus and --ignore-model-hints was not set, the teammate invokes the implementation subagent with ORCH_TIER (the orchestrator tier, typically Opus) instead of TEAMMATE_MODEL for that single task.

2. Load plan

Read the plan document. Extract:

• Slug
• Mode (may be overridden by CLI arg)
• Autopilot (may be overridden by CLI arg — presence of --autopilot flag sets true; absence on --resume keeps the persisted value)
• Accept-ADRs (Accept-ADRs: true | false; per ADR-005 req 35 — read on --resume so a run that explicitly accepted ADRs without manual review continues consistently. CLI override wins: an explicit --accept-adrs / --no-accept-adrs on --resume supersedes the persisted value.)
• Lean (may be overridden by CLI arg)
• Skills (Skills: true | false; may be overridden by CLI --skills / --no-skills — CLI wins on --resume)
• Branch (warn if current branch differs)
• Teammate-model (may be overridden by CLI arg — persisted value read on --resume so a run that explicitly picked Opus teammates doesn't silently fall back to the default on resume)
• Plan-phases (enumerate via brains:phase-* labels filtered by brains:topic:<slug>)

If the plan header does not yet contain a Teammate-model: field (older plans), resolve it via step 1b and write it back to the plan header before step 5 begins. The plan document IS authoritative for this field on subsequent resumes.

3. Prerequisite checks

Spawn mode detection (see $BRAINS_PATH/references/teammate-protocol.md § Spawn-Mode Detection):

if [[ "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-0}" == "1" ]]; then
  SPAWN_MODE="agent-teams"
elif command -v tmux >/dev/null 2>&1; then
  SPAWN_MODE="tmux"
else
  echo "error: /brains:implement requires either tmux or agent-teams."
  echo "Install tmux (apt/brew/pkg install tmux) OR"
  echo "enable agent-teams: set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in settings.json (Claude Code v2.1.32+)."
  exit 1
fi

Task tracker: follow $BRAINS_PATH/references/beads-integration.md § Tracker Selection.

3b. Pre-flight summary (autopilot + interactive)

Before spawning the first teammate, emit a prominent multi-line pre-flight summary block so the user can see — without scrolling or scanning a log — exactly what will run and at what cost tier. This block replaces the old one-line "Opus orchestrator detected; spawning teammates on Sonnet" status update.

Template (customize counts per actual plan):

── BRAINS phase 3 pre-flight ──────────────────────────────────
  Mode:              <--single|--parallel|--debate>
  Autopilot:         <on|off> (<effect — e.g. "no per-phase prompts">)
  Lean:              <on|off>
  Orchestrator:      <opus|sonnet|haiku|unknown>
  Teammate model:    <opus|sonnet|haiku> <← auto-selected for cost | from plan header | --teammate-model>
  Subagent model:    <same as teammate> <(+escalation on model-hint: prefer-opus)>
  Escalate-on-retry: <on|off> <(3rd failure retries on <orchestrator tier>)>
  Ignore-model-hints: <on|off>
  Plan-phases:       <N> plan-phases, <M> open implementation tasks
  Umbrella tasks:    <N> nurture, <N> secure, <0|1> cleanup
  Branch:            <current branch>
  Override:          /brains:implement --teammate-model <other-tier> [--resume]
───────────────────────────────────────────────────────────────

In autopilot, emit the block and proceed immediately — no confirmation prompt. The user can still cancel with Ctrl-C or stop during the autopilot loop.

In interactive mode, emit the block and pause with a single prompt: "Proceed with the above configuration? [Y/n]". On n, exit cleanly (no teammate is spawned); the user can re-invoke with adjusted flags.

The pre-flight block MUST be emitted before any teammate spawn in step 5. On --resume, emit a pre-flight summary for the remaining plan-phases (not the originally-planned full set) so the user sees the actual upcoming work.

4. Resume (if --resume)

Query the task tracker for the first brains:phase-N with any open tasks. Resume at that plan-phase.

5. Per-plan-phase loop

For each plan-phase in order:

5a. Launch teammate

Construct the initial prompt per $BRAINS_PATH/references/teammate-protocol.md § Teammate Initial Prompt Template — follow the template exactly; do not paraphrase or omit sections. The prompt MUST include accepted ADR paths, the plan path, the phase label (e.g. brains:phase-2), the inherited mode flag, the completion marker path under docs/plans/.state/, and the behavioral constraints specified in the teammate-protocol reference.

tmux mode:

tmux split-window -h "claude '<initial prompt>'"

agent-teams mode: Invoke TeamCreate with appropriate lead-provided teammate specification. See $BRAINS_PATH/references/teammate-protocol.md for the exact call pattern.

5b. Wait for completion

Poll every 15s (configurable via settings.local.json key brains.pollingIntervalSeconds):

• Completion marker file at docs/plans/.state/<slug>-phase-<N>-marker.json
• Beads task counts: tasks with brains:topic:<slug> + brains:phase-<N> by status

On state change, emit a one-line status update to the master pane (see $BRAINS_PATH/references/teammate-protocol.md § Progress Surfacing).

In agent-teams mode, TeammateIdle notifications arrive automatically; still poll beads for state changes that don't trigger idle.

5c. Handle needs-human

When a task acquires the brains:needs-human label, dispatch to the handler per $BRAINS_PATH/references/failure-recovery.md § Needs-Human Variants. Each variant has its own questionnaire prompt.

In autopilot, a surfaced brains:needs-human is one of the three explicit stop conditions. Master still runs the questionnaire flow — autopilot does not suppress the prompt — and resumes autopilot behavior after the user responds.

5d. User-response timeout

If the user does not respond to a questionnaire within the timeout (default 4h, configurable via settings.local.json key brains.userResponseTimeoutSeconds), follow $BRAINS_PATH/references/failure-recovery.md § User-Response Timeout.

5e. Advance

On teammate completion marker status complete: close the teammate's pane / shut down the agent-teams teammate, advance to next plan-phase.

6. Final cleanup teammate (conditional)

If any brains:cleanup-labelled tasks exist: launch one more teammate with phase label brains:cleanup, wait for completion, same flow as other phases.

7. Wrap-up

If a cleanup teammate ran, read its wrap-up report at docs/plans/<slug>-wrap-up.md. Otherwise master writes the wrap-up itself.

Wrap-up structure:

# Wrap-up: <topic>

**Slug:** <slug>
**Paused:** false   <!-- true in paused.md variant -->

## Per-Phase Summary
### Phase 1
- Tasks completed: X/Y
- Issues found (nurture): ...
- Issues found (secure): ...

### Phase 2
...

## Outstanding Work
<beads tasks still open, e.g., future/deferred labels>

## Known Gaps and Limitations
<surfaced by nurture/secure>

## Suggested Follow-up Plans
<optional>

Summarize the wrap-up to the user and close any remaining teammate panes.

7a. Transition draft PR to ready (per ADR-005 req 37a)

AFTER the wrap-up document is written, IF ALL of the following conditions hold, transition the PR from draft to ready:

1. The wrap-up has Paused: false (i.e., this is a clean completion, not a paused exit).
2. No brains:needs-human tasks are outstanding for this topic — verify with: bd list --label brains:topic:<slug> --label brains:needs-human --status=open returns empty.
3. command -v gh succeeds AND a PR exists for the current branch — verify with: gh pr view --head $(git branch --show-current) --json number -q .number 2>/dev/null returns a number.

When all conditions hold:

SLUG="<slug>"
CURRENT_BRANCH=$(git branch --show-current)

# Condition 2
NEEDS_HUMAN=$(bd list --label "brains:topic:$SLUG" --label brains:needs-human --status=open 2>/dev/null)

# Condition 3
PR_NUMBER=""
if command -v gh >/dev/null 2>&1; then
  PR_NUMBER=$(gh pr view --head "$CURRENT_BRANCH" --json number -q .number 2>/dev/null || true)
fi

if [[ -z "$NEEDS_HUMAN" ]] && [[ -n "$PR_NUMBER" ]]; then
  READY_OUTPUT=$(gh pr ready "$PR_NUMBER" 2>&1) || true
  if echo "$READY_OUTPUT" | grep -q 'already in "ready" state'; then
    echo "PR #$PR_NUMBER already marked ready; skipping"
  fi
  # Surface the PR URL either way for the user
  PR_URL=$(gh pr view "$PR_NUMBER" --json url -q .url 2>/dev/null || true)
  [[ -n "$PR_URL" ]] && echo "PR ready for review: $PR_URL"
fi

Skip silently when gh is missing, no GitHub remote exists, or no PR exists for the current branch. Failures (other than already-ready) MUST be logged but MUST NOT block wrap-up.

Teammate-Side Protocol

Teammates follow the protocol defined in $BRAINS_PATH/skills/implement/teammate.md. That file is included in the teammate's initial prompt. The master does not execute T1–T6; the master's job ends at spawning teammates and coordinating their completion.

Additional Resources

• $BRAINS_PATH/skills/implement/teammate.md — teammate-side protocol (T1–T6)
• $BRAINS_PATH/references/teammate-protocol.md — spawn, sync, marker format
• $BRAINS_PATH/references/beads-integration.md — task queries, label conventions, fallback
• $BRAINS_PATH/references/failure-recovery.md — failure flow, needs-human variants, state machine
• $BRAINS_PATH/references/multi-llm-protocol.md — star-chamber invocation protocol