Purpose

Turn a spec into a detailed, executable multi-step implementation plan. Prevents implementation drift and gives any engineer — or agent — enough detail to build without guessing.

When to Use

• Before implementing any multi-subsystem or non-trivial feature.
• When a spec or requirements document exists and needs to become actionable tasks.
• When the implementation requires coordinating multiple files or components.

If the spec covers multiple independent subsystems, break it into separate plans — one per subsystem. Each plan should produce working, testable software on its own.

Inputs

• Spec or requirements document.
• Access to the codebase (for file paths and existing patterns).

Workflow

1. Scope check — Identify all affected subsystems. If multiple independent subsystems, suggest separate plans.

1. Design file structure — Before defining tasks, map which files will be created or modified and what each is responsible for. Units should have clear boundaries, focused responsibility, and well-defined interfaces.

1. Write the plan header:

   # [Feature Name] Implementation Plan

   **Goal:** [One sentence describing what this builds]

   **Architecture:** [2-3 sentences about approach]

   **Tech Stack:** [Key technologies/libraries]

   ---

1. Break work into bite-sized tasks — Each step should take 2–5 minutes:

• "Write the failing test" — step
• "Run it to verify it fails" — step
• "Implement the minimal code to pass the test" — step
• "Run tests and confirm pass" — step
• "Commit" — step

1. Write each task using this structure:

   ### Task N: [Component Name]

   **Files:**
   - Create: `exact/path/to/file.py`
   - Modify: `exact/path/to/existing.py`
   - Test: `tests/exact/path/to/test.py`

   - [ ] **Step 1:** [Action]

Actual code here

   - [ ] **Step 2:** Run: `<exact command>`
     Expected: `<exact output>`

1. No placeholders — These are plan failures; never write them:

   TBD / TODO / implement later / fill in details
   "Add appropriate error handling" / "handle edge cases"
   "Write tests for the above" (without actual test code)
   "Similar to Task N" (repeat the code — engineer may read tasks out of order)
   Steps that describe without showing how (code blocks required for code steps)

1. Self-review before saving:

• Spec coverage: Can you point to a task for every requirement?
• Placeholder scan: No undefined, deferred, or vague steps?
• Type consistency: Do types and method names in later tasks match earlier definitions?

1. Save to docs/plans/YYYY-MM-DD-<feature-name>.md.

Output

A Markdown plan file with:

• Header (goal, architecture, tech stack)
• Tasks with checkbox steps, exact file paths, actual code blocks, exact commands with expected output
• No placeholders of any kind

Verification

• [ ] All spec requirements covered (point to a task for each)
• [ ] No undefined, deferred, or vague steps present
• [ ] File paths are exact (not path/to/file)
• [ ] Tasks are 2–5 minutes each
• [ ] Code blocks contain actual code, not descriptions
• [ ] Commands include expected output
• [ ] Plan saved to docs/plans/

Failure Modes

• Vague tasks — A reader who cannot execute a step without guessing means the task is incomplete.
• Missing spec coverage — Implementation diverges from requirements.
• Placeholder content — Implementation stalls when an engineer hits an undefined or deferred step.
• Stale type references — Function named clearLayers() in Task 3 but clearFullLayers() in Task 7 is a bug in the plan.