Generate Implementation Plan

Announce: "I'm using the generate-implementation-plan skill to enrich this plan for standalone execution. This will embed the mandatory execution workflow and per-task checklists."

Quick Start

1. •Identify plan from ~/.claude/plans/
2. •Read and gather context for referenced files
3. •Output format:
   • •Multi-file (always): Use INTRO-TEMPLATE.md + TASK-TEMPLATE.md
   • •Create folder YYYY-MM-DD-<feature-name>/ containing intro.md + task-N.md files
4. •Update docs/plans/INDEX.md

Process

1. •

   Identify the plan - Ask user which plan or use the most recent

2. •

   Read the plan - Understand tasks and scope

3. •

   Gather context - Read relevant files mentioned in the plan

4. •

   Discover test files - For each modified file, find related .spec.ts files and mock locations

5. •

   Compute checksums - Calculate md5 checksums for files to be modified (first 8 chars)

6. •

   Gather dependency info - For package upgrades, query peer dependencies and known issues

7. •

   Enrich - Add self-contained header and inline code context

8. •

   Add verification - How to confirm each task is complete

9. •

   Add skill recommendations - Which skills to invoke per task

10. •

    Generate ALL output content at once with model selection:

    CRITICAL OPTIMIZATION: Generate content for ALL files (intro + all tasks) in a single LLM response. Do NOT generate task files one-by-one.

    Model selection for content generation:

    For each task:

    a) Complex sections (use Sonnet):

    • •Architecture analysis
    • •Code context extraction
    • •Custom failure modes
    • •Dependency discovery and conflict resolution
    • •Task complexity assignment

    b) Boilerplate sections (use templates + Haiku):

    • •Load template from assets/checklist-template.md
    • •Substitute variables: {{TASK_NAME}}, {{FILE_PATH}}, etc.
    • •Use Haiku sub-agent for any custom text generation
    • •Standard verification steps (use verification-template.md)
    • •Common failure modes (use failure-modes-template.md)

    c) Generation strategy:

    • •All Sonnet sections first (complex analysis)
    • •All template substitutions second (simple replacement)
    • •All Haiku sections last (parallel sub-agents for boilerplate)

    Multi-file generation:

    • •In ONE response, generate:
      • •Complete intro.md content from INTRO-TEMPLATE.md
      • •Complete task-0.md content (if exists) from TASK-TEMPLATE.md
      • •Complete task-1.md content from TASK-TEMPLATE.md
      • •Complete task-2.md content from TASK-TEMPLATE.md
      • •... (all task files)
    • •Build Task Index in intro with relative links to task files
    • •Code snippets go in intro only; task files reference "See intro"
    • •Store each file's content in memory with clear labels:
      code

      INTRO_CONTENT = "# Fix Slow..."
      TASK_0_CONTENT = "# Task 0:..."
      TASK_1_CONTENT = "# Task 1:..."
      

11. •

    Write ALL files in parallel:

    CRITICAL OPTIMIZATION: Use a SINGLE message with MULTIPLE Write tool calls. Do NOT write files sequentially.

    First, create the directory if needed:

    markdown

    Creating directory and writing all plan files in parallel:
    

    Then make ONE tool call message containing ALL Write operations:

    • •Write(docs/plans/YYYY-MM-DD-<feature>/intro.md, INTRO_CONTENT)
    • •Write(docs/plans/YYYY-MM-DD-<feature>/task-0.md, TASK_0_CONTENT)
    • •Write(docs/plans/YYYY-MM-DD-<feature>/task-1.md, TASK_1_CONTENT)
    • •Write(docs/plans/YYYY-MM-DD-<feature>/task-2.md, TASK_2_CONTENT)
    • •... (all task files)

    Why: Parallel writes execute simultaneously. Sequential writes wait for each API roundtrip (~26-53s per file).

12. •

    Update INDEX - Add/update entry in docs/plans/INDEX.md

Key Principles

The enriched plan is for a fresh Claude session with zero prior context.

Multi-File Format: Content Split

When using multi-file format, content is split to minimize context overhead per session:

Task files reference shared content with:

> **Plan:** [[feature-name]](./intro.md)
> **See intro for:** Architecture, Code Context, Execution Workflow

Migration Patterns (for upgrade plans)

For plans involving syntax migrations or API changes, include before/after examples in the "Relevant Code Context" section. See MIGRATION-PATTERNS.md for common patterns.

Example format:

### Migration Pattern: *ngIf to @if

**Before:**
```html
<div *ngIf="user">{{ user.name }}</div>

After:

@if (user) {
  <div>{{ user.name }}</div>
}

Notes: Remove ng-template wrappers when using @else

- Include all context inline (no memory of your conversation)
- Be explicit about file locations and patterns
- Reference relevant code snippets directly in the plan
- Intent for business logic, exact content for templates/config
- Verification criteria for every task
- Skill recommendations for specialized workflows

## Context Optimization (Reduces Startup Tool Calls)

Pre-compute context that would otherwise require tool calls during execution:

### Code Structure Discovery (ast-grep Skill)

**For TypeScript/JavaScript/Python files referenced in the plan:**

**Before gathering context, invoke ast-grep skill for structure:**

1. **Invoke ast-grep skill:**
   ```markdown
   Skill("ast-grep", args="Find all functions in src/service.ts")

1. •

   ast-grep returns signatures (200-500 tokens):

   • •Function names with line numbers
   • •Class definitions with methods
   • •Import statements
2. •

   Analyze signatures to identify relevant code (2-3 functions typically)

3. •

   Read only relevant sections:

   markdown

   Read src/service.ts offset=<start_line> limit=<num_lines>
   

When to use ast-grep:

• •✅ Finding function signatures before reading implementation
• •✅ Locating class methods across large files
• •✅ Discovering imports/exports for dependency analysis
• •✅ Identifying interface definitions for type context
• •❌ Small files (< 100 lines) - just Read directly
• •❌ Config files, JSON, YAML - no AST benefit

Result: 50-80% token reduction for code context gathering

Important: Always invoke the ast-grep skill explicitly using Skill("ast-grep", args="...") - Claude Code doesn't auto-invoke skills.

Test File Discovery (Batched)

CRITICAL: Use ONE Glob call to find all test files at once.

Instead of:

Glob for auth.service.spec.ts    # Call 1
Glob for user.service.spec.ts    # Call 2
Glob for api.service.spec.ts     # Call 3

Do this:

Glob for {auth,user,api}.service.spec.ts
# OR
Glob for **/*.service.spec.ts (then filter)

Result: One Glob call instead of N calls for N files.

For each modified file, include:

• •Related .spec.ts file path
• •Mock setup location (line numbers)
• •Required mock changes based on interface modifications

File Checksums (Batched)

CRITICAL: Compute checksums for ALL files in a SINGLE Bash call.

Instead of:

md5 -q /path/to/file1.ts | cut -c1-8  # Call 1
md5 -q /path/to/file2.ts | cut -c1-8  # Call 2
md5 -q /path/to/file3.ts | cut -c1-8  # Call 3

Do this:

for file in /path/to/file1.ts /path/to/file2.ts /path/to/file3.ts; do
  echo "$file: $(md5 -q "$file" | cut -c1-8)"
done

Result: One Bash call instead of N calls for N files.

For each file to be modified:

• •Compute md5 -q <file> | cut -c1-8
• •Include "lines to modify" range
• •Enables skip-if-already-done detection

Dependency Information

For package upgrade tasks:

• •Query npm info <pkg> peerDependencies
• •Document known compatibility issues
• •Include breaking changes from changelogs

Skill Recommendations

For each task, recommend relevant skills that should be invoked. Check all available skills including:

• •Built-in skills (e.g., from superpowers plugin)
• •Project-specific skills (in .claude/skills/)
• •Third-party plugin skills

Per-task format:

**Recommended skill:** `superpowers:test-driven-development`
  - Invoke BEFORE writing implementation code
  - Ensures tests are written first

Selection criteria:

• •Match task type to skill purpose
• •Use — if no skill provides clear benefit
• •Include invocation timing (before/during/after implementation)

Complexity Assignment

Every task MUST be assigned a complexity rating during enrichment:

🟢 Simple (< 50 lines, single focus):

• •Single file modifications < 50 lines
• •Config changes, simple refactors
• •Clear input → output transformations
• •Examples: Add environment variable, update constant, simple helper function

🟡 Moderate (50-200 lines, some complexity):

• •Multiple files modified
• •Business logic implementation
• •Requires understanding existing patterns
• •Examples: Add API endpoint, implement validation logic, refactor component

🔴 Complex (> 200 lines, architectural):

• •Architectural changes
• •Cross-cutting concerns
• •Requires deep domain knowledge
• •Examples: Migrate authentication system, redesign data layer, add new service

Dispatch implications:

• •🟢: Direct execution or focused-task-executor (if also < 30 lines, single file)
• •🟡: Sub-agent recommended for context isolation
• •🔴: Sub-agent required

Who assigns: Plan enricher during enrichment process (not the original planner)

Validation: Plan validator checks all tasks have complexity assigned

Agent Recommendations

When a specialist agent would benefit a task, recommend it. Common patterns:

Selection criteria:

• •Match task domain to agent specialty
• •Use — if no agent provides clear benefit
• •Consider project-specific agents if available

Codex Delegation (Optional)

For users who prefer OpenAI Codex for code generation tasks, add Dispatch: codex to the task.

Prerequisites:

• •Run /setup-codex to configure Codex MCP server
• •Codex CLI installed and authenticated

When to recommend Codex:

• •User explicitly requests Codex for tasks
• •Code generation heavy tasks (large implementations)
• •When user has stated preference for Codex style

Format:

**Dispatch:** codex

Important: Codex delegation only handles implementation. Claude Code still manages:

• •Checkpoint creation (before/after task)
• •Code review (/pr-review-toolkit:review-pr)
• •Verification and commit

Critical: Execution Workflow Embedding

The enriched plan MUST include these elements to ensure code reviews are not skipped:

1. •Execution Workflow section - Placed BEFORE tasks, not buried at the end
2. •Per-task checklist - Each task ends with a checklist including the review step

This workflow mandates:

• •Code review for EVERY task (/pr-review-toolkit:review-pr)
• •Status updates in Execution Log
• •Fix-and-retry cycle for critical issues (max 2 cycles)
• •Session handoff protocol

Without these, executors will skip reviews because the instructions are too far from where they're working.

References

Templates:

• •Intro template: INTRO-TEMPLATE.md
• •Task template: TASK-TEMPLATE.md

Guides:

• •Enrichment checklist: ENRICHMENT-CHECKLIST.md
• •Failure modes examples: FAILURE-MODES-EXAMPLES.md
• •Migration patterns: MIGRATION-PATTERNS.md
• •Execution guide: EXECUTION-GUIDE.md

Execution Handoff

After saving the enriched plan, offer:

Plan enriched and saved:

• •Intro: docs/plans/<feature>/intro.md
• •Tasks: docs/plans/<feature>/task-0.md through task-N.md

Ready to execute?

1. •Execute now - Start working through tasks in this session
2. •New session - Open fresh session, run /execute-plan <feature-name>

INDEX.md Maintenance

After saving an enriched plan, update docs/plans/INDEX.md:

1. •Read current INDEX.md
2. •Check if plan already exists in table
3. •If new: Add row to "Active Plans" with:
   • •Link to plan intro file
   • •Created date (from filename)
   • •Task count (count task files)
   • •Progress: 0/N
   • •Branch (from plan's Git Context)
   • •Status: ⏳ Not Started
4. •If existing: Update progress and status based on Execution Log
5. •Write updated INDEX.md

INDEX.md format:

| Plan | Created | Tasks | Progress | Branch | Status |
|------|---------|-------|----------|--------|--------|
| [Feature A](./2026-01-14-feature-a/intro.md) | 2026-01-14 | 8 | 3/8 | feature/a | 🔄 |
| [Feature B](./2026-01-13-feature-b/intro.md) | 2026-01-13 | 2 | 0/2 | feature/b | ⏳ |

When a plan reaches 100% completion:

• •Move from "Active Plans" to "Completed Plans"
• •Add completion date