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:
```bash
"${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:

   ```gherkin
   ## 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:
     ```yaml
     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