map

BRAINS Phase 2: Map High-Level Plan

Generate a stub-level task plan from accepted ADR(s), create beads tasks with brains: labels, and chain into /brains:implement. Default mode: --parallel.

Set the plugin base path:

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

Mode Behavior

Mode	Plan review
--single	Local subagent only
--parallel (default)	Star-chamber reviews task ordering, sizing, coverage, phasing
--debate	Star-chamber debates the plan across rounds

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. When set:

• Skip all user prompts — no branch prompt (step 3), no plan-acceptance gate (step 7).
• Star-chamber still runs per mode (--parallel reviews, --debate debates); feedback is auto-integrated into the plan without a user confirmation step. Think of this as "fix anything that needs fixing" — actionable findings get applied; items requiring a true architectural judgment call should be surfaced by escalating that plan-phase's tasks to brains:needs-human during phase 3 rather than blocking here.
• Branch offer becomes automatic: on a base branch, create brains/<slug> without asking; otherwise stay on the current branch (same as non-autopilot behavior).
• Chain into /brains:implement --autopilot with inherited mode at the phase transition — do not prompt.

Autopilot is propagated downstream — the inherited state is persisted in the plan header (see step 11) and honored by /brains:implement --resume.

Process

1. Parse arguments

Parse mode, --autopilot, --lean, --skills / --no-skills, --bullets / --no-bullets, rounds, and topic. If no topic and no prior phase 1 output exists, ask the user. If chained from phase 1, inherit the mode, autopilot state, --lean state, and --skills state.

--grill MUST be rejected with a clear error and a non-zero exit. Print: "--grill is phase-1 only; use /brains:brains --grill instead" and stop. --grill does not propagate from phase 1 either (per ADR-005 req 23).

Flag resolution for --skills (per ADR-005 reqs 18-19): 4-layer precedence, top-to-bottom — first definitive value wins:

1. Explicit CLI flag — --skills / --no-skills on the command line wins.
2. .claude/brains.local.md Flags table — skills row with true or false.
3. ~/.config/brains/defaults.json flags.skills — boolean.
4. 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 vendored $BRAINS_PATH/references/find-skills.md is read only when the find-skills fallback fires.

Flag resolution for --bullets (per ADR-005 reqs 44, 49): same 4-layer precedence, top-to-bottom — first definitive value wins:

1. Explicit CLI flag — --bullets / --no-bullets on the command line wins.
2. .claude/brains.local.md Flags table — bullets row with true or false.
3. ~/.config/brains/defaults.json flags.bullets — boolean.
4. Built-in default — false (auto-detection in step 5 may still flip the resolved value to true when the standard heuristic holds; --no-bullets always wins and forces standard shape).

In autopilot, if a topic is truly missing and no prior phase 1 output exists, do NOT stall waiting for input — stop with a brains:needs-human style message to the user explaining that /brains:map --autopilot requires either a topic argument or a prior phase 1 output.

--lean activates the token-efficiency path: use the compact multi-llm-protocol excerpt inline rather than reading the full reference; read the Research-Summary block from the plan header (written by phase 1) instead of re-reading the full research document — drill down to the full file only when a summary field is empty-but-relevant; follow the role manifest at $BRAINS_PATH/manifests/phase-2-map.md. Default off. --lean propagates to /brains:implement at the phase transition.

2. Derive topic slug

Convert the topic to kebab-case lowercase. Example: "add a health-check endpoint" → health-check-endpoint.

3. Branch offer

Note: When chained from /brains:brains (the common case), step 9 of phase 1 has already moved the user to a topic branch — this step is a no-op fallback for standalone /brains:map invocations on a base branch (per ADR-005 req 38).

Determine the current branch:

CURRENT_BRANCH=$(git branch --show-current)

Base branches (configurable via settings.local.json key brains.baseBranches, default main, master, develop):

• If CURRENT_BRANCH is a base branch:
  • Interactive: prompt "Create topic branch brains/<slug> and switch to it? [y/n]" — on yes, git checkout -b brains/<slug>; on no, continue on current branch with a one-line warning that BRAINS tasks will be labelled with the current branch name.
  • Autopilot: skip the prompt and auto-create brains/<slug> (git checkout -b brains/<slug>). Emit a one-line status update instead.
• Otherwise: use the current branch without prompting (same in both modes).

4. Load inputs

Find accepted ADR(s) in docs/adr/ matching the topic (by filename pattern or by user-selection if ambiguous) — ADRs are ALWAYS loaded whole, under all modes including --lean.

Research document loading depends on --lean:

• Non-lean (default): read the full research document at docs/research/<slug>-research.md (legacy fallback: docs/plans/<slug>-research.md for pre-v0.5 ADR runs). Preserves v0.2.x reading behavior.
• Under --lean: read only the research-summary block stashed by phase 1 (per $BRAINS_PATH/skills/brains/references/research-summary-schema.md). Drill down into the full research document only when a summary field is empty-but-relevant, when a task is flagged risk:high during grooming, or when --ignore-research-summary was passed.

Codebase exploration policy:

• If the research document's mtime is within 1 hour AND no git commits landed on the current branch since then: reuse phase 1's exploration; skip this step.
• Otherwise: spawn a refresher subagent (Agent with feature-dev:code-explorer) scoped to re-explore files listed in the ADR; note drift. Surface significant drift to the user before proceeding; append minor drift to the plan document.

5. High-level plan generation (subagent)

Spawn a planning subagent with a prompt that emphasizes:

• Produce stub-level tasks (no implementation specifics — intentionally stub-level so re-architecture in phase 3 is cheap to clean up)
• Identify inter-task dependencies
• Group into phases if >12 tasks (target: each phase independently testable)
• Include acceptance criteria per task

5a. Serial-sweep eligibility (per ADR-005 reqs 44-47)

Before (or alongside) plan generation, evaluate the three-condition heuristic:

• (a) The ADR introduces no new external dependencies or services.
• (b) All work is topologically serial — no parallel-independent streams.
• (c) No risk:high markers AND no architectural unknowns surfaced by grooming.

Pass these conditions into the planning subagent's prompt and ask it to return a verdict line bullets-eligible: true | false alongside the plan. Resolve the effective bullets state:

• If --no-bullets is the resolved CLI/config value, force standard multi-phase shape regardless of the verdict.
• Else if --bullets is the resolved CLI/config value OR the verdict is bullets-eligible: true, set the effective state to bullets and instruct the subagent to emit the plan in serial-sweep shape: 1 plan-phase (or at most 2 with a clear setup/teardown split), 3–6 coarse beads tasks, each with a markdown bullet checklist body of constituent file-level steps. See $BRAINS_PATH/skills/map/references/plan-format.md § "Serial Sweep Mode (bullets)".
• Otherwise, use the standard multi-phase shape (existing behavior).

If grooming downstream surfaces risk:high or new architectural unknowns, the skill MUST escalate back to standard multi-phase shape with a one-line warning to the user (per ADR-005 req 47).

Output path: docs/plans/YYYY-MM-DD-<slug>-map.md. This file IS overwritten on every phase-2 run. Do not preserve prior map documents — the plan is the tracker, not the archive. ADRs and research documents remain immutable.

6. Plan review (mode-dependent)

Behavior depends on the selected mode:

• --single: Skip plan review entirely. The subagent's output is accepted as-is and passed directly to the user gate.
• --parallel (default): Invoke the star-chamber to review the plan in parallel. Reviewers focus on task ordering, sizing, coverage, and phasing; their feedback is integrated into a revised plan before presenting to the user. Follow the parallel protocol in $BRAINS_PATH/references/multi-llm-protocol.md.
• --debate: Invoke the star-chamber to debate the plan across rounds. Reviewers challenge each other's positions on ordering, sizing, coverage, and phasing until consensus or the round limit is reached; the synthesized outcome is integrated into the plan. Follow the debate protocol in $BRAINS_PATH/references/multi-llm-protocol.md.

In --autopilot, star-chamber feedback (when applicable) is integrated without a user confirmation step — apply actionable findings, and surface anything that looks like a genuine architectural re-think as a brains:needs-human task during phase 3 rather than blocking here.

7. User gate

7a. Commit + push plan, surface link (per ADR-005 req 37c)

BEFORE presenting the gate options or showing the plan summary (interactive), AND in autopilot before the inline status update, the skill MUST commit + push the plan document so the user can review it on GitHub. This also applies to out-of-band plan-review requests where the user interrupts autopilot mid-flight to revise the plan.

PLAN_PATH="docs/plans/YYYY-MM-DD-<slug>-map.md"
CURRENT_BRANCH=$(git branch --show-current)

# Commit only when there are unstaged or staged changes to the plan file
if ! git diff --quiet -- "$PLAN_PATH" || ! git diff --cached --quiet -- "$PLAN_PATH"; then
  git add "$PLAN_PATH"
  git commit -m "docs(plan): map <slug>"
fi

# Push — set upstream if the branch has none
if git rev-parse --abbrev-ref --symbolic-full-name '@{u}' >/dev/null 2>&1; then
  git push
else
  git push -u origin "$CURRENT_BRANCH"
fi

After a successful push, IF git remote get-url origin contains the substring github.com, surface a clickable GitHub link (same derivation pattern as skills/brains/SKILL.md step 9 sub-step (d) — handle both https:// and [email protected]: remote forms; strip trailing .git):

Plan doc:
- https://<host>/<owner>/<repo>/blob/<branch>/<plan-path>

Skip the link block silently when no GitHub remote exists. Push failures should be surfaced to the user (do NOT bypass hooks or force-push); offer retry / skip-push-and-continue / abort, mirroring the phase-1 commit+push handling.

7b. Present gate options

• Interactive: Present the plan. Options:
  • Reject: revise in place, re-present. Stay within phase 2.
  • Accept: proceed to task creation, then chain to /brains:implement.
  • (Conditional) Accept and skip teammate spawn — available ONLY when all three are true: plan has <10 total tasks; all tasks fit in a single plan-phase; no task is flagged risk:high during grooming (check the per-task grooming annotations, or run a lightweight grooming pass now if not yet performed). When accepted, create the beads tasks (step 9) and then proceed to inline implementation in the CURRENT session without invoking /brains:implement. Execute tasks directly; run /brains:nurture --scope phase-1 and /brains:secure --scope phase-1 at the end.
• Autopilot: skip the gate. Proceed directly to task creation and chain to /brains:implement --autopilot. Autopilot NEVER auto-selects the skip-teammate-spawn option — it continues to chain through the full pipeline. Emit a one-line status update summarizing the plan (phase count, task count, any star-chamber findings that were integrated).

Bullets-mode override (per ADR-005 req 47): when the effective state from step 5a is bullets, the gate behavior changes:

• Interactive --bullets: still present the gate, but pre-select "Accept and skip teammate spawn" as the recommended option (option 3 / inline) and label it as such. The eligibility constraints in the third bullet above (<10 tasks, single plan-phase, no risk:high) are satisfied by construction in serial-sweep mode, so the conditional option is always available.
• --autopilot --bullets: skip the gate prompt entirely (autopilot already gates prompts) and proceed directly to the inline-execution path in the current orchestrator session — do NOT spawn a teammate, do NOT chain /brains:implement --autopilot. After task creation, execute the plan inline and run /brains:nurture --scope phase-1 and /brains:secure --scope phase-1 at the end.
• If grooming subsequently surfaces risk:high or new architectural unknowns, escalate back to standard multi-phase shape with a one-line warning and resume the standard gate/teammate-spawn behavior.

8. Task tracker selection

Follow $BRAINS_PATH/references/beads-integration.md § Tracker Selection.

9. Task creation

Follow $BRAINS_PATH/references/beads-integration.md § Task Creation (phase 2). For each plan-phase, create implementation tasks, the Nurture umbrella task, and the Secure umbrella task. For the final plan-phase, also create the Cleanup task.

10. Re-architecture cleanup

If this phase-2 run was triggered by a needs-human-kind=re-architecture escalation from phase 3, follow $BRAINS_PATH/references/beads-integration.md § Re-Architecture Cleanup BEFORE step 9.

Detection: the caller sets the environment variable BRAINS_REARCHITECTURE=1; /brains:map reads it on entry.

11. Write plan header with persisted mode

Update the map document to include the following frontmatter/header fields:

# Plan: <topic>

**Slug:** <slug>
**ADRs:** <list of paths>
**Research:** <research doc path>
**Mode:** <--single | --parallel | --debate>
**Autopilot:** <true | false>
**Accept-ADRs:** <true | false>
**Lean:** <true | false>
**Bullets:** <true | false>
**Skills:** <true | false>
**Teammate-model:** <sonnet | opus | haiku | (unset — /brains:implement will resolve and write back)>
**Branch:** <branch name>

<!-- Under --lean, embed the research-summary block inline here. Fields per
     skills/brains/references/research-summary-schema.md. Example:

```yaml
research-summary:
  libraries-and-versions: |
    - FastAPI 0.112
    - SQLAlchemy 2.0
  deprecated-apis-to-avoid: |
    - SQLAlchemy 1.x Query API
  codebase-patterns: |
    - Repository pattern in src/repos/
  prior-art: |
    - ADR-003 (auth middleware refactor)
  constraints: |
    - MUST maintain Python 3.11 compatibility

-->

The `Mode:`, `Autopilot:`, `Accept-ADRs:`, `Lean:`, `Bullets:`, `Skills:`, and `Teammate-model:` lines are read by `/brains:implement --resume`. CLI flags on `--resume` override the persisted values (e.g., `/brains:implement --resume --single`, `--autopilot`, `--lean`, `--teammate-model opus`, or the sugar aliases `--teammate-opus` / `--teammate-sonnet` / `--teammate-haiku`). On first phase-2 run, `Teammate-model:` MAY be left empty if the user has not chosen a tier; `/brains:implement` resolves the default per step 1b and writes the decision back to the plan header before launching the first teammate.

## Phase Transition

After tasks are created, chain into phase 3:

- **Interactive:** > "Phase 2 complete. Plan at `<map path>`. <N> tasks created across <K> plan-phase(s). Chaining into `/brains:implement` with mode `<mode>`."
  Invoke `/brains:implement` directly.
- **Autopilot:** > "Phase 2 complete. Plan at `<map path>`. <N> tasks created across <K> plan-phase(s). Chaining into `/brains:implement --autopilot` with mode `<mode>`."
  Invoke `/brains:implement --autopilot` directly — phase 3 will not prompt the user unless a `brains:needs-human` task surfaces.

## Additional Resources

- **`$BRAINS_PATH/references/multi-llm-protocol.md`** — shared multi-LLM invocation protocol
- **`$BRAINS_PATH/references/beads-integration.md`** — task tracker selection, label conventions, task creation commands
- **`$BRAINS_PATH/skills/map/references/plan-format.md`** — plan document template (created next in task 2.3)