Create Plan

Contents

• When to Use This Skill
• Initial Input Handling
• Planning Workflow
  • Phase 1: Research
  • Phase 2: Present Understanding
  • Phase 3: Research User Corrections
  • Phase 4: Design Options
  • Phase 4b: Document Decision (ADR)
  • Phase 5: Phase Structure Review
  • Phase 6: Write the Plan
  • Phase 7: Bootstrap Tasks
• Multi-Session Support
• Critical Guidelines
  • Verification-First Planning
  • Phase Granularity
  • Be Thorough
  • Be Interactive
  • Be Skeptical
  • Exit Conditions Are Blocking Gates
  • No Unresolved Questions
• Quality Checklist
• Progress Tracking
• Project Type Detection

Reference files (open one when a step points to it):

• references/exit-conditions.md: Exit Condition Templates by Project Type

Create detailed, well-researched implementation plans through interactive collaboration and thorough codebase investigation.

When to Use This Skill

• Planning new features or functionality
• Designing technical implementations before coding
• Creating phased development roadmaps
• Structuring complex refactoring work
• Any task requiring upfront planning and design

Initial Input Handling

Parse the user's request to identify:

1. Task description - What needs to be implemented
2. Context files - Relevant existing code or documentation
3. Constraints - Timeline, technology, or scope limitations

Planning Workflow

Phase 1: Research

Critical: Thoroughly investigate the codebase before planning.

Spawn parallel sub-tasks using specialized agents:

Research Tasks:
- codebase-locator: Find all files related to the feature area
- codebase-analyzer: Understand existing patterns and architecture
- Explore: Investigate integration points and dependencies

For each research task, provide:

• Specific directories to examine
• Exact patterns or code to find
• Required output: file:line references

Read all identified files completely - no partial reads or summaries.

Phase 2: Present Understanding

Before any design work, present findings:

1. Codebase Analysis
   • Relevant existing code with file:line references
   • Current patterns and conventions discovered
   • Integration points and dependencies
2. Clarifying Questions
   • Ask only questions that code investigation couldn't answer
   • Focus on business logic, user requirements, edge cases
   • Avoid questions answerable by reading more code

Wait for user response before proceeding.

Phase 3: Research User Corrections

Critical: Do not accept user corrections at face value.

When the user provides corrections or additional context:

1. Verify claims through code investigation
2. Cross-reference with discovered patterns
3. Resolve any conflicts between user input and codebase reality

If conflicts exist, present findings and discuss before proceeding.

Phase 4: Design Options

Present design approaches with trade-offs:

Option A: [Approach Name]
- Description: [How it works]
- Pros: [Benefits]
- Cons: [Drawbacks]
- Fits pattern: [Reference to existing codebase patterns]

Option B: [Alternative Approach]
- Description: [How it works]
- Pros: [Benefits]
- Cons: [Drawbacks]
- Fits pattern: [Reference to existing codebase patterns]

Recommendation: [Preferred option with rationale]

Wait for user feedback on approach before detailing phases.

Phase 4b: Document Decision (ADR)

Before creating a new ADR, check for existing related decisions:

# Tiered ADR reading (context conservation)
1. Read("docs/decisions/INDEX.md")           # Scan all ADRs
2. Read("docs/decisions/ADR-NNNN.md", limit=10)  # Quick Reference only
3. Read full ADR only if directly relevant

After user approves a design option, invoke the ADR skill to document the decision:

Skill(skill="adr"): Document the design decision just made.

Context: [Why this decision was needed - from research phase]
Options Considered: [List options from Phase 4]
Decision: [The chosen option]
Rationale: [Why this option was selected]
Consequences: [Expected impacts]

The ADR will be created at docs/decisions/ADR-NNNN-title.md and INDEX.md will be updated.

Update the plan to reference the ADR in the Design Decision section:

## Design Decision

[Brief description of chosen approach]

See [ADR-NNNN](../decisions/ADR-NNNN-title.md) for full rationale and alternatives considered.

When to create ADRs during planning:

• Choosing between architectural approaches
• Selecting technologies or libraries
• Establishing new patterns or conventions
• Making trade-offs with significant implications
• Decisions that future developers will question "why?"

Phase 5: Phase Structure Review

Before writing the detailed plan, validate phase sizing and present the structure.

Phase Sizing Guide

Plans fail during execution when phases are too large or vague. Each phase will be executed by an orchestrator that delegates to subagents — so every task in a phase needs to be concrete enough that an independent agent can implement it without guessing.

Bias toward smaller phases. 12 small well-defined phases are far better than 5 large ones. A phase that tries to do too much will overwhelm the implementing agent, cause it to lose focus, or force it to make assumptions about parts it hasn't reached yet. When in doubt, split. A complex feature might need 8-15 phases — that reflects the natural decomposition of the work, not a failure of planning.

A natural layered decomposition often emerges: foundation/setup → data model → core logic → API/interface → integration → polish/edge cases. Each layer is typically one phase.

Right-sized phase characteristics:

• Has one concern — a single coherent unit of work
• Touches a small number of files (1-5 is typical, occasionally more for cross-cutting changes)
• Each task names a specific file and describes what to put in it (functions, classes, methods, endpoints)
• Can be described in 2 sentences — if you need more, split it
• Has a clear, testable outcome — you can verify it works without looking at later phases

Split signals — if any of these are true, the phase is too big:

• It contains the word "and" connecting unrelated concerns (e.g., "implement auth and set up the database schema")
• Two tasks within it could be developed and tested independently
• It mixes infrastructure/config work with feature implementation

Present the Structure

Proposed Implementation Phases:

Phase 1: [Name] - [2-sentence description] ([N] files)
Phase 2: [Name] - [2-sentence description] ([N] files)
Phase 3: [Name] - [2-sentence description] ([N] files)
...

Does this structure make sense? Any phases to add/remove/reorder?

Get explicit approval before writing the full plan.

Phase 6: Write the Plan

Write the implementation plan to the designated location:

Default path: docs/plans/YYYY-MM-DD-description.md

Use this structure:

# Implementation Plan: [Feature Name]

## Overview
[2-3 sentence summary of what will be implemented]

## Context
[Background, motivation, relevant existing code references]

## Design Decision
[Chosen approach and rationale]

**ADR Reference**: [ADR-NNNN](../decisions/ADR-NNNN-title.md)

## Related ADRs
- [ADR-NNNN](../decisions/ADR-NNNN-title.md): [Brief description of relevance]

## Implementation Phases

### Phase 1: [Name]

**Objective**: [1-2 sentences — what this phase accomplishes and what it produces]

**Files touched**: [List every file this phase creates or modifies]

**Verification Approach**: [How will we verify this phase works? What tests, commands, or checks will confirm success?]

**Tasks** (tests first, then implementation):
- [ ] Create `[test-file-path]`: test [specific scenarios — name them]
- [ ] Create `[file-path]`: implement `ClassName` with `method1()`, `method2()` — [what each does, 5-10 words per method]
- [ ] Modify `[file-path]`: add [what — e.g., "import and register AuthModule"]
- [ ] Verify: [specific command]

**Exit Conditions**:

> Phase cannot proceed until ALL conditions pass.

Build Verification:
- [ ] `[build command]` succeeds
- [ ] `[lint command]` passes
- [ ] `[typecheck command]` passes (if applicable)

Runtime Verification:
- [ ] Application starts: `[start command]`
- [ ] No runtime errors in console
- [ ] [Service/endpoint] is accessible at [URL]

Functional Verification:
- [ ] `[test command]` passes
- [ ] [Specific test]: `[targeted test command]`
- [ ] [Manual check]: [Observable behavior to verify]

### Phase 2: [Name]
[Continue pattern...]

## Dependencies
[External dependencies, prerequisites, blockers]

## Risks and Mitigations
[Potential issues and how to handle them]

Phase 7: Bootstrap Tasks

After writing the plan file, create Tasks for progress tracking:

Process:

1. Generate a task list ID from plan filename: plan-{filename-without-extension}
   • Example: 2026-01-24-user-auth.md → plan-2026-01-24-user-auth
2. Create a Task for each phase:

   TaskCreate:
     subject: "Phase N: [Phase Name]"
     description: "[Phase objective] - Plan: [plan file path]"
     activeForm: "Implementing Phase N: [Name]"

3. Set sequential dependencies:

   TaskUpdate:
     taskId: [phase-N]
     addBlockedBy: [phase-(N-1)]  # Each phase blocked by previous

4. Add task list ID to plan metadata (top of file):

   ---
   task_list_id: plan-2026-01-24-user-auth
   ---

Completion Message:

Plan created: [path]
Tasks created: [count] phases with sequential dependencies
Task List ID: [task_list_id]

To work on this plan:
  Single session:  /implement-plan [path]
  Multi-session:   CLAUDE_CODE_TASK_LIST_ID=[task_list_id] claude

Use the same task_list_id across sessions to share progress.

Multi-Session Support

Tasks persist on the filesystem and can be shared across Claude Code sessions.

Starting a shared session:

CLAUDE_CODE_TASK_LIST_ID=plan-2026-01-24-user-auth claude

Benefits:

• Multiple developers can work on the same plan
• Progress syncs automatically via shared task list
• Dependency tracking prevents conflicts (blocked tasks visible)
• Resume from any session with the same task_list_id

Task States:

◻ #1 Phase 1: Setup
◻ #2 Phase 2: Core Logic › blocked by #1
◻ #3 Phase 3: Integration › blocked by #2
◻ #4 Phase 4: Testing › blocked by #3

Critical Guidelines

Verification-First Planning

Every phase in the plan MUST include:

1. Verification Approach - A clear statement of how success will be measured
2. Tests before implementation - Task lists must show test creation BEFORE implementation
3. Specific test scenarios - Not just "write tests" but what scenarios to cover

Phase Granularity

Phases are executed by an orchestrator that delegates each task to an independent subagent. If a task is vague, the subagent has to guess — and it often guesses wrong. The key question for each task: could a developer who's never seen this codebase complete this task based solely on this description?

Bad — too vague, too large:

### Phase 1: Authentication

**Objective**: Add authentication to the application

**Tasks**:
- [ ] Write tests for auth
- [ ] Implement auth service
- [ ] Implement auth controller
- [ ] Add auth middleware
- [ ] Verify: `npm test` passes

Problems: "auth service" doing what exactly? How many methods? What library? "Add auth middleware" — where, protecting which routes? A subagent receiving "Implement auth service" will either ask clarifying questions (stalling the orchestrator) or make assumptions that conflict with later tasks.

Good — specific, delegatable:

### Phase 1: Password Hashing and Token Generation

**Objective**: Create the core auth utilities — password hashing via bcrypt and JWT token generation. No HTTP layer yet.

**Files touched**: `src/auth/auth.service.ts`, `src/auth/auth.service.spec.ts`, `src/auth/auth.module.ts`

**Verification Approach**: Unit tests verify bcrypt hashing round-trips correctly and JWT tokens contain expected claims (sub, iat, exp).

**Tasks** (tests first, then implementation):
- [ ] Create `src/auth/auth.service.spec.ts`: test `hashPassword()` produces valid bcrypt hash, `comparePassword()` matches correct password and rejects wrong password, `generateToken()` returns JWT with `sub` and `exp` claims
- [ ] Create `src/auth/auth.service.ts`: implement `AuthService` with `hashPassword(plain): Promise<string>`, `comparePassword(plain, hash): Promise<boolean>`, `generateToken(userId): string` — uses bcrypt (10 rounds) and jsonwebtoken
- [ ] Create `src/auth/auth.module.ts`: register `AuthService` as provider, export it
- [ ] Verify: `npm test -- auth.service` passes

### Phase 2: Login Endpoint

**Objective**: Add POST /auth/login endpoint that validates credentials and returns a JWT. Depends on AuthService from Phase 1.

**Files touched**: `src/auth/auth.controller.ts`, `src/auth/auth.controller.spec.ts`, `src/auth/auth.module.ts`
...

Notice: Phase 1 has one concern (crypto utilities), Phase 2 has one concern (HTTP endpoint). Each task names exact files, functions, and behaviors. A feature like auth might have 6-8 phases — that's a strength, not a weakness. Small phases are easier to implement, test, and debug.

Be Thorough

• Read entire files, not partial content
• Verify facts through code investigation
• Follow import chains to understand dependencies

Be Interactive

• Get buy-in at each step
• Allow course corrections throughout
• Present options rather than dictating

Be Skeptical

• Research user claims before accepting
• Cross-reference multiple sources
• Challenge assumptions with evidence

Exit Conditions Are Blocking Gates

Exit conditions are mandatory gates that must pass before advancing to the next phase. They are not advisory - they are requirements.

Three Verification Categories (all must pass):

1. Build Verification - Code compiles and passes static analysis:
   • Build commands (npm run build, cargo build, go build)
   • Linting (npm run lint, flake8, golangci-lint)
   • Type checking (npm run typecheck, mypy, tsc --noEmit)
2. Runtime Verification - Application actually runs:
   • Start command executes without error
   • No runtime exceptions or crashes
   • Services/endpoints become accessible
   • Health checks pass
3. Functional Verification - Correct behavior:
   • Test suites pass (npm test, pytest, go test)
   • Specific feature tests pass
   • Manual verification steps (for human-observable behaviors)

Never skip a category - each phase must have at least one check in each category.

No Unresolved Questions

Do NOT write plans with open questions.

If planning encounters ambiguity:

1. Stop and research further
2. Present options to the user
3. Get resolution before continuing

A plan with "TBD" or "to be determined" sections is incomplete.

Quality Checklist

Before finalizing any plan:

• All relevant code has been read completely
• File:line references are accurate and specific
• Design fits existing codebase patterns
• Phases are incrementally implementable
• Each phase has one concern and touches a small number of files
• Each task names specific files and describes what goes in them (classes, methods, functions)
• No task is so vague that a developer unfamiliar with the project would need to ask clarifying questions
• Each phase has a Verification Approach section
• Tasks list tests BEFORE implementation
• Exit conditions cover all three verification categories
• No unresolved questions or TBD sections
• User has approved structure and approach
• Tasks bootstrapped with dependencies set
• task_list_id added to plan metadata

Progress Tracking

Progress is tracked via Task tools which persist across sessions. See ADR-0001.

Task Persistence:

• Tasks persist on filesystem between sessions
• Dependencies ensure correct execution order
• Multiple sessions can share the same task list via CLAUDE_CODE_TASK_LIST_ID

Workflow:

create-plan → TaskCreate (all phases) → Outputs task_list_id
                    ↓
implement-plan → TaskUpdate(in_progress) → implement-phase → TaskUpdate(completed)
                    ↓
Resume (any session) → CLAUDE_CODE_TASK_LIST_ID=xxx claude → TaskList shows progress

Project Type Detection

Before writing exit conditions, detect the project type and use appropriate commands. Read references/exit-conditions.md for detection heuristics and per-language templates (Node.js, Python, Go, Rust, Java, etc.).