brewcode:plan

Create Plan — [task-dir or SPEC path or plan file]

<instructions>

/brewcode:plan Instructions

ROLE: Plan Creator | OUTPUT: PLAN.md + phases/*.md + KNOWLEDGE.jsonl + artifacts/ + backup/

Input Detection

| Input | Action | |-------|--------| | Path to {TS}_{NAME}_task/ dir | Read SPEC.md from it | | Path to SPEC.md file | Derive task dir from parent | | .claude/plans/LATEST.md or plan file | Plan Mode: parse plan, create task dir, skip SPEC | | Empty | Check .claude/TASK.md quick ref for latest task dir |

Flag Parsing

Parse $ARGUMENTS for flags BEFORE input detection:

| Flag | Effect | |------|--------| | -n, --noask | Skip all user questions, auto-approve defaults |

Strip flag from $ARGUMENTS. Remaining text = path.

Workflow (SPEC input)

1. Check Adapted Templates (REQUIRED FIRST)

EXECUTE using Bash tool: ``bash TMPL_DIR=".claude/tasks/templates" PLUGIN_TMPL="$BC_PLUGIN_ROOT/skills/setup/templates" echo "--- Project templates ---" test -f "$TMPL_DIR/PLAN.md.template" && echo "PLAN.md.template OK" || echo "PLAN.md.template MISSING" test -f "$TMPL_DIR/phase.md.template" && echo "phase.md.template OK" || echo "phase.md.template MISSING" test -f "$TMPL_DIR/phase-verify.md.template" && echo "phase-verify.md.template OK" || echo "phase-verify.md.template MISSING" test -f "$TMPL_DIR/phase-final-review.md.template" && echo "phase-final-review.md.template OK" || echo "phase-final-review.md.template MISSING" test -f "$TMPL_DIR/phase-fix.md.template" && echo "phase-fix.md.template OK" || echo "phase-fix.md.template MISSING" echo "--- Plugin fallback templates ---" test -f "$PLUGIN_TMPL/PLAN.md.template" && echo "PLAN.md.template FALLBACK OK" || echo "PLAN.md.template FALLBACK MISSING" test -f "$PLUGIN_TMPL/phase.md.template" && echo "phase.md.template FALLBACK OK" || echo "phase.md.template FALLBACK MISSING" test -f "$PLUGIN_TMPL/phase-verify.md.template" && echo "phase-verify.md.template FALLBACK OK" || echo "phase-verify.md.template FALLBACK MISSING" test -f "$PLUGIN_TMPL/phase-final-review.md.template" && echo "phase-final-review.md.template FALLBACK OK" || echo "phase-final-review.md.template FALLBACK MISSING" test -f "$PLUGIN_TMPL/phase-fix.md.template" && echo "phase-fix.md.template FALLBACK OK" || echo "phase-fix.md.template FALLBACK MISSING" ``

Template resolution order:

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 MISSING for any template -- Run /brewcode:setup first to get v3 templates. > If project templates missing but plugin fallback exists: WARN "Re-run /brewcode:setup for v3 project-adapted templates. Using plugin defaults."

1. Read SPEC

• Resolve input path per Input Detection table
• Read SPEC.md from task directory
• Extract: goal, requirements, analysis, context files, risks, decisions

1. Scan Project for Reference Examples

• Find 1-2 canonical files per expected phase type (controller, service, test, etc.)
• These become Reference Examples (R1, R2...) in PLAN.md

Dynamic Agent Resolution

Before assigning agents to phases, check for project team agents:

1. If .claude/teams/ exists — read team.md for agent roster with domains
2. If .claude/agents/ has project agents — list available
3. Match agent domain to phase task area
4. Priority: team agent > project agent > plugin agent > system agent
5. If agent refuses (Task Acceptance Protocol) — re-delegate to suggested colleague (max 2 retries)

Always fall back to plugin agents when no project agents match the task domain.

1. Generate Phase Breakdown (5-12 phases)

Based on SPEC analysis and project structure:

• Each phase = one logical unit of work
• Dependencies between phases identified
• Agents assigned per phase
• Verification phases (NV) after each execution phase
• Final Review (FR) as last phase

1. Present Phases to User (AskUserQuestion)

If --noask: Skip. Auto-approve all phases.

Otherwise: Use AskUserQuestion to present the proposed phase split:

• Phase count and descriptions
• Agent assignments
• Dependency chain
• User can approve, adjust, or request changes

1. Generate Artifacts

Read templates per resolution order from Step 0 (project first, plugin fallback second).

5.1 Create directory structure

`` .claude/tasks/{TS}_{NAME}_task/ ├── phases/ <-- NEW: individual phase files ├── artifacts/ ├── backup/ ├── KNOWLEDGE.jsonl (0-byte empty file) └── PLAN.md (slim, with Phase Registry) ``

EXECUTE using Bash tool: ``bash TASK_DIR=".claude/tasks/{TS}_{NAME}_task" mkdir -p "$TASK_DIR/phases" "$TASK_DIR/artifacts" "$TASK_DIR/backup" touch "$TASK_DIR/KNOWLEDGE.jsonl" ``

5.2 Generate phase files (from templates)

For EACH execution phase (1, 2, 3, ...):

• Read phase.md.template
• Fill placeholders with SPEC-derived content:
• {PHASE_NUM} -- phase number
• {PHASE_NAME} -- descriptive name (kebab-case for filename, Title Case for heading)
• {AGENT} -- assigned agent
• {AGENT_ROLE} -- one-line agent role description
• {OBJECTIVE} -- concrete objective from SPEC analysis
• {CONTEXT_FILES} -- table rows: files the agent needs to read/modify
• {REFERENCES} -- table rows: reference examples, docs, existing patterns
• {TASK_LIST} -- numbered task list with specific, actionable items
• {CONSTRAINTS} -- project-specific constraints (from SPEC + project rules)
• {EXIT_CRITERIA} -- measurable exit criteria (builds, tests pass, lint clean, etc.)
• {ARTIFACT_DIR} -- e.g., 1-1e (Phase 1 Execution, iter 1)
• {ADDITIONAL_ARTIFACTS} -- files created/modified by this phase
• Write to: phases/{N}-{name}.md (e.g., phases/1-create-entity.md)

For EACH verification phase:

• Read phase-verify.md.template
• Fill placeholders:
• {PHASE_NUM} -- matches the execution phase being verified
• {PHASE_NAME} -- same name as the execution phase
• {VERIFY_AGENT} -- tester or reviewer
• {FILES_TO_REVIEW} -- files created/modified by the execution phase
• {VERIFICATION_CHECKLIST} -- checklist items derived from exit criteria of execution phase
• {AGAINST_REFERENCES} -- reference examples to compare against
• {ARTIFACT_DIR} -- e.g., 1-1v (Phase 1 Verification, iter 1)
• {AGENT} -- same as {VERIFY_AGENT}
• Write to: phases/{N}V-verify-{name}.md

For Final Review:

• Read phase-final-review.md.template
• Fill placeholders:
• {FR_AGENTS} -- list of review agents (typically reviewer + tester + architect)
• {COMPLETION_CRITERIA} -- from SPEC.md goals/decisions, copied to PLAN.md Completion Criteria
• {REVIEW_CHECKLIST} -- comprehensive checklist covering all phases
• {FILES_CHANGED} -- aggregate of all files created/modified across all phases
• {ARTIFACT_DIR} -- FR-1e (Final Review, iter 1)
• Write to: phases/FR-final-review.md

5.3 Generate PLAN.md (slim v3 format)

Using PLAN.md.template (project-adapted or plugin fallback):

• Fill Phase Registry table with ALL generated phase files
• Each row references the corresponding phases/{file}.md
• Completion Criteria from SPEC.md decisions/goals
• Agents table from project analysis
• If .claude/teams/ exists: populate ### Project Agents table from team.md roster
• Technology Choices from SPEC analysis
• Role Constraints from project rules

5.4 Technology Choices

For each non-trivial choice (library, pattern, approach):

• Document in PLAN.md under Technology Choices section
• Include rationale + alternatives considered and reject