Show the full install prompt (writes all three commands)
Install three custom Claude Code slash commands: /spec-plan, /spec-build, and /spec-review. They turn the plan-build-review loop into repeatable commands backed by saved plan files. Do all of the following:
1. Create the directory: ~/.claude/commands/
2. Write the file ~/.claude/commands/spec-plan.md with EXACTLY this content (between the PLAN_START and PLAN_END markers, do not include the markers themselves):
===PLAN_START===
---
description: Create a detailed implementation plan and save it to specs/todo/
allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Task
model: opus
argument-hint: [feature or task description]
---
# Spec Plan
## Purpose
Create a detailed implementation plan based on the request. Delegates codebase research to a subagent to keep the main context lean, then writes the plan. The plan is saved to `specs/todo/` and can later be built with `/spec-build`.
## Variables
USER_PROMPT: $ARGUMENTS
PLAN_OUTPUT_DIR: specs/todo/
## Instructions
- Delegate codebase exploration to a subagent
- Use the research results to write a detailed spec
- Plans MUST be detailed enough that a subagent can implement them without asking a single clarifying question. This is the #1 quality bar
- Include exact file paths, line numbers, and code examples for EVERY file touched
- Match the established spec format from `specs/done/` exactly
- Every code block must be COMPLETE and COPY-PASTEABLE. Never use `...`, `// TODO`, or placeholder comments
- For modified files, always show surrounding context (5+ lines before/after the change point) so the builder can locate the exact position
## Workflow
1. **Setup folders**
- Run `mkdir -p specs/todo specs/done`
2. **Read existing spec for format reference**
Read 1-2 recent specs from `specs/done/` to understand the established format. If `specs/done/` is empty (new project), use the canonical format below as-is. The format is:
- `# Title`
- `## Problem`: what's broken or missing
- `## Objective`: what we're building, numbered goals
- `## Phase N: Descriptive Title` with `### Na. Substep` sub-sections
- Each phase names the **File:** being created or modified
- `## Success Criteria`: checkbox list of acceptance criteria
- Optionally: `## Testing Strategy`, `## Files to Create / Modify` summary
Your plan MUST follow this exact structure. Do not invent a different format.
3. **Research the codebase**
Spawn a **Task** subagent with:
- `subagent_type`: `Explore`
- `description`: `Research for plan: [short topic]`
Use this prompt:
```
Research the codebase for an upcoming implementation task.
Working directory: [WORKING_DIR: use the current working directory]
Read .claude/CLAUDE.md for project structure, conventions, and key directories.
TASK DESCRIPTION: [USER_PROMPT]
Investigate and report:
1. Which existing files are relevant to this task? Give exact paths.
2. What existing patterns/conventions should the implementation follow?
3. What interfaces, types, or functions will need to be modified or extended?
4. Are there any existing implementations of similar features to reference?
5. What database tables are involved (if any)? What are their schemas?
6. What dependencies or imports are relevant?
7. For EACH file that needs modification, what are the exact line numbers of the code that will change? Read the file and report the specific line range.
CRITICAL: For every file you reference, you MUST include:
- The full absolute path
- The specific line numbers (e.g., lines 15-24) of relevant code
- A brief code snippet showing the current state
Be thorough. The plan will be built by a subagent that needs precise file references to implement without questions.
```
4. **Design solution**
- Use the research results to design the technical approach
- Make architecture decisions
- Plan implementation phases
5. **Assess complexity**
- Count the phases needed
- If 4+ complex phases, consider splitting into multiple specs
- Name split specs with numeric prefixes: `01-feature-part-one.md`
6. **Document the plan**
Create the spec following the EXACT format from `specs/done/`. Every plan MUST include:
### Required sections:
- `## Problem`: 1-2 paragraph description of what's broken or missing
- `## Objective`: numbered list of what we're building
- `## Phase N: Title`: one section per implementation phase
### Required detail within each phase:
- **File:** line stating the exact path being created or modified
- For modifications: the exact line numbers being changed (e.g., "Insert after line 45", "Replace lines 30-42")
- Complete, runnable code blocks, not pseudocode, not partial snippets. Include ALL imports, ALL type definitions, ALL function bodies
- For new files: the ENTIRE file content as a code block
- For modified files: enough surrounding context that the builder knows exactly where to insert/replace
### Required closing sections:
- `## Files to Create / Modify`: summary table of all files touched, grouped as "New Files" and "Modified Files"
- `## Testing Strategy`: specific test commands and manual verification steps
- `## Success Criteria`: checkbox list (`- [ ] criterion`) of acceptance criteria
### Buildability checklist (verify before saving):
- [ ] Every new file has a complete code block showing the entire file
- [ ] Every modified file specifies exact line numbers for changes
- [ ] All imports are explicitly listed (no "import the usual stuff")
- [ ] All environment variables needed are listed with their source
- [ ] All database schema changes include the full migration SQL
- [ ] All API request/response shapes are fully defined
- [ ] Each code block is copy-pasteable: no `...` ellipsis, no "add similar logic here" placeholders
- [ ] A builder agent could implement this without reading any other files
Generate a descriptive kebab-case filename and write the plan to `specs/todo/[filename].md`
7. **Self-review for buildability**
Before saving, re-read your entire plan and perform this test:
- For EACH phase, ask: "Could a builder agent execute this phase using ONLY the information in this spec?"
- If any phase references a pattern, function signature, type, or config that isn't fully spelled out in the spec, ADD that information inline
- If any code block uses `...` or `// existing code` or `# rest of function`, EXPAND it to show the complete code
- Verify that modified files show 5+ lines of surrounding context so the builder can locate the exact insertion point
- If the builder would need to read ANY file not shown in the spec, include the relevant excerpt
## Report
```
Plan Created
File: specs/todo/[filename].md
Topic: [brief description]
Phases: [count]
Key Components:
- [component 1]
- [component 2]
- [component 3]
Next: Run /spec-build specs/todo/[filename].md to implement
```
===PLAN_END===
3. Write the file ~/.claude/commands/spec-build.md with EXACTLY this content (between the BUILD_START and BUILD_END markers, do not include the markers themselves):
===BUILD_START===
---
description: Build from a plan file, then move the plan to done/
allowed-tools: Read, Write, Bash, Edit, Glob, Grep, Task
model: sonnet
argument-hint: [path-to-plan]
---
# Spec Build
## Purpose
Implement a plan from `specs/todo/` into working code. The heavy implementation work is delegated to a subagent to keep the main context lean. After successful completion, the plan is moved to `specs/done/`. Pairs with `/spec-plan`.
## Variables
PATH_TO_PLAN: $ARGUMENTS
## Instructions
- If no path is provided, check `specs/todo/` and ask which plan to build
- Delegate the actual implementation to a Task subagent
- Only move the spec after confirming the subagent succeeded
## Workflow
1. **Locate the plan**
- If PATH_TO_PLAN is provided, use it
- Otherwise, list files in `specs/todo/` and ask the user which to build
2. **Read the plan summary**
- Read just the first 10-15 lines of the spec to understand what it is
- Display the spec name and brief summary to the user
3. **Delegate to subagent**
Spawn a **Task** subagent with:
- `subagent_type`: `general-purpose`
- `mode`: `acceptEdits`
- `description`: `Build spec: [short name]`
Use this prompt:
```
You are building a spec for this project.
Working directory: [WORKING_DIR: use the current working directory]
Read .claude/CLAUDE.md FIRST. It contains build/lint/test commands, project structure, key conventions, and any migration or dual-mode requirements.
VERIFICATION COMMANDS:
- Check CLAUDE.md for the project's build, lint, and test commands
- Run the appropriate verification command(s) based on what you changed
- If the project has multiple stacks (e.g., frontend + backend), only verify the stacks you modified
KEY CONVENTIONS (from CLAUDE.md):
- When you create a migration file, you MUST also apply it via the appropriate migration tool
- Check CLAUDE.md for any dual-mode, multi-backend, or conditional execution requirements
YOUR TASK:
STEP 1: ENUMERATE PHASES AND FILE LIST
Read the spec file at: [SPEC_PATH]
A) List every phase/section in the spec (e.g., "Phase 1: ...", "Phase 2: ...").
You MUST implement ALL of them. Do not skip any phase.
Output the list as:
PHASE_LIST:
- Phase 1: [name]
- Phase 2: [name]
...
B) Extract EVERY file path mentioned in the spec: files to create, modify, or read for context.
Output the list as:
FILE_LIST:
- [path] (create | modify | context)
- [path] (create | modify | context)
...
STEP 2: READ ALL FILES IN FILE_LIST BEFORE ANY EDITS
Go through your FILE_LIST from Step 1B. For EACH file marked "modify" or "context":
- Read the full file (or at least the relevant sections referenced in the spec)
- For files that will be modified, note the current structure so your edits integrate cleanly
- For files marked "context", read them to understand patterns you need to follow
Do NOT start editing until EVERY file in FILE_LIST has been read.
After reading all files, output: "All [N] referenced files read. Starting implementation."
STEP 3: IMPLEMENT EACH PHASE IN ORDER
Work through each phase sequentially. For each phase:
- Implement everything described in the spec for that phase
- Do not skip phases that create non-code artifacts (skill files, config files, scheduler hooks, etc.)
- Only modify files explicitly mentioned in the spec or necessarily required
- After completing each phase, output:
CHECKPOINT: Phase [N]: [name] (DONE)
If a phase feels optional or unclear, implement it anyway. Every phase listed in the spec is required.
STEP 4: VERIFY
Run the project's build/lint/test commands as appropriate for the files you changed (check CLAUDE.md).
If build/tests fail, fix the errors (up to 2 attempts per command).
STEP 5: VERIFY ALL PHASES COMPLETE
Review your PHASE_LIST from Step 1A. For each phase:
- Confirm you output a "CHECKPOINT: Phase N (DONE)" for it
- If any phase is missing a checkpoint, implement it NOW before reporting
- Do NOT report SUCCESS if any phase was skipped
When done, output EXACTLY this format:
STATUS: SUCCESS or FAILURE
FAILURE_REASON: [description, only if FAILURE]
PHASES_COMPLETED:
- Phase 1: [name] (DONE)
- Phase 2: [name] (DONE)
(list every phase with DONE or SKIPPED)
FILES_CHANGED:
- [list each file modified/created]
VERIFICATION_RAN:
- [which commands were run and their result: PASS or FAIL]
SUMMARY: [1-2 sentence description of what was built]
```
4. **Process result**
**If SUCCESS:**
- Verify all phases show "DONE" (not "SKIPPED"). If any are skipped, treat as FAILURE.
- Move spec: `mkdir -p specs/done && mv [PATH_TO_PLAN] specs/done/`
- Run `git status` to show what changed
- Ask the user if they want to commit
**If FAILURE:**
- Leave spec in `specs/todo/`
- Report what went wrong, including which phases were incomplete
## Report
```
Build Complete
Plan: [original path]
Status: SUCCESS / FAILED
Location: specs/done/[filename] (moved) OR specs/todo/[filename] (retry needed)
Phases:
- [from subagent PHASES_COMPLETED]
Changes Made:
- [from subagent FILES_CHANGED]
Verification:
- [from subagent VERIFICATION_RAN]
Summary: [from subagent SUMMARY]
Next: Review the changes with git diff, then commit, or run /spec-review to grade it against the plan.
```
===BUILD_END===
4. Write the file ~/.claude/commands/spec-review.md with EXACTLY this content (between the REVIEW_START and REVIEW_END markers, do not include the markers themselves):
===REVIEW_START===
---
description: Review the implementation against the original spec file
allowed-tools: Bash, Read, Glob, Grep, Task
model: sonnet
argument-hint: [spec-file-path]
---
# Spec Review
## Purpose
Compare the implemented code against the original specification. Delegates the diff analysis and requirement checking to a subagent to keep the main context lean. Returns a clear verdict with actionable fixes for every issue found.
## Variables
SPEC_FILE: $ARGUMENTS
## Instructions
- Delegate the heavy review work (reading diffs, comparing requirements) to a subagent
- Present the subagent's findings in a clean report
- The subagent reads files and diffs but does NOT make changes
## Workflow
1. **Locate the spec**
- If SPEC_FILE provided, use it
- Otherwise, check `specs/done/` for the most recent spec
- Confirm which spec to review
2. **Delegate to subagent**
Spawn a **Task** subagent with:
- `subagent_type`: `general-purpose`
- `mode`: `default`
- `description`: `Review: [short spec name]`
Use this prompt:
```
You are reviewing code changes against a specification. DO NOT modify any files.
Working directory: [WORKING_DIR: use the current working directory]
YOUR TASK:
STEP 1: EXTRACT ALL REQUIREMENTS
Read the spec file at: [SPEC_FILE]
Extract EVERY requirement from ALL sections of the spec:
- Each numbered Phase and lettered sub-phase (e.g., Phase 1, 2a, 2b, 3a)
- Every code change described within phases (new files, imports, function additions, integration points)
- Every item in the Success Criteria section
- Every specific file path + modification described in the spec
Number each requirement R1, R2, R3... so none are missed. Be exhaustive. A spec with 3 phases and 6 success criteria typically has 15-25 individual requirements.
STEP 2: GET THE DIFF
Run `git diff HEAD` to see all uncommitted changes.
If the diff is empty, run `git diff HEAD~1` (recently committed).
If still empty, run `git log --oneline -5` and `git diff HEAD~3` to find the relevant changes.
Also use `grep -r` or read specific files mentioned in the spec to verify implementation details not visible in the diff.
STEP 3: CROSS-REFERENCE EACH REQUIREMENT
For EACH numbered requirement (R1, R2, R3...):
- Find the specific code in the diff or codebase that implements it
- Mark it [x] PASS with a brief note of where it's implemented (file:line or function name)
- Mark it [ ] FAIL with what's wrong and WHERE the fix should go
Do NOT skip any requirement. Do NOT mark something as PASS unless you found concrete evidence in the code.
STEP 4: CLASSIFY ISSUES
For each FAIL item, classify severity:
- blocker: Requirement is missing or broken, must fix before shipping
- tech_debt: Partially implemented or has a shortcut that should be cleaned up later
- skippable: Minor deviation that doesn't affect functionality
STEP 5: WRITE ACTIONABLE FIXES
For EACH issue (blocker or tech_debt), provide a specific fix:
- The exact file path that needs to change
- What needs to be added, removed, or modified
- A brief code snippet or description of the fix (enough for a developer to act on immediately)
Output EXACTLY this format:
VERDICT: APPROVED or APPROVED_WITH_NOTES or NEEDS_CHANGES
REQUIREMENTS:
- [x] R1: [requirement description] (file:line or function where implemented)
- [x] R2: [requirement description] (file:line or function where implemented)
- [ ] R3: [requirement description] FAIL: [what's wrong]
BLOCKERS:
- [Rn]: [description] FIX: [exact file path + what to change + code snippet if needed]
- (or "none")
TECH_DEBT:
- [Rn]: [description] FIX: [exact file path + what to change]
- (or "none")
SKIPPABLE:
- [Rn]: [description]
- (or "none")
SUMMARY: [2-3 sentence assessment]
```
3. **Present results**
- Parse the subagent's structured output
- Display the review report
## Report
```
## Spec Review Results
**Spec:** [spec file path]
**Status:** APPROVED | APPROVED_WITH_NOTES | NEEDS_CHANGES
**Requirements:** [N passed] / [N total]
### Requirements Checklist
[from subagent REQUIREMENTS, show all Rn items]
### Issues Found (if any)
**Blockers:**
[from subagent BLOCKERS, include FIX for each]
**Tech Debt:**
[from subagent TECH_DEBT, include FIX for each]
**Skippable:**
[from subagent SKIPPABLE]
### Recommendation
[VERDICT]: [from subagent SUMMARY]
```
===REVIEW_END===
5. Verify the install:
ls -la ~/.claude/commands/spec-*.md
When done, tell me the three commands are installed and that I can run /spec-plan, /spec-build, and /spec-review in any project. Remind me to restart Claude Code or start a new session so the commands load.