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

THIS MUST BE YOUR FIRST ACTION. Do NOT resolve the design path, do NOT read files, do NOT do anything else until you have started the Superpower Loop.

1. Resolve the design path from $ARGUMENTS (if provided) or by searching docs/plans/
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 to verify the design folder and continue with planning

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 was already started in the critical first action above - do NOT start it again)

1. Resolve Design Path (must complete to build the prompt for the loop above):
   • If $ARGUMENTS provides a path (e.g., docs/plans/YYYY-MM-DD-topic-design/), use it as the design source.
   • If no argument is provided:
     • Search docs/plans/ for the most recent *-design/ folder matching the pattern YYYY-MM-DD-*-design/
     • If found, confirm with user: "Use this design: [path]?"
     • If not found or user declines, ask the user for the design folder path.
2. Design Check: Verify the folder contains _index.md and bdd-specs.md.
3. 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: Get user approval on the plan.
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, launch sub-agents in parallel to verify plan quality and identify gaps.

Core reflection sub-agents (always required):

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 - Verify test tasks have corresponding impl tasks
• File Conflict Review - Identify tasks that modify the same files

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: Present 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 to git with proper message format.

Critical requirements:

• Commit the entire folder: git add docs/plans/YYYY-MM-DD-<topic>-plan/
• Prefix: docs: (lowercase)
• Subject: Under 50 characters, lowercase
• Footer: Co-Authored-By with model name

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/prompt-patterns.md - Writing effective superpower loop prompts for each phase
• ../../skills/references/completion-promises.md - Completion promise design and safety nets