| name | dev-planning |
| description | Development planning — codebase investigation, complexity estimation, structured Wave/Step plan generation and review. Produces plans consumed by dev-execute. |
| when-to-use | Any task that needs an implementation plan before coding. Triggered when asked to plan a feature, analyze a task, or produce a development plan. |
Development Planning
Investigate the codebase, estimate complexity, and produce a structured Wave/Step plan. No code — only plans that the execution phase follows exactly.
Phase 1: Load Context
get-task — read description, acceptance criteria, existing sections
- Read the PM's
analysis section if present
report-progress(status: planning, percentage: 5)
Phase 2: Investigate
Estimate complexity first from the task description, then launch investigation accordingly.
Simple (1-2 steps): Direct Grep/Read on known files — no agents needed.
Normal (3-6 steps): Parallel investigation:
- 1 Explore agent: conventions, similar implementations, callers
- 1 librarian agent: official docs if external library involved
Complex (7+ steps): Parallel investigation:
- 2 Explore agents: conventions + organization, impact scope + test coverage
- 1 librarian agent: official docs, API references
- Self-assess: stress-test the approach, surface risks before planning
After investigation, assess codebase state: Disciplined (follow patterns) / Transitional (follow new direction) / Legacy (improve, don't copy) / Chaotic (establish from scratch).
report-progress(percentage: 20)
Phase 3: Pre-Plan Analysis (complexity-gated)
Simple: Skip — proceed to Phase 4.
Normal: Skip-if-confident gate. Skip if ALL of:
- scope is single module
- no external dependencies introduced
- no architectural impact
- research found all relevant patterns and files
- no cross-cutting concerns (auth, logging, error handling, migrations)
If ANY condition fails:
- Self-analyze: context sufficiency, hidden requirements, gaps in the task description
- Identify MUST DO / MUST NOT directives for your plan
- If ambiguity remains: resolve via further investigation or
ask-user MCP tool
Complex:
- Deep analysis before planning:
- Context sufficiency: hidden requirements, gaps, unstated assumptions
- Effort estimation: prerequisites, codebase fit, dependency ordering
- Stress-test: challenge the approach, surface risks and alternatives
- Synthesize all findings into plan directives
- If ambiguity remains: resolve before proceeding
report-progress(percentage: 40)
Phase 4: Create Development Plan
Apply my-coding skill — plans must align with project coding standards. Apply my-language skill to all written output. All plan content (step titles, descriptions, conventions, risks) MUST be in English.
Tier System
| Tier | Files | Model | When | Benchmark Context |
|---|
quick | ≤1 | haiku | Mechanical: config, rename, scaffold, boilerplate | SWE-bench 73%, 200K context, $5/MTok. Fast (93 tok/s). Fails at cross-file reasoning. |
mid | 1-3 | sonnet | Standard implementation, business logic. DEFAULT | SWE-bench 80%, 200K context, $15/MTok. 98.5% of Opus coding at 1/5 cost. |
senior | 3+ | opus | Cross-layer, architecture, migration, complex edge cases | SWE-bench 81%, 200K context, GPQA 91% (+17pp over Sonnet). $75/MTok. Justified for deep reasoning. |
Codebase state escalation: Chaotic or Legacy → all quick steps escalate to mid.
Wave Construction Rules
- Steps within a wave MUST touch different files (file-exclusive parallelism)
- Steps across waves MAY touch the same files (sequential execution)
- Group independent steps into the same wave for parallel execution
- Dependent steps go into later waves
report-progress(percentage: 60)
Phase 5: Plan Review (complexity-gated)
Simple: Skip — save plan directly.
Normal: Skip-if-confident gate. Skip if ALL of:
- All file references verified (paths exist or are explicitly marked as new)
- Every step has concrete QA (command + expected result, not vague)
- Tiers match scope (no senior for single-file config, no quick for cross-module logic)
- No scope beyond original request (no bonus features, no extra abstractions)
If ANY condition fails:
- Spawn
plan-review agent with the plan content
- If REJECT: fix cited issues, re-submit (max 2 iterations)
- If OKAY: proceed to Phase 6
Complex:
- Spawn
plan-review agent (opus override): comprehensive review including adversarial checks, reference verification, AI-slop detection
- If REJECT: fix cited issues, re-submit (max 2 iterations)
- If OKAY: proceed to Phase 6
report-progress(percentage: 90)
Phase 6: Deliver
create-task-section(type: plan) — save the structured plan (format below)
report-progress(status: planned, percentage: 100)
Plan Format
## Development Plan
**Complexity**: simple | normal | complex
**Steps**: {total count}
**Waves**: {wave count}
**Codebase State**: disciplined | transitional | legacy | chaotic
### Wave 1
#### Step 1: {imperative title}
- **Tier**: quick | mid | senior
- **Files**: {comma-separated absolute paths}
- **Done when**:
- {verifiable criterion 1}
- {verifiable criterion 2}
- **QA**: {test scenario or command + expected result}
#### Step 2: {imperative title}
- **Tier**: mid
- **Files**: {paths — MUST NOT overlap with Step 1}
- **Done when**:
- {criterion}
- **QA**: {scenario + expected result}
### Wave 2 (depends on Wave 1)
#### Step 3: {title}
...
### Conventions
- {Pattern from codebase to follow — file:line reference}
### Must NOT
- {Forbidden change or pattern}
- {File or module to leave untouched}
### Risks
- {Open questions, assumptions, unresolved gaps}
Plan Quality Rules
- Every step has tier, files list, done-when, and QA
- Done-when criteria are verifiable (testable, greppable, readable) — never vague
- Files are absolute paths that exist in the codebase
- Conventions reference actual code patterns (file:line) — not generic advice
- Must NOT section prevents scope creep — always include for normal/complex
Complexity Reference
| Steps | Complexity | Pre-Plan Analysis | Plan Review |
|---|
| 1-2 | simple | skip | skip |
| 3-6 | normal | self-analysis | plan-review (sonnet) |
| 7+ | complex | deep self-analysis | plan-review (opus) |