| name | plan |
| description | Architecture plan — tech decisions from an approved spec, before code |
| when_to_use | Use when turning a human-approved spec into an implementation plan — pattern choices, architecture decisions, mirror target, tradeoffs, and risks appended to the feature's GitHub issue — the pipeline Plan stage between /spec and /schema (NOT Claude Code plan mode). Triggers on: plan the architecture, architecture plan for the approved spec, pipeline Plan stage. |
| argument-hint | <feature>|#N [product] |
Plan — Architecture & Tech Decisions
Turn an approved spec into an implementation plan: the architecture decisions, the pattern choices, and the risks — the how behind the spec's what. Sits between /spec (human-approved) and /schema. Resumable; skippable for trivial work.
Usage
/plan #42 — plan from issue number
/plan billing — plan from feature name (finds the issue)
/plan billing hogwarts — product-scoped
Argument: $ARGUMENTS
Instructions
1. READ — Load the approved spec
gh issue view <N> --repo <repo> --comments
Require a ## Technical Spec comment AND human approval (the /spec checkpoint). If the spec is missing or unapproved, stop and route back to /spec. Extract: data model sketch, file plan, acceptance criteria.
2. SURVEY — Find what to mirror
Identify the closest existing feature to mirror (the spec usually names one). Read its content.tsx / actions.ts / form.tsx to lock the conventions this feature will follow. Note the canonical pattern cards that apply (.claude/patterns/cards/) and the domain rules (.claude/rules/<domain>/).
3. DESIGN — Generate the plan
Delegate the architecture judgment to tech-lead (and the user-level architecture agent). Produce, using .claude/templates/plan.md as the shape:
- Pattern choices — which pattern cards + rule files govern this feature, cited by name
- Architecture decisions — data flow, server/client boundaries, caching (
'use cache' where it applies), auth + tenant-isolation placement
- Mirror target — the existing feature this one copies, with its path
- Tradeoffs — the one or two real forks in the road and why this side
- Risks — what could break (migrations touching live tenants, breaking changes, perf)
4. PUBLISH — Append to issue
gh issue comment <N> --repo <repo> --body "<plan>"
Header the comment ## Implementation Plan and end with *Generated by plan stage. Ready for task breakdown.*.
5. EXIT GATE
Plan comment exists on the issue with: pattern choices, architecture decisions, mirror target, tradeoffs, risks. Ready for /tasks.
When to skip
Trivial features (a field add, a copy fix) don't need a plan — go straight to /schema or /code. The pipeline is a menu, not a mandate: /feature billing --from schema stays valid.