Create Implementation Plan

Generate structured, executable implementation plans with visual diagrams and dependency tracking.

Purpose

Transform requirements into actionable plans that:

• Stay under 5000 tokens (hard cap)
• Include visual diagrams (Mermaid or ASCII)
• Show task/subplan dependencies
• Are numbered sequentially in docs/plans/

When to Use

• Before implementing a new feature
• When refactoring existing code
• For breaking down complex changes
• After brainstorming, before coding

Critical Constraints

Token Limit: Hard Cap 5000

• Optimal: 2000-3000 tokens (fits well in context with code)
• Maximum: 5000 tokens (STOP if exceeded)
• If plan would exceed 5000 tokens, create subplans instead
• Validate with: bun run scripts/validate-plan.ts <plan-file>

Reference, Never Copy

• Reference docs by path only: per docs/standards/validation.md
• NEVER paste external content into the plan
• Only include directly relevant references

Workflow

Phase 1: Gather Requirements

Ask clarifying questions before planning:

1. Scope: What exactly should this feature do?
2. Boundaries: What's explicitly out of scope?
3. Dependencies: What existing code/systems does this touch?
4. Constraints: Any technical requirements or limitations?
5. Success Criteria: How do we know it's done?

Do NOT proceed until you have clear answers.

Phase 2: Explore Codebase

Use the Explore subagent to understand:

• Existing modules and patterns
• Files that will need modification
• Dependencies and integration points
• Documentation that needs updates

Phase 3: Design Architecture

Create diagrams to illustrate:

• Component relationships
• Data/control flow
• State transitions
• Interactions and sequences

Use Mermaid (preferred) or ASCII. Choose the diagram type that best fits:

Flowchart - Component relationships, data flow:

graph TD
    A[Component A] --> B[Component B]
    B --> C[Component C]

Sequence - API calls, interactions between systems:

sequenceDiagram
    Client->>+API: POST /users
    API->>+DB: INSERT user
    DB-->>-API: user record
    API-->>-Client: 201 Created

State - Lifecycle, status transitions:

stateDiagram-v2
    [*] --> Draft
    Draft --> Review
    Review --> Approved
    Review --> Draft: Changes requested
    Approved --> [*]

Class - Object relationships, data models:

classDiagram
    User "1" --> "*" Order
    Order "1" --> "*" LineItem

ASCII - When Mermaid isn't rendered:

┌──────────────┐         ┌──────────────┐
│  Component A │ ──────► │  Component B │
└──────────────┘         └──────────────┘

Phase 4: Plan Tasks

Break work into phases and tasks:

• Each task should be 2-15 minutes
• Include file paths (CREATE/MODIFY/DELETE)
• Add verification steps
• Include commit messages

Phase 5: Check Size & Split

Before writing:

1. Estimate token count (~4 chars = 1 token)
2. If > 3000 tokens, consider splitting
3. If > 5000 tokens, MUST create subplans

Subplan Strategy:

030_feature-initiative.md      (parent overview)
├── 030A_frontend-component.md (subplan A)
├── 030B_backend-api.md        (subplan B)
└── 030C_integration.md        (subplan C)

Phase 6: Define Testing Strategy

Every plan MUST include a testing strategy with:

1. Automated Tests (required)

   • Prefer E2E tests that validate the full feature flow
   • Include integration tests for component interactions
   • Add unit tests for complex logic

2. Manual Validation (required)

   • Step-by-step instructions for human verification
   • What to look for, what to click, what to expect
   • Screenshots or recordings if helpful

## Testing Strategy

### Automated Tests

| Type | What It Tests | Command |
|------|---------------|---------|
| E2E | Full user flow | `bun test:e2e tests/e2e/feature.spec.ts` |
| Integration | API + DB | `bun test tests/integration/` |
| Unit | Core logic | `bun test tests/unit/` |

### Manual Validation

1. Navigate to /settings
2. Click "Preferences" tab
3. Toggle dark mode
4. **Expected:** Theme changes immediately
5. Refresh page
6. **Expected:** Setting persists

Phase 7: Create Dependency Graph

Every plan MUST end with a dependency graph showing:

• Which tasks/subplans can run in parallel
• Which must be sequential
• External prerequisites

graph TD
    subgraph "Prerequisites"
        P1[Prior Plan 029]
    end

    subgraph "This Plan"
        A[Phase 1: Setup] --> B[Phase 2: Core]
        A --> C[Phase 3: Tests]
        B --> D[Phase 4: Integration]
        C --> D
    end

    P1 --> A

Phase 8: Write Plan

Write to: docs/plans/{NNNN}_{FEATURE_NAME}.md

Use the template from assets/plan-template.md.

Phase 9: Validate

Run the validation script:

bun run content/skills/plan-create/scripts/validate-plan.ts docs/plans/{plan-file}.md

Phase 10: Commit Plan

After validation passes, commit the plan and any related artifacts:

git add docs/plans/{plan-file}.md
git add docs/plans/{plan-file}*.md  # Include any subplans
git commit -m "docs(plan): add {NNNN}_{FEATURE_NAME}

- {Brief description of what the plan covers}
- Includes dependency graph and testing strategy

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>"

Always commit immediately after validation to ensure plans are tracked in version control.

Phase 11: Offer Review

After committing, ask:

"Would you like me to run /review-plan to validate this plan before implementation?"

The review-plan skill will:

• Check for completeness and clarity
• Validate dependencies are correct
• Ensure testing strategy is adequate
• Identify potential issues or gaps

Phase 12: Offer Worktree Setup

After plan is complete, ask:

"Would you like me to create a git worktree for implementing this plan?"

Worktrees are created in .worktrees/ named after the plan:

git worktree add .worktrees/0042_user-preferences -b feature/0042_user-preferences

See references/worktree-setup.md for details.

Plan Numbering

1. Check docs/plans/ for the highest existing plan number
2. Use the next sequential number
3. Format: {NNNN}_{FEATURE_NAME}.md (4 digits, zero-padded)

Examples:

• 0001_user-authentication.md
• 0042_api-refactor.md
• 0100_database-migration.md

Output Location

All plans go to: docs/plans/

docs/plans/
├── 0001_initial-setup.md
├── 0002_user-auth.md
├── 0003A_frontend-forms.md
├── 0003B_backend-validation.md
└── 0003C_integration-tests.md

Plan Structure

See assets/plan-template.md for the full template.

Key sections:

1. Header - Status, overview, goals
2. References - Only directly relevant docs
3. Architecture - Mermaid/ASCII diagrams
4. Phases - Numbered tasks with prereqs
5. Files Summary - CREATE/MODIFY/DELETE table
6. Testing Strategy - Automated tests + manual validation (required)
7. Dependency Graph - Required at end
8. Checklist - Completion tracking

Examples

See references/examples.md for complete plan examples.

Validation

Run validation before finalizing:

• Token count under 5000
• Testing strategy present (automated + manual)
• Dependency graph present
• Proper numbering format

Related Skills

• brainstorm - Use before planning to explore ideas
• review-plan - Review a plan before execution
• implement-plan - Execute a plan task by task