writing-plans

Writing Plans

Create executable implementation plans that reduce ambiguity for whoever executes them using Superpower Loop for continuous iteration.

CRITICAL: First Action - Start Superpower Loop NOW

Resolve the design path and start the loop immediately — do NOT read design files, explore the codebase, or do anything else first.

1. Resolve the design path:
   • If $ARGUMENTS provides a path (e.g., docs/plans/YYYY-MM-DD-topic-design/), use it
   • Otherwise, search docs/plans/ for the most recent *-design/ folder matching YYYY-MM-DD-*-design/
   • If found without explicit argument, confirm with user: "Use this design: [path]?"
   • If not found or user declines, ask the user for the design folder path
2. Immediately run:

"${CLAUDE_PLUGIN_ROOT}/scripts/setup-superpower-loop.sh" "Write an implementation plan for: <resolved-design-path>. Continue progressing through the superpowers:writing-plans skill phases: Phase 1 (Plan Structure) → Phase 2 (Task Decomposition) → Phase 3 (Validation) → Phase 4 (Plan Reflection) → Phase 5 (Git Commit) → Phase 6 (Transition)." --completion-promise "PLAN_COMPLETE" --max-iterations 50

3. Only after the loop is running, proceed with Initialization below

The loop enables self-referential iteration throughout the planning process.

Superpower Loop Integration

This skill uses Superpower Loop to enable self-referential iteration throughout the planning process.

CRITICAL: Throughout the process, you MUST output <promise>PLAN_COMPLETE</promise> only when:

• Phase 1-4 (Plan Structure, Task Decomposition, Validation, Plan Reflection) are all complete
• Plan folder created with all task files
• User approval received in Phase 3
• Git commit completed

Do NOT output the promise until ALL conditions are genuinely TRUE.

ABSOLUTE LAST OUTPUT RULE: The promise tag MUST be the very last text you output. Output any transition messages or instructions to the user BEFORE the promise tag. Nothing may follow <promise>PLAN_COMPLETE</promise>.

Initialization

(The Superpower Loop and design path were resolved in the first action above — do NOT start the loop again)

1. Design Check: Verify the folder contains _index.md and bdd-specs.md.
2. Context: Read bdd-specs.md completely. This is the source of truth for your tasks.

The loop will continue through all phases until <promise>PLAN_COMPLETE</promise> is output.

Background Knowledge

Core Concept: Explicit over implicit, granular tasks, verification-driven, context independence. PROHIBITED: Do not generate implementation bodies — no function logic, no algorithm code. ALLOWED: Interface signatures and type definitions that define the contract.

• MANDATORY: Tasks must be driven by BDD scenarios (Given/When/Then).
• MANDATORY: Test-First (Red-Green) workflow. Verification tasks must precede implementation tasks.
• MANDATORY: When plans include unit tests, require external dependency isolation with test doubles (DB/network/third-party APIs).
• PROHIBITED: Do not generate implementation bodies — no function logic, no algorithm code.
• ALLOWED: Interface signatures, type definitions, and function signatures that define the contract (e.g., async function improve(params: ImproveParams): Promise<Result>).
• MANDATORY: One task per file. Each task gets its own .md file.
• MANDATORY: _index.md contains overview and references to all task files.

Phase 1: Plan Structure

Define goal, architecture, constraints, and context.

1. Read Specs: Read bdd-specs.md from the design folder (generated by superpowers:brainstorming).
2. Draft Structure: Use ./references/plan-structure-template.md to outline the plan.
3. Write Context Section: Populate the ## Context section in _index.md:
   • State why this work is needed (motivation, constraints, prior incidents).
   • If modifying existing code, add a current-state vs target-state comparison table covering key dimensions (module structure, API shape, behavior, etc.). Omit the table for greenfield work.

Phase 2: Task Decomposition

Break into small tasks mapped to specific BDD scenarios.

1. Reference Scenarios: CRITICAL: Every task must explicitly include the full BDD Scenario content in the task file using Gherkin syntax. For example:

   ## BDD Scenario
   
   Scenario: [concise scenario title]
     Given [context or precondition]
     When [action or event occurs]
     Then [expected outcome]
     And [additional conditions or outcomes]
   

   The scenario content should be self-contained in the task file, not just a reference to bdd-specs.md. This allows the executor to see the complete scenario without switching files.

2. Define Verification: CRITICAL: Verification steps must run the BDD specs (e.g., npm test tests/login.spec.ts).

3. Enforce Ordering: For each feature NNN, the test task (task-NNN-<feature>-test) must precede its paired impl task (task-NNN-<feature>-impl) via depends-on.

4. Declare Dependencies: MANDATORY: Each task file must include a **depends-on** field listing only true technical prerequisites — tasks whose output is required before this task can start. Rules:

   • A test task (Red) for feature X has no dependency on test tasks for other features
   • An implementation task (Green) depends only on its paired test task (Red), not on other features' implementations
   • Tasks that touch different files and test different scenarios are independent by default
   • PROHIBITED: Do not chain tasks sequentially just to impose execution order — use depends-on only when there is a real technical reason (e.g., "implement auth middleware" must precede "implement protected route test")

5. Create Task Files: MANDATORY: Create one .md file per task. Filename pattern: task-<NNN>-<feature>-<type>.md.

   • Example: task-001-setup.md, task-002-feature-test.md, task-002-feature-impl.md
   • <NNN>: Sequential number (001, 002, ...)
   • <feature>: Feature identifier (e.g., auth-handler, user-profile)
   • <type>: Type (test, impl, config, refactor)
   • Test and implementation tasks for the same feature share the same NN prefix, e.g., 002-feature-test and 002-feature-impl

6. Describe What, Not How: PROHIBITED: Do not generate implementation bodies. Describe what to implement (e.g., "Create a function that validates user credentials"). ALLOWED: Include interface signatures to define contracts (e.g., def validate_credentials(username: str, password: str) -> bool: ...), but never the body logic.

Phase 3: Validation & Documentation

Verify completeness, confirm with user, and save.

1. Verify: Check for valid commit boundaries and no vague tasks.
2. Confirm: Use AskUserQuestion to get user approval on the plan. AskUserQuestion pauses within the turn, ensuring the user can respond before the loop re-injects.
3. Save: Write to docs/plans/YYYY-MM-DD-<topic>-plan/ folder.
   • CRITICAL: _index.md MUST include "Execution Plan" section with inline YAML metadata (see template in ./references/plan-structure-template.md)
   • CRITICAL: _index.md MUST include "Task File References" section with links to full task files for detailed BDD scenarios
   • CRITICAL: _index.md MUST include "BDD Coverage" section confirming all scenarios are covered
   • CRITICAL: _index.md MUST include "Dependency Chain" section with visual dependency graph (will be populated in Phase 4)
   • Example YAML metadata:

     tasks:
       - id: "001"
         subject: "Setup project structure"
         slug: "setup-project-structure"
         type: "setup"
         depends-on: []
       - id: "002"
         subject: "Whale Discovery Test"
         slug: "whale-discovery-test"
         type: "test"
         depends-on: ["001"]
       - id: "003"
         subject: "Whale Discovery Impl"
         slug: "whale-discovery-impl"
         type: "impl"
         depends-on: ["002"]
     

   • Example file reference: - [Task 002: Whale Discovery Test](./task-002-whale-discovery-test.md)

Phase 4: Plan Reflection

Before committing, verify plan quality. Scale reflection based on plan size.

Small plans (up to 6 tasks): Main agent performs a single review pass — check BDD coverage, dependency graph, and task completeness sequentially. No sub-agents needed.

Medium plans (7-15 tasks, 2 sub-agents):

Sub-agent 1: BDD Coverage & Completeness Review

• Focus: Verify BDD scenario coverage AND task structure completeness
• Output: Coverage matrix, incomplete tasks, missing sections

Sub-agent 2: Dependency Graph Review

• Focus: Verify depends-on fields, check for cycles, identify missing dependencies
• Output: Dependency graph, cycle detection, incorrect dependencies

Large plans (16+ tasks, 3+ sub-agents):

Sub-agent 1: BDD Coverage Review

• Focus: Verify every BDD scenario from design has corresponding tasks
• Output: Coverage matrix, orphaned scenarios, extra tasks without scenarios

Sub-agent 2: Dependency Graph Review

• Focus: Verify depends-on fields are correct, check for cycles, identify missing dependencies
• Output: Dependency graph, cycle detection, incorrect dependencies

Sub-agent 3: Task Completeness Review

• Focus: Verify each task has required structure (BDD scenario, files, steps, verification)
• Output: Incomplete tasks list, missing sections by task

Additional sub-agents (launch as needed): Red-Green Pairing Review, File Conflict Review.

Integrate and Update:

1. Collect all sub-agent findings
2. Prioritize issues by impact
3. Update plan files to fix issues
4. MANDATORY: Add dependency graph from Sub-agent 2 to _index.md in "Dependency Chain" section
5. Re-verify updated sections
6. Confirm with user: Use AskUserQuestion to present the reflection summary and get approval before committing

Output: Updated plan with issues resolved, dependency graph included in _index.md, and user approval received.

See ./references/plan-reflection.md for sub-agent prompts and integration workflow.

Phase 5: Git Commit

Commit the plan folder using git-agent (with git fallback).

Actions:

1. Stage the entire folder: git add docs/plans/YYYY-MM-DD-<topic>-plan/
2. Run: git-agent commit --no-stage --intent "add implementation plan for <topic>" --co-author "Claude <Model> <Version> <noreply@anthropic.com>"
3. On auth error, retry with --free flag
4. Fallback: If git-agent is unavailable or fails, use git commit -m "docs: add implementation plan for <topic> ..." with conventional format

See ../../skills/references/git-commit.md for detailed patterns.

Phase 6: Transition to Execution

Prompt the user to use superpowers:executing-plans, then output the promise as the absolute last line.

Output in this exact order:

1. Transition message: "Plan complete. To execute this plan, use /superpowers:executing-plans."
2. <promise>PLAN_COMPLETE</promise> — nothing after this

PROHIBITED: Do NOT offer to start implementation directly. Do NOT output any text after the promise tag.

Exit Criteria

Plan created with clear goal/constraints, decomposed tasks with file lists and verification, BDD steps, commit boundaries, no vague tasks, reflection completed, user approval.

References

• ./references/plan-structure-template.md - Template for plan structure
• ./references/task-granularity-and-verification.md - Guide for task breakdown and verification
• ./references/plan-reflection.md - Sub-agent prompts for plan reflection
• ../../skills/references/git-commit.md - Git commit patterns and requirements
• ../../skills/references/loop-patterns.md - Completion promise design, prompt patterns, and safety nets