Writing Plans

Create executable implementation plans that reduce ambiguity for whoever executes them.

Initialization

1. Resolve Design Path:
   • 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.

Background Knowledge

Core Concept: Explicit over implicit, granular tasks, verification-driven, context independence. PROHIBITED: Do not generate actual code – focus on what to do, not implementation details.

• 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 actual code – describe what to implement, not the implementation itself.
• 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.

1. Read Specs: Read bdd-specs.md from the design folder (generated by brainstorming).
2. Draft Structure: Use ./references/plan-structure-template.md to outline the plan.

Phase 2: Task Decomposition

Break into small tasks mapped to specific BDD scenarios.

1. Reference Scenarios: CRITICAL: Every task must explicitly reference a BDD Scenario (e.g., “Implement Login (ref: Scenario 1)”).
2. Define Verification: CRITICAL: Verification steps must run the BDD specs (e.g., npm test tests/login.spec.ts).
3. Enforce Ordering: Task N (Test/Red) -> Task N+1 (Implementation/Green).
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. Ensure Compatibility: Ensure tasks are compatible with superpowers:behavior-driven-development.
6. Create Task Files: MANDATORY: Create one .md file per task. Filename pattern: task-<NNN>-<short-description>.md.
7. Describe What, Not How: PROHIBITED: Do not generate actual code. Describe what to implement (e.g., “Create a function that validates user credentials”), not the implementation (e.g., “def validate_credentials(username, password): …”).

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 references to all task files
   • Example: - [Task 001: Setup](./task-001-setup.md)

Git Commit

Commit the plan folder to git with proper message format.

See ../../skills/references/git-commit.md for detailed patterns, commit message templates, and requirements.

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

Phase 4: Transition to Execution

Goal: Seamlessly transition to executing the plan.

Actions:

1. Invoke superpowers:executing-plans using the Skill tool, passing the plan folder path as an argument.

Exit Criteria

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

References

• ./references/plan-structure-template.md – Template for plan structure
• ./references/task-granularity-and-verification.md – Guide for task breakdown and verification
• ../../skills/references/git-commit.md – Git commit patterns and requirements