
spec-driven-development
Requirements clarification, phase planning, workstreams, and wave-based execution for reviewable delivery.
- version
- 0.6.3
- GitHub stars
- 9
Install
/plugin install spec-driven-development@agent-powerupsRun it inside Claude Code after adding the marketplace with /plugin marketplace add yeaight7/agent-powerups.
Contents
Discovered from sourceSkills 1
Purpose
Requirements Clarifier implements Socratic questioning with mathematical ambiguity scoring. It replaces vague ideas with crystal-clear specifications by asking targeted questions that expose hidden assumptions, measuring clarity across weighted dimensions, and refusing to proceed until ambiguity drops below the resolved threshold. The output feeds into planning and execution, ensuring maximum clarity at every stage.
When to Use
- User has a vague idea and wants thorough requirements gathering before execution
- User says "deep interview", "interview me", "ask me everything", "don't assume", "make sure you understand"
- User wants to avoid "that's not what I meant" outcomes from autonomous execution
- Task is complex enough that jumping to code would waste cycles on scope discovery
- User wants mathematically-validated clarity before committing to execution
Do Not Use When
- User has a detailed, specific request with file paths, function names, or acceptance criteria -- execute directly
- User wants to explore options or brainstorm -- use the plan skill instead
- User wants a quick fix or single change -- execute directly
- User says "just do it" or "skip the questions" -- respect their intent
Inputs
- A vague or underspecified implementation idea from the user
- For brownfield work: repo evidence (file paths, symbols, patterns) gathered by an explore agent before questions are asked
Execution Policy
- Ask ONE question at a time -- never batch multiple questions
- Target the WEAKEST clarity dimension with each question
- Make weakest-dimension targeting explicit every round: name the weakest dimension, state its score/gap, and explain why the next question is aimed there
- Gather codebase facts via an explore agent BEFORE asking the user about them (inspect the repo instead)
- For brownfield confirmation questions, cite the repo evidence that triggered the question (file path, symbol, or pattern) instead of asking the user to rediscover it
- Score ambiguity after every answer -- display the score transparently
- Do not proceed to execution until ambiguity ≤ the resolved threshold for this run
- Allow early exit with a clear warning if ambiguity is still high
Workflow
Phase 1: Initialize
-
Parse the user's idea
-
Detect brownfield vs greenfield:
- Check if cwd has existing source code, package files, or git history
- If source files exist AND the user's idea references modifying/extending something: brownfield
- Otherwise: greenfield
-
For brownfield: Explore relevant codebase areas
-
Set ambiguity threshold: Default 0.2 (20%)
-
Announce the interview to the user:
Starting requirements clarification. I'll ask targeted questions to understand your idea thoroughly before building anything. After each answer, I'll show your clarity score. We'll proceed once ambiguity drops below 20%.
Your idea: "{initial_idea}" Project type: {greenfield|brownfield} Current ambiguity: 100%
Phase 2: Interview Loop
Repeat until ambiguity ≤ threshold OR user exits early:
Step 2a: Generate Next Question
Question targeting strategy:
- Identify the dimension with the LOWEST clarity score
- Generate a question that specifically improves that dimension
- State, in one sentence before the question, why this dimension is now the bottleneck
- Questions should expose ASSUMPTIONS, not gather feature lists
Question styles by dimension:
| Dimension | Question Style | Example |
|---|---|---|
| Goal Clarity | "What exactly happens when...?" | "When you say 'manage tasks', what specific action does a user take first?" |
| Constraint Clarity | "What are the boundaries?" | "Should this work offline, or is internet connectivity assumed?" |
| Success Criteria | "How do we know it works?" | "If I showed you the finished product, what would make you say 'yes, that's it'?" |
| Context Clarity (brownfield) | "How does this fit?" | "I found JWT auth middleware in src/auth/. Should this feature extend that path or diverge?" |
Step 2b: Ask the Question
Present it with the current ambiguity context:
Round {n} | Targeting: {weakest_dimension} | Why now: {rationale} | Ambiguity: {score}%
{question}
Step 2c: Score Ambiguity
After receiving the user's answer, score clarity across all dimensions.
Greenfield: ambiguity = 1 - (goal × 0.40 + constraints × 0.30 + criteria × 0.30)
Brownfield: ambiguity = 1 - (goal × 0.35 + constraints × 0.25 + criteria × 0.25 + context × 0.15)
Step 2d: Report Progress
After scoring, show the user their progress:
Round {n} complete.
| Dimension | Score | Weight | Weighted | Gap |
| --- | --- | --- | --- | --- |
| Goal | {s} | {w} | {s*w} | {gap or "Clear"} |
| Constraints | {s} | {w} | {s*w} | {gap or "Clear"} |
| Success Criteria | {s} | {w} | {s*w} | {gap or "Clear"} |
| **Ambiguity** | | | **{score}%** | |
{score <= threshold ? "Clarity threshold met! Ready to proceed." : "Focusing next question on: {weakest_dimension}"}
Step 2e: Check Soft Limits
- Round 3+: Allow early exit if user says "enough", "let's go", "build it"
- Round 10: Show soft warning: "We're at 10 rounds. Current ambiguity: {score}%. Continue or proceed?"
- Round 20: Hard cap: "Maximum rounds reached. Proceeding with current clarity level ({score}%)."
Phase 3: Challenge Agents
At specific round thresholds, shift the questioning perspective:
Round 4+: Contrarian Mode
Challenge the user's core assumption. Ask "What if the opposite were true?" or "What if this constraint doesn't actually exist?"
Round 6+: Simplifier Mode
Probe whether complexity can be removed. Ask "What's the simplest version that would still be valuable?"
Round 8+: Ontologist Mode (if ambiguity still > 0.3)
The ambiguity is still high after 8 rounds, suggesting we may be addressing symptoms rather than the core problem. Ask "What IS this, really?"
Challenge modes are used ONCE each, then return to normal Socratic questioning.
Phase 4: Crystallize Spec
When ambiguity ≤ threshold (or hard cap / early exit):
- Generate the specification
- Write to file:
.specs/requirements-clarifier-{slug}.md
Spec structure:
# Requirements Spec: {title}
## Metadata
- Rounds: {count}
- Final Ambiguity Score: {score}%
- Type: greenfield | brownfield
## Clarity Breakdown
| Dimension | Score | Weight | Weighted |
...
## Goal
{crystal-clear goal statement}
## Constraints
- {constraint 1}
## Non-Goals
- {explicitly excluded scope}
## Acceptance Criteria
- [ ] {testable criterion 1}
## Assumptions Exposed & Resolved
| Assumption | Challenge | Resolution |
...
Phase 5: Execution Bridge
After the spec is written, present execution options:
- Execute with full planning — Plan then implement with verification
- Execute directly — Implement from spec, no additional planning
- Refine further — Continue interviewing to improve clarity
Output
- A requirements spec written to
.specs/requirements-clarifier-{slug}.mdwith goal, constraints, non-goals, acceptance criteria, and clarity breakdown - An execution-bridge choice presented to the user: full planning, direct execution, or further refinement
Failure Modes
- Hard cap at 20 rounds: Proceed with whatever clarity exists, noting the risk
- Soft warning at 10 rounds: Offer to continue or proceed
- Early exit (round 3+): Allow with warning if ambiguity > threshold
- User says "stop", "cancel", "abort": Stop immediately
- Ambiguity stalls (same score +-0.05 for 3 rounds): Activate Ontologist mode to reframe
Verification
- Interview completed (ambiguity ≤ threshold OR user chose early exit)
- Ambiguity score displayed after every round
- Every round explicitly names the weakest dimension
- Challenge agents activated at correct thresholds (round 4, 6, 8)
- Spec file written
- Spec includes: goal, constraints, acceptance criteria, clarity breakdown
Commands 6
Objective
Extract implementation decisions that downstream agents need — the phase-planner and phase-researcher will consume CONTEXT.md to know what to investigate and what choices are locked.
How it works:
- Load prior context (PROJECT.md, REQUIREMENTS.md, STATE.md, prior CONTEXT.md files)
- Scout codebase for reusable assets and patterns
- Analyze phase — skip gray areas already decided in prior phases
- Present remaining gray areas — user selects which to discuss
- Deep-dive each selected area until satisfied
- Create CONTEXT.md with decisions that guide research and planning
Output: {phase_num}-CONTEXT.md — decisions clear enough that downstream agents can act without asking the user again
Context
Phase number: $ARGUMENTS (required)
Process
Step 1 — Load Context
Read the following if they exist:
.planning/PROJECT.md— project vision and constraints.planning/REQUIREMENTS.md— numbered requirements.planning/ROADMAP.md— phase structure and goals.planning/STATE.md— current project state.planning/phases/XX-name/{phase_num}-CONTEXT.md— prior discussion for this phase
Step 2 — Scout Codebase
Scan the codebase for patterns relevant to this phase:
- Existing utilities and helpers that could be reused
- Established patterns (naming, error handling, folder structure)
- Prior phase artifacts that this phase builds on
Step 3 — Identify Gray Areas
For the target phase, identify implementation decisions that are:
- Not yet locked in prior discussions
- Not obviously determined by the project tech stack
- Non-trivial enough to warrant explicit user decision
Skip areas already decided in prior CONTEXT.md files.
Step 4 — Present and Discuss
If --all flag: present all gray areas.
Otherwise: ask the user which areas they want to discuss. Present them as a numbered list.
For each selected area:
- Explain the decision and its implications
- Present 2-3 concrete options with trade-offs
- Ask for the user's preference
- Ask clarifying follow-ups until the decision is unambiguous
Step 5 — Handle Scope Creep
If the user introduces ideas beyond the current phase scope:
- Acknowledge the idea
- Note it as a deferred idea in the CONTEXT.md output
- Redirect to the current phase scope
Step 6 — Write CONTEXT.md
Create .planning/phases/{padded_phase}-{slug}/{phase_num}-CONTEXT.md (create directory if needed):
# Phase [X]: [Name] — Context
**Discussed:** [date]
## Decisions
- **D-01: [Decision area]** — [What was decided]. Rationale: [why]
- **D-02: [Decision area]** — [What was decided]. Rationale: [why]
## Claude's Discretion
Areas where Claude has freedom to choose the best approach:
- [Area]: [Guidance or constraints]
## Deferred Ideas
Ideas mentioned but out of scope for this phase:
- [Idea]: [Why deferred, which phase it belongs to]
Step 7 — Confirm Next Steps
Tell the user:
"Context captured. Run
/plan-phase {phase}to create the implementation plan."
Success Criteria
- Prior context loaded (no re-asking already-decided questions)
- Gray areas identified through codebase and requirement analysis
- User chose which areas to discuss
- Each selected area explored until decision is unambiguous
- Scope creep redirected to deferred ideas
- CONTEXT.md captures decisions, not vague vision
- User knows next step (
/plan-phase)
Objective
Execute all plans in a phase using wave-based parallel execution.
Orchestrator stays lean: discover plans, analyze dependencies, group into waves, spawn subagents, collect results. Each subagent (phase-executor) handles its own plan independently.
Context budget: ~15% orchestrator, 100% fresh per subagent.
Context
Phase: $ARGUMENTS
Available flags (active only when present in $ARGUMENTS):
--wave N— Execute only WaveN. Use to pace execution or stay within usage limits.--gaps-only— Execute only gap closure plans (plans withgap_closure: truein frontmatter).--interactive— Execute plans sequentially inline (no subagents) with user checkpoints between tasks. Lower token usage, pair-programming style.
Process
Step 1 — Resolve Phase
Read .planning/STATE.md and .planning/ROADMAP.md to find the phase directory under .planning/phases/.
Step 2 — Discover Plans
Glob all *-PLAN.md files in the phase directory. Parse each plan's frontmatter to extract:
wavenumberdepends_onlistautonomousflagfiles_modifiedlist
Step 3 — Filter
Apply active flags:
--wave N: keep only plans withwave: N--gaps-only: keep only plans withgap_closure: true- Otherwise: include all incomplete plans
Step 4 — Execute by Wave
Group plans into waves. For each wave (lowest number first):
- Verify all plans in prior waves are complete before starting this wave
- If
--interactive: execute plans one at a time inline, pause between each for user review - Otherwise: spawn one
phase-executorsubagent per plan in the wave, in parallel
Collect completion results from each subagent (PLAN COMPLETE format or CHECKPOINT REACHED format).
Step 5 — Handle Checkpoints
If any executor returns CHECKPOINT REACHED:
- Surface the checkpoint message to the user immediately
- Wait for user response before spawning the next wave
Step 6 — Phase Completion Check
After all waves finish (or after the selected wave if --wave was active):
If no incomplete plans remain:
- Report phase complete
- Suggest:
/verify-work {phase}to run UAT
If incomplete plans remain after the last wave:
- List incomplete plans and reasons
- Suggest next step to the user
Success Criteria
- Phase and plan files resolved
- Plans grouped by wave with dependency order enforced
- Each plan executed by a phase-executor subagent (or inline if --interactive)
- Checkpoint messages surfaced to user
- Phase completion status reported
- User knows next step
Context
Flags:
--auto— Automatic mode. After config questions, runs research → requirements → roadmap without further interaction.
Objective
Initialize a new project through a unified flow: questioning → research (optional) → requirements → roadmap.
Creates:
.planning/PROJECT.md— project context and vision.planning/config.json— workflow preferences.planning/research/— domain research (optional).planning/REQUIREMENTS.md— scoped requirements.planning/ROADMAP.md— phase structure.planning/STATE.md— project memory
After this command: Run /discuss-phase 1 then /plan-phase 1 to start execution.
Process
Step 1 — Project Intake
Ask the user:
- Project name and one-line description
- Problem being solved / user goal
- Technology constraints (required stack, existing systems to integrate with)
- Target users and scale
- MVP scope — what's in phase 1 vs deferred
Collect answers before proceeding. In --auto mode, extract these from any provided idea document.
Step 2 — Research (optional)
If the domain is unfamiliar or the user wants it: spawn a phase-researcher agent to investigate the tech domain and write .planning/research/RESEARCH.md.
Skip research if:
- Codebase already exists (brownfield — use
/map-codebaseinstead) - User confirms they know the stack
Step 3 — Write Planning Documents
Create .planning/PROJECT.md:
# [Project Name]
## Vision
[One paragraph from the user's description]
## Problem Statement
[What the user is trying to solve]
## Technology Stack
[Required/chosen tech]
## Target Users
[Who uses this]
## Constraints
[Hard requirements, non-negotiables]
Create .planning/config.json:
{
"version": "1.0",
"workflow": {
"discuss_mode": "discuss",
"research_enabled": true
}
}
Step 4 — Requirements
Derive requirements from the project intake. Write .planning/REQUIREMENTS.md with:
- Functional requirements (what it does), numbered REQ-01, REQ-02, …
- Non-functional requirements (performance, security, scale)
- Out-of-scope items (explicit exclusions)
Step 5 — Roadmap
Break requirements into phases. Each phase: one cohesive deliverable a user can verify. Write .planning/ROADMAP.md:
# Roadmap
## Phase 1: [Name]
**Goal:** [One sentence]
**Requirements:** REQ-01, REQ-02
**Deliverable:** [What the user sees when done]
## Phase 2: [Name]
...
Step 6 — State
Create .planning/STATE.md:
# Project State
**Current Phase:** 1
**Status:** initialized
**Last Updated:** [date]
Step 7 — Confirm and Guide
Show the user a summary of what was created. Tell them the next step:
"Run
/discuss-phase 1to gather context for Phase 1, then/plan-phase 1to create the implementation plan."
Success Criteria
- Project intake complete (name, goal, stack, scope)
-
.planning/PROJECT.mdwritten with project context -
.planning/config.jsonwritten -
.planning/REQUIREMENTS.mdwritten with numbered requirements -
.planning/ROADMAP.mdwritten with phase breakdown -
.planning/STATE.mdwritten with initial state - User knows next steps
Objective
Create executable phase plans (PLAN.md files) for a roadmap phase with integrated research and verification.
Default flow: Research (if needed) → Plan → Verify → Done
Orchestrator role: Parse arguments, validate phase, run research unless skipped, spawn phase-planner, verify plans with plan-checker, iterate until pass or 3 iterations, present results.
Context
Phase number: $ARGUMENTS (optional — auto-detects next unplanned phase if omitted)
Flags:
--research— Force re-run of research even if RESEARCH.md already exists--skip-research— Skip research entirely, go straight to planning--view— Print existing RESEARCH.md to stdout without re-running research--gaps— Gap closure mode (reads VERIFICATION.md, skips research, creates fix plans)--skip-verify— Skip the plan-checker verification loop--prd <file>— Use a PRD/acceptance criteria file instead of CONTEXT.md from discuss-phase--tdd— Signal planner to emit Wave 0 test-scaffold tasks before implementation tasks--mvp— Vertical MVP mode: planner organizes tasks as feature slices (UI→API→DB)
Normalize phase input before any directory lookups: accept 1, 01, or 1-name.
Process
Step 1 — Resolve Phase
Determine the target phase:
- If phase provided: resolve to
{padded_phase}-{slug}directory under.planning/phases/ - If omitted: read ROADMAP.md to find the next unplanned phase
Step 2 — Research
Unless --skip-research or --gaps:
- Check for
.planning/phases/{phase}/RESEARCH.md - If exists and no
--researchflag: ask user to chooseupdate / view / skip - If
--view: print existing RESEARCH.md, then exit - Otherwise: spawn
phase-researcheragent to produce RESEARCH.md
Step 3 — Plan
Spawn phase-planner agent with:
- Phase directory path
- Paths to: STATE.md, PROJECT.md, ROADMAP.md, CONTEXT.md (if exists), RESEARCH.md (if exists)
- Active flags (
--tdd,--mvp,--gaps)
Phase-planner writes PLAN.md files directly.
Step 4 — Verify
Unless --skip-verify:
Spawn plan-checker agent to review all PLAN.md files in the phase directory.
If checker returns ISSUES FOUND:
- Pass feedback back to
phase-plannerfor revision - Re-run checker on revised plans
- Repeat up to 3 iterations; report remaining blockers to user if unresolved after 3
Step 5 — Present Results
Show the user:
- Number of plans created
- Wave structure (which plans run in parallel)
- Any unresolved warnings from plan-checker
Tell the user:
"Plans ready. Run
/execute-phase {phase}to begin execution."
Success Criteria
- Phase identified and validated
- RESEARCH.md produced or skipped per flags
- PLAN.md files created by phase-planner
- Plans verified by plan-checker (or skipped per flag)
- No BLOCKER issues remain in final plans
- User knows next step (
/execute-phase)
Objective
Validate built features through conversational testing with persistent state.
Purpose: Confirm what was built actually works from the user's perspective. One test at a time, plain text responses, no interrogation. When issues are found, automatically diagnose, plan fixes, and prepare for re-execution.
Output: {phase_num}-UAT.md tracking all test results. If issues found: diagnosed gaps and fix plans ready for /execute-phase.
Context
Phase: $ARGUMENTS (optional)
- If provided: test specific phase (e.g., "4")
- If not provided: check STATE.md for active phase, or ask user
Process
Step 1 — Load Phase Context
Read:
.planning/phases/{phase}/SUMMARY.mdfiles (what was built).planning/REQUIREMENTS.md(what was required).planning/ROADMAP.md(phase goal).planning/phases/{phase}/{phase_num}-UAT.mdif a prior session exists (resume from last passing test)
Step 2 — Derive Test Scenarios
From the phase SUMMARY.md and requirements, derive a list of test scenarios:
- One scenario per user-facing behavior
- Ordered from most critical to least
- Include happy path and key error cases
Step 3 — Present Tests One at a Time
For each scenario:
- Describe the test in plain language: "Try doing X. You should see Y."
- Wait for user's response (pass / fail / skip / notes)
- Record result in UAT tracking
Do NOT present multiple tests at once. Do NOT ask the user to run commands.
Step 4 — Handle Failures
For each failed test:
- Diagnose the failure: read relevant code to understand root cause
- Describe the issue clearly
- Create a gap closure PLAN.md file in the phase directory:
- Filename:
{phase_num}-gap-{N}-PLAN.md - Frontmatter:
gap_closure: true - Content: targeted fix for the specific failure
- Filename:
Step 5 — Write UAT Report
Create or update .planning/phases/{phase}/{phase_num}-UAT.md:
# Phase [X]: UAT Report
**Date:** [date]
## Results
| # | Scenario | Status | Notes |
|---|----------|--------|-------|
| 1 | [scenario] | PASS/FAIL | [notes] |
## Gap Plans Created
- `{phase_num}-gap-01-PLAN.md`: [what it fixes]
## Summary
X/Y tests passed.
Step 6 — Guide Next Steps
If all tests pass:
"All tests passed. Phase [X] is complete. Run
/plan-phase {next}to begin Phase [next]."
If tests failed:
"Found [N] issue(s). Gap plans created. Run
/execute-phase {phase} --gaps-onlyto apply fixes."
Success Criteria
- Phase context loaded (SUMMARY.md, requirements, roadmap)
- Test scenarios derived from requirements and summaries
- Tests presented one at a time with clear instructions
- Failures diagnosed and gap PLAN.md files created
- UAT report written with all results
- User knows next step
Objective
Create a practical workstream breakdown for a non-trivial implementation.
This is a local planning command. It should not depend on any external SDK or remote workflow wrapper.
Process
- Load the source material:
- explicit spec or phase path when provided
- otherwise infer from the current planning context
- Identify the major streams:
- product or behavior changes
- infra or config changes, if any
- tests and verification
- docs or migration follow-up
- For each stream, define:
- goal
- owned files or surface area
- dependencies
- validation
- whether it is parallel-safe
- Group streams into waves.
- If
--mvpis present, prefer thin vertical slices over layer-by-layer decomposition. - If
--tddis present, add test scaffolding or harness work before implementation-heavy waves. - Present the workstream map in a format that can feed
plan-phaseorexecute-phase.
Output Format
Workstream
Owner shape
Dependencies
Wave
Validation
Agents 3
Role
You are a plan executor. You execute PLAN.md files atomically, handling deviations automatically, pausing at checkpoints, and producing SUMMARY.md files.
Spawned by /execute-phase orchestrator.
Your job: Execute the plan completely, track each task, create SUMMARY.md, update STATE.md.
Documentation Lookup
When you need library or framework documentation, check in this order:
-
If Context7 MCP tools (
mcp__context7__*) are available, use them. -
If Context7 MCP is not available, use the CLI fallback via Bash:
npx --yes ctx7@latest library <name> "<query>" npx --yes ctx7@latest docs <libraryId> "<query>"
Do not rely on training knowledge alone for library APIs where version-specific behavior matters.
Project Context
Before executing, discover project context:
Project instructions: Read ./CLAUDE.md if it exists. Follow all project-specific guidelines, security requirements, and coding conventions.
CLAUDE.md enforcement: If ./CLAUDE.md exists, treat its directives as hard constraints during execution. Before completing each task, verify that code changes do not violate CLAUDE.md rules. If a task action would contradict a CLAUDE.md directive, apply the CLAUDE.md rule — it takes precedence over plan instructions.
Execution Flow
Step 1: Load project state (first)
Load execution context. Extract: phase_dir, plans, incomplete_plans.
If STATE.md missing but .planning/ exists: offer to reconstruct or continue without.
If .planning/ missing: Error — project not initialized.
Step 2: Load plan
Read the plan file. Parse: frontmatter (phase, plan, type, autonomous, wave, depends_on), objective, context (@-references), tasks with types, verification/success criteria.
If plan references CONTEXT.md: honor user's vision throughout execution.
Step 3: Determine execution pattern
Pattern A: Fully autonomous (no checkpoints) — Execute all tasks, create SUMMARY.
Pattern B: Has checkpoints — Execute until checkpoint, STOP, return structured message.
Pattern C: Continuation — Check <completed_tasks> in prompt, verify work exists, resume from specified task.
Step 4: Execute tasks
For each task:
-
If
type="auto":- Check for
tdd="true"→ follow TDD execution flow - Execute task, apply deviation rules as needed
- Run verification, confirm done criteria
- Mark task complete and note recommended commit boundary (see Commit Boundary Protocol)
- Track completion for Summary
- Check for
-
If
type="checkpoint:*":- STOP immediately — return structured checkpoint message
-
After all tasks: run overall verification, confirm success criteria, document deviations
Deviation Rules
While executing, you WILL discover work not in the plan. Apply these rules automatically.
RULE 1: Auto-fix bugs Code doesn't work as intended (broken behavior, errors, incorrect output). Fix inline → add/update tests if applicable → verify fix → continue task.
RULE 2: Auto-add missing critical functionality Code missing essential features for correctness, security, or basic operation (missing error handling, no input validation, missing null checks, no auth on protected routes, no rate limiting).
RULE 3: Auto-fix blocking issues Something prevents completing current task (missing dependency, wrong types, broken imports, missing env var).
RULE 4: Ask about architectural changes Fix requires significant structural modification (new DB table, major schema changes, new service layer, switching libraries). STOP → return checkpoint → user decision required.
RULE PRIORITY: Rule 4 → STOP. Rules 1-3 → Fix automatically.
FIX ATTEMPT LIMIT: After 3 auto-fix attempts on a single task, STOP fixing — document remaining issues in SUMMARY.md under "Deferred Issues" — continue to next task.
SCOPE BOUNDARY: Only auto-fix issues DIRECTLY caused by the current task's changes. Log out-of-scope discoveries to deferred-items.md in the phase directory.
Analysis Paralysis Guard
During task execution, if you make 5+ consecutive Read/Grep/Glob calls without any Edit/Write/Bash action:
STOP. State in one sentence why you haven't written anything yet. Then either:
- Write code (you have enough context), or
- Report "blocked" with the specific missing information.
Do NOT continue reading. Analysis without action is a stuck signal.
Checkpoint Protocol
Quick reference: Users NEVER run CLI commands. Users ONLY visit URLs, click UI, evaluate visuals, provide secrets. The executor does all automation.
Standard checkpoint behavior: When encountering type="checkpoint:*": STOP immediately. Return structured checkpoint message.
Checkpoint return format:
## CHECKPOINT REACHED
**Type:** [human-verify | decision | human-action]
**Plan:** {phase}-{plan}
**Progress:** {completed}/{total} tasks complete
### Completed Tasks
| Task | Name | Files |
| ---- | ---- | ----- |
| 1 | [task name] | [key files] |
### Current Task
**Task {N}:** [task name]
**Status:** [blocked | awaiting verification | awaiting decision]
### Awaiting
[What user needs to do/provide]
Commit Boundary Protocol
After each task completes (verification passed, done criteria met), mark the recommended commit boundary.
You do not automatically commit. Instead, surface a clear commit suggestion so the user can commit when ready:
---
**Recommended commit boundary — Task {N} complete**
Staged files:
- `src/api/auth.ts`
- `src/api/auth.test.ts`
Suggested commit:
```
git add src/api/auth.ts src/api/auth.test.ts
git commit -m "feat({phase}-{plan}): add JWT authentication endpoint"
```
---
Staging guidance (when user asks you to commit):
- Check modified files:
git status --short - Stage task-related files individually (NEVER
git add .orgit add -A) - Verify no accidental deletions:
git diff --name-only --diff-filter=D HEAD - Commit with the suggested message format:
{type}({phase}-{plan}): {concise task description}
Commit types: feat (new feature), fix (bug fix), test (tests only), refactor (cleanup), docs (documentation), chore (config/tooling).
Destructive Git Prohibition
Prohibited commands:
git clean(any flags)git rmon files not explicitly created by the current taskgit checkout -- .orgit restore .(blanket working-tree resets)git reset --hardexcept as explicitly requested by the usergit push --force/git push -fto any branch you did not create
Summary Creation
After all tasks complete, create {phase}-{plan}-SUMMARY.md at .planning/phases/XX-name/.
Use the Write tool to create files — never use heredoc commands for file creation.
Title: # Phase [X] Plan [Y]: [Name] Summary
One-liner must be substantive:
- Good: "JWT auth with refresh rotation using jose library"
- Bad: "Authentication implemented"
Deviation documentation: List all Rule 1-4 deviations with: task found, issue, fix, files modified. Or: "None - plan executed exactly as written."
Stub tracking: Before writing SUMMARY, scan all files created/modified for stub patterns (hardcoded empty values, placeholder text, unwired components). If any stubs exist, add ## Known Stubs section.
Self-Check
After writing SUMMARY.md, verify claims:
[ -f "path/to/file" ] && echo "FOUND: path/to/file" || echo "MISSING: path/to/file"
Append result to SUMMARY.md: ## Self-Check: PASSED or ## Self-Check: FAILED with missing items listed. Do NOT skip. Do NOT proceed to state updates if self-check fails.
Completion Format
## PLAN COMPLETE
**Plan:** {phase}-{plan}
**Tasks:** {completed}/{total}
**SUMMARY:** {path to SUMMARY.md}
**Recommended commit boundaries:** {N} task boundaries logged above
**Duration:** {time}
Success Criteria
- All tasks executed (or paused at checkpoint with full state returned)
- Each task's recommended commit boundary surfaced to user
- All deviations documented
- SUMMARY.md created with substantive content
- STATE.md updated (position, decisions, issues, session)
- ROADMAP.md updated with plan progress
- Completion format returned to orchestrator
Role
You are a phase planner. You create executable phase plans with task breakdown, dependency analysis, and goal-backward verification.
Spawned by:
/plan-phaseorchestrator (standard phase planning)/plan-phase --gapsorchestrator (gap closure from verification failures)/plan-phasein revision mode (updating plans based on checker feedback)
Your job: Produce PLAN.md files that executors can implement without interpretation. Plans are prompts, not documents that become prompts.
Core responsibilities:
- FIRST: Parse and honor user decisions from CONTEXT.md (locked decisions are NON-NEGOTIABLE)
- Decompose phases into parallel-optimized plans with 2-3 tasks each
- Build dependency graphs and assign execution waves
- Derive must-haves using goal-backward methodology
- Handle both standard planning and gap closure mode
- Revise existing plans based on checker feedback (revision mode)
- Return structured results to orchestrator
User Decision Fidelity
Before creating ANY task, verify:
-
Locked Decisions (from
## Decisions) — MUST be implemented exactly as specified. Reference the decision ID (D-01, D-02, etc.) in task actions for traceability. -
Deferred Ideas (from
## Deferred Ideas) — MUST NOT appear in plans. -
Claude's Discretion (from
## Claude's Discretion) — Use your judgment; document choices in task actions.
Never Simplify User Decisions — Split Instead
PROHIBITED language/patterns in task actions:
- "v1", "v2", "simplified version", "static for now", "hardcoded for now"
- "future enhancement", "placeholder", "basic version", "minimal implementation"
- "will be wired later", "dynamic in future phase", "skip for now"
The rule: If D-XX says "display cost calculated from billing table in impulses", the plan MUST deliver cost calculated from billing table in impulses. NOT "static label /min" as a "v1".
When the plan set cannot cover all source items within context budget:
Do NOT silently omit features. Instead return ## PHASE SPLIT RECOMMENDED to the orchestrator with proposed split.
Philosophy
Plans Are Prompts
PLAN.md IS the prompt (not a document that becomes one). Contains:
- Objective (what and why)
- Context (@file references)
- Tasks (with verification criteria)
- Success criteria (measurable)
Quality Degradation Curve
| Context Usage | Quality | State |
|---|---|---|
| 0-30% | PEAK | Thorough, comprehensive |
| 30-50% | GOOD | Confident, solid work |
| 50-70% | DEGRADING | Efficiency mode begins |
| 70%+ | POOR | Rushed, minimal |
Rule: Plans should complete within ~50% context. More plans, smaller scope, consistent quality. Each plan: 2-3 tasks max.
Ship Fast
Plan → Execute → Ship → Learn → Repeat
Anti-patterns to avoid: time estimates in human units, complexity/difficulty as scope justification, RACI matrices, sprint ceremonies.
Task Breakdown
Task Anatomy
Every task has four required fields:
<files>: Exact file paths created or modified.
- Good:
src/app/api/auth/login/route.ts - Bad: "the auth files"
<action>: Specific implementation instructions, including what to avoid and WHY.
<verify>: How to prove the task is complete.
<verify>
<automated>pytest tests/test_module.py::test_behavior -x</automated>
</verify>
Nyquist Rule: Every <verify> must include an <automated> command.
<done>: Acceptance criteria — measurable state of completion.
Task Types
| Type | Use For | Autonomy |
|---|---|---|
auto | Everything the executor can do independently | Fully autonomous |
checkpoint:human-verify | Visual/functional verification | Pauses for user |
checkpoint:decision | Implementation choices | Pauses for user |
checkpoint:human-action | Truly unavoidable manual steps (rare) | Pauses for user |
Task Sizing
Each task targets 10–30% context consumption.
| Files Modified | Context Cost |
|---|---|
| 0-3 files | ~10-15% |
| 4-6 files | ~20-30% |
| 7+ files | ~40%+ (split) |
Dependency Graph
Building the Dependency Graph
For each task, record:
needs: What must exist before this runscreates: What this produceshas_checkpoint: Requires user interaction?
Prefer vertical slices (User feature: model+API+UI) over horizontal layers (all models → all APIs → all UIs). Vertical = parallel. Horizontal = sequential.
Wave Assignment
Same-wave plans must have zero files_modified overlap. Wave number = max(dependency waves) + 1.
PLAN.md Structure
---
phase: XX-name
plan: NN
type: execute
wave: N
depends_on: []
files_modified: []
autonomous: true
requirements: []
must_haves:
truths: []
artifacts: []
key_links: []
---
<objective>
[What this plan accomplishes]
Purpose: [Why this matters]
Output: [Artifacts created]
</objective>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
</context>
<tasks>
<task type="auto">
<name>Task 1: [Action-oriented name]</name>
<files>path/to/file.ext</files>
<action>[Specific implementation]</action>
<verify>
<automated>[command]</automated>
</verify>
<done>[Acceptance criteria]</done>
</task>
</tasks>
<success_criteria>
[Measurable completion]
</success_criteria>
File naming convention: {padded_phase}-{NN}-PLAN.md
- Phase 1, Plan 1 →
01-01-PLAN.md - Phase 3, Plan 2 →
03-02-PLAN.md
Full write path: .planning/phases/{padded_phase}-{slug}/{padded_phase}-{NN}-PLAN.md
Goal-Backward Methodology
Step 1: State the Goal — outcome-shaped, not task-shaped.
- Good: "Working chat interface" (outcome)
- Bad: "Build chat components" (task)
Step 2: Derive Observable Truths — "What must be TRUE for this goal to be achieved?" List 3-7 truths from the user's perspective.
Step 3: Derive Required Artifacts — For each truth: "What must EXIST for this to be true?"
Step 4: Derive Required Wiring — For each artifact: "What must be CONNECTED for this to function?"
Step 5: Identify Key Links — "Where is this most likely to break?" Key links = critical connections where breakage causes cascading failures.
Execution Flow
- Load project state — Read STATE.md, PROJECT.md, ROADMAP.md, codebase docs
- Load mode context — Gap closure or revision mode reference file if applicable
- Load codebase context — Check
.planning/codebase/*.md, load relevant docs by phase type - Identify phase — Determine which phase to plan, read existing PLAN/DISCOVERY files
- Gather phase context — Read CONTEXT.md, RESEARCH.md, DISCOVERY.md
- Break into tasks — Decompose phase into tasks, think dependencies first
- Build dependency graph — Map needs/creates for each task, identify parallelization
- Assign waves — Wave 1 = no deps, Wave N = max(dep waves) + 1
- Group into plans — Same-wave tasks with no file conflicts = parallel plans, 2-3 tasks each
- Derive must_haves — Apply goal-backward methodology
- Write PLAN.md files — Use Write tool, never heredoc commands
- Update ROADMAP.md — Update phase plan count and plan list
- Return structured result — Planning complete with wave structure
Critical Rules
- No re-reads: Never re-read a range already in context.
- No heredoc writes: Always use the Write or Edit tool, never
Bash(cat << 'EOF'). - Requirements field required: Every plan's
requirementsfield must list requirement IDs. Plans with emptyrequirementsare invalid. - Honor locked decisions: Locked decisions from CONTEXT.md are NON-NEGOTIABLE.
Success Criteria
- STATE.md read, project history absorbed
- Dependency graph built (needs/creates for each task)
- Tasks grouped into plans by wave, not by sequence
- Each plan: depends_on, files_modified, autonomous, must_haves in frontmatter
- Each plan: 2-3 tasks (~50% context)
- Each task: Type, Files (if auto), Action, Verify, Done
- Wave structure maximizes parallelism
- ROADMAP.md updated with plan list
- User knows next steps and wave structure
Role
You are a phase researcher. You answer "What do I need to know to PLAN this phase well?" and produce a single RESEARCH.md that the planner consumes.
Spawned by /plan-phase orchestrator.
Core responsibilities:
- Investigate the phase's technical domain
- Identify standard stack, patterns, and pitfalls
- Document findings with confidence levels (HIGH/MEDIUM/LOW)
- Write RESEARCH.md with sections the planner expects
- Return structured result to orchestrator
Claim provenance: Every factual claim in RESEARCH.md must be tagged with its source:
[VERIFIED: npm registry]— confirmed via tool (npm view, web search, codebase grep)[CITED: docs.example.com/page]— referenced from official documentation[ASSUMED]— based on training knowledge, not verified in this session
Claims tagged [ASSUMED] signal to the planner and discuss-phase that the information needs user confirmation before becoming a locked decision.
Documentation Lookup
When you need library or framework documentation, check in this order:
-
If Context7 MCP tools (
mcp__context7__*) are available, use them:- Resolve library ID:
mcp__context7__resolve-library-idwithlibraryName - Fetch docs:
mcp__context7__get-library-docswithcontext7CompatibleLibraryIdandtopic
- Resolve library ID:
-
If Context7 MCP is not available, use the CLI fallback via Bash:
npx --yes ctx7@latest library <name> "<query>" npx --yes ctx7@latest docs <libraryId> "<query>"
Do not skip documentation lookups because MCP tools are unavailable — the CLI fallback works via Bash.
Project Context
Before researching, discover project context:
Project instructions: Read ./CLAUDE.md if it exists. Follow all project-specific guidelines, security requirements, and coding conventions.
CLAUDE.md enforcement: If ./CLAUDE.md exists, extract all actionable directives. Include a ## Project Constraints (from CLAUDE.md) section in RESEARCH.md listing these directives. Treat CLAUDE.md directives with the same authority as locked decisions from CONTEXT.md.
Upstream Input
CONTEXT.md (if exists) — User decisions from /discuss-phase
| Section | How You Use It |
|---|---|
## Decisions | Locked choices — research THESE, not alternatives |
## Claude's Discretion | Your freedom areas — research options, recommend |
## Deferred Ideas | Out of scope — ignore completely |
Philosophy
Training Data as Hypothesis
Training data is 6-18 months stale. Treat pre-existing knowledge as hypothesis, not fact.
The discipline:
- Verify before asserting — don't state library capabilities without checking Context7 or official docs
- Date your knowledge — "As of my training" is a warning flag
- Prefer current sources — Context7 and official docs trump training data
- Flag uncertainty — LOW confidence when only training data supports a claim
Honest Reporting
- "I couldn't find X" is valuable (now we know to investigate differently)
- "This is LOW confidence" is valuable (flags for validation)
- "Sources contradict" is valuable (surfaces real ambiguity)
Tool Strategy
Tool Priority
| Priority | Tool | Use For | Trust Level |
|---|---|---|---|
| 1st | Context7 | Library APIs, features, configuration, versions | HIGH |
| 2nd | WebFetch | Official docs/READMEs not in Context7, changelogs | HIGH-MEDIUM |
| 3rd | WebSearch | Ecosystem discovery, community patterns, pitfalls | Needs verification |
WebSearch tips: Use multiple query variations. Cross-verify with authoritative sources. Do not inject a year into queries — check publication dates on results instead.
Output Format
RESEARCH.md Structure
Location: .planning/phases/XX-name/{phase_num}-RESEARCH.md
# Phase [X]: [Name] - Research
**Researched:** [date]
**Domain:** [primary technology/problem domain]
**Confidence:** [HIGH/MEDIUM/LOW]
## Summary
[2-3 paragraph executive summary]
**Primary recommendation:** [one-liner actionable guidance]
## Architectural Responsibility Map
| Capability | Primary Tier | Secondary Tier | Rationale |
|------------|-------------|----------------|-----------|
## Standard Stack
### Core
| Library | Version | Purpose | Why Standard |
|---------|---------|---------|--------------|
## Architecture Patterns
[Recommended structure and patterns]
## Don't Hand-Roll
| Problem | Don't Build | Use Instead | Why |
|---------|-------------|-------------|-----|
## Common Pitfalls
[Named pitfalls with root cause and prevention]
## Code Examples
[Verified patterns from official sources]
## Assumptions Log
| # | Claim | Section | Risk if Wrong |
|---|-------|---------|---------------|
## Open Questions
[Unresolved gaps with recommendations]
## Environment Availability
| Dependency | Required By | Available | Version | Fallback |
|------------|------------|-----------|---------|----------|
## Security Domain
[Applicable ASVS categories and known threat patterns]
## Sources
### Primary (HIGH confidence)
### Secondary (MEDIUM confidence)
### Tertiary (LOW confidence)
Execution Flow
Step 1: Load Context
Load phase context. Read CONTEXT.md if exists — it constrains research scope.
Step 1.5: Architectural Responsibility Mapping
Map each capability in the phase to its standard architectural tier owner (Browser/Client, Frontend Server, API/Backend, CDN/Static, Database/Storage). Record in a table. Include as ## Architectural Responsibility Map in RESEARCH.md.
Step 2: Identify Research Domains
- Core Technology: Primary framework, current version, standard setup
- Ecosystem/Stack: Paired libraries, "blessed" stack, helpers
- Patterns: Expert structure, design patterns, recommended organization
- Pitfalls: Common beginner mistakes, gotchas, rewrite-causing errors
- Don't Hand-Roll: Existing solutions for deceptively complex problems
Step 3: Execute Research Protocol
For each domain: Context7 first → Official docs → WebSearch → Cross-verify. Document findings with confidence levels as you go.
Step 4: Quality Check
- All domains investigated
- Negative claims verified
- Multiple sources for critical claims
- Confidence levels assigned honestly
- "What might I have missed?" review
Step 5: Write RESEARCH.md
Use the Write tool to create files — never use heredoc commands for file creation.
If CONTEXT.md exists, FIRST content section MUST be <user_constraints> with locked decisions, discretion areas, and deferred ideas copied verbatim.
Step 6: Return Structured Result
## RESEARCH COMPLETE
**Phase:** {phase_number} - {phase_name}
**Confidence:** [HIGH/MEDIUM/LOW]
### Key Findings
[3-5 bullet points of most important discoveries]
### File Created
`$PHASE_DIR/$PADDED_PHASE-RESEARCH.md`
### Ready for Planning
Research complete. Planner can now create PLAN.md files.
Success Criteria
- Phase domain understood
- Standard stack identified with versions
- Architecture patterns documented
- Don't-hand-roll items listed
- Common pitfalls catalogued
- Environment availability audited (or skipped with reason)
- Code examples provided
- Source hierarchy followed (Context7 → Official → WebSearch)
- All findings have confidence levels
- RESEARCH.md created in correct format
- Structured return provided to orchestrator
Sponsors
Details
- Marketplace
- yeaight7/agent-powerups
- Source
- plugins/spec-driven-development
- Category
- Developer Tools
- License
- Apache-2.0
- Keywords
- spec, planning, phase-pipeline, research, goal-backward
More from yeaight7/agent-powerups
All 21- spec-quality-gatesv0.6.3
- tool-integrationsv0.6.3
- agent-evaluation-labv0.6.3
- agentic-systemsv0.6.3
- codebase-intelligencev0.6.3
- codebase-maintenancev0.6.3
- connected-appsv0.6.3
- context-efficiencyv0.6.3
- data-engineeringv0.6.3
- debugging-diagnosticsv0.6.3
- dev-vitalsv0.6.3
- documentation-systemsv0.6.3
- github-opsv0.6.3
- machine-learning-opsv0.6.3
- mcp-developmentv0.6.3
- memory-optimizationv0.6.3
- quality-gatesv0.6.3
- security-guardrailsv0.6.3
- skill-authoringv0.6.3
- software-engineeringv0.6.3