plan — spec to execution plan

Caution

No plan — no execution. /brewcode:start requires a PLAN.md with a Phase Registry. Skipping /brewcode:plan and writing phases by hand produces incomplete exit criteria, missing verification phases, and untraceable requirements. The quorum review (2/3 agents) catches gaps before a single line of code is touched.

Tip

Two entry points. Feed it a SPEC.md from /brewcode:spec, or point it at a Plan Mode file (.claude/plans/LATEST.md). Both paths produce the same artifact structure. Add -n / --noask to skip all interactive prompts and auto-approve defaults.

Quick reference

FieldValue
Command/brewcode:plan
Arguments[-n] [task-dir|SPEC.md|plan-file]
Flag -n / --noaskSkip all questions, auto-approve defaults
Modelopus
ToolsRead, Write, Glob, Grep, Bash, Task, AskUserQuestion

When to use

  • After /brewcode:spec — convert a finished SPEC.md into a phased execution plan
  • From Plan Mode — point at .claude/plans/LATEST.md when no SPEC exists
  • Large tasks — any feature that needs more than one agent or more than a day of work
  • Team projects — phases get assigned to project team agents defined in .claude/teams/
  • Before /brewcode:start — start requires a valid PLAN.md; plan creates it

Examples

# Point at a task directory (reads SPEC.md inside it)
/brewcode:plan .claude/tasks/20260417_auth_task/

# Point directly at a SPEC file
/brewcode:plan .claude/tasks/20260417_auth_task/SPEC.md

# Use Plan Mode file (no SPEC needed)
/brewcode:plan .claude/plans/LATEST.md

# No questions — batch/CI mode
/brewcode:plan -n .claude/tasks/20260417_auth_task/SPEC.md

After the skill completes:

/brewcode:start .claude/tasks/20260417_auth_task/PLAN.md

Flow

  1. Detect input + check templates

    Resolves the argument to a task directory or plan file. Checks project templates in .claude/tasks/templates/ first, then falls back to plugin templates in $BC_PLUGIN_ROOT/skills/setup/templates/. Missing templates in both locations → stop, run /brewcode:setup.

  2. Read SPEC + scan reference examples

    Extracts goal, requirements, context files, risks, and decisions from SPEC.md. Scans the project for 1-2 canonical files per expected phase type (controller, service, test) — these become Reference Examples (R1, R2…) embedded in each phase file.

  3. Generate phases + assign agents

    Breaks the SPEC into 5-12 phases. Each execution phase (1, 2, 3…) gets a paired verification phase (1V, 2V…). A Final Review (FR) phase closes the sequence. Agent assignment follows priority: team agent > project agent > plugin agent > system agent. Presents the phase split via AskUserQuestion (skipped with —noask).

  4. Write artifact tree

    Creates .claude/tasks/{‘{TS}_{NAME}_task’}/ with PLAN.md (slim Phase Registry), phases/*.md (one file per phase from templates), KNOWLEDGE.jsonl (empty seed), artifacts/, and backup/. Updates .claude/TASK.md quick-ref at the top.

  5. Quorum review — 3 agents in parallel

    Plan agent checks Phase Registry completeness. Architect agent reviews architecture decisions, technology choices, and phase dependencies. Reviewer agent checks exit criteria measurability and verification checklist quality. A remark is accepted only when 2 of 3 agents confirm it (2/3 consensus).

  6. Traceability check + fix loop

    A dedicated reviewer agent verifies every SPEC requirement maps to at least one phase file. Gaps produce missing phase files that are created and registered before results are shown. Confirmed remarks are presented to the user (or auto-applied with —noask). Fixed PLAN.md and phase files are validated on disk before the skill exits.

Full phase breakdown and artifact details

Input detection

InputAction
Path to {TS}_{NAME}_task/ dirRead SPEC.md from inside it
Path to SPEC.md fileDerive task dir from parent
.claude/plans/LATEST.md or any plan filePlan Mode: parse plan, create task dir, skip SPEC
EmptyCheck .claude/TASK.md for latest task dir

Template resolution

  1. Project templates: .claude/tasks/templates/{name}.template (adapted by /brewcode:setup)
  2. Plugin fallback: $BC_PLUGIN_ROOT/skills/setup/templates/{name}.template

Stop if both locations are missing for any template.

Directory structure created

.claude/tasks/{TS}_{NAME}_task/
├── phases/
│   ├── 1-{name}.md          # Execution phase
│   ├── 1V-verify-{name}.md  # Verification phase
│   ├── ...
│   └── FR-final-review.md   # Final Review
├── artifacts/
├── backup/
├── KNOWLEDGE.jsonl          # empty seed
└── PLAN.md                  # Phase Registry + metadata

Phase file placeholders

Each execution phase template fills: {PHASE_NUM}, {PHASE_NAME}, {AGENT}, {AGENT_ROLE}, {OBJECTIVE}, {CONTEXT_FILES}, {REFERENCES}, {TASK_LIST}, {CONSTRAINTS}, {EXIT_CRITERIA}, {ARTIFACT_DIR}, {ADDITIONAL_ARTIFACTS}.

Verification phase template adds: {VERIFY_AGENT}, {FILES_TO_REVIEW}, {VERIFICATION_CHECKLIST}, {AGAINST_REFERENCES}.

Final Review template adds: {FR_AGENTS}, {COMPLETION_CRITERIA}, {REVIEW_CHECKLIST}, {FILES_CHANGED}.

Plan Mode flow (no SPEC)

Steps 0-5 are identical to the SPEC flow except no SPEC.md is read — the plan file replaces it. Review is lightweight: 2 agents in parallel (architect + reviewer), both must confirm a remark (2/2 consensus).

Validation checks (run at end)

The skill verifies on disk: task directory exists, PLAN.md present, KNOWLEDGE.jsonl present, artifacts/ and backup/ directories exist, phases/ directory exists, every path listed in the Phase Registry matches an actual file, and .claude/TASK.md top line references the new task.

📄

Spec

Create the SPEC.md that feeds into this skill. Start here if you have requirements but no spec yet.

🚀

Start

Execute the PLAN.md this skill produces. Infinite handoff, phase-by-phase, with hooks injecting context.

🔗

GitHub source

SKILL.md, templates, and phase file format.

🧩

Brewcode overview

Full skill catalog: setup → spec → plan → start → review → teardown.

Updating plugins

Use /brewtools:plugin-update to check and update the brewcode plugin suite in one command. See the FAQ for details.