Writing Plans
Write step-by-step implementation plans for agentic execution. Each task should be a complete unit of work that one agent handles entirely.
Clarify ambiguity upfront: If the plan has unclear requirements or meaningful tradeoffs, use AskUserQuestion before writing the plan. Present options with descriptions explaining the tradeoffs. Use multiSelect: true for independent features that can be combined; use single-select for mutually exclusive choices. Don't guess when the user can clarify in 10 seconds.
Save to: **/plans/YYYY-MM-DD-<feature-name>.md
Plan Template
# [Feature Name] Implementation Plan
> **Status:** DRAFT | APPROVED | IN_PROGRESS | COMPLETED
## Specification
**Problem:** [What's broken, missing, or needed. Describe the current state and why it's insufficient. Be specific enough that someone unfamiliar with the codebase understands the issue.]
**Goal:** [What the end state looks like after this work is done. Describe the user/developer experience, not the implementation.]
**Scope:** [What's in and what's out. Explicit boundaries prevent scope creep.]
**Success Criteria:**
- [ ] Criterion 1 (measurable/verifiable)
- [ ] Criterion 2
## Context Loading
_Run before starting:_
read src/relevant/file.ts glob src/feature/**/*.ts
## Tasks
### Task 1: [Complete Feature Unit]
**Context:** `src/auth/`, `tests/auth/`
**Steps:**
1. [ ] Create `src/auth/login.ts` with authentication logic
2. [ ] Add tests in `tests/auth/login.test.ts`
3. [ ] Export from `src/auth/index.ts`
**Verify:** `npm test -- tests/auth/`
---
### Task 2: [Another Complete Unit]
**Context:** `src/billing/`
**Steps:**
1. [ ] ...
**Verify:** `npm test -- tests/billing/`Task Sizing
A task includes everything to complete one logical unit:
- Implementation + tests + types + exports
- All steps a single agent should do together
Right-sized: "Add user authentication" - one agent does model, service, tests, types Wrong: Separate tasks for model, service, tests - these should be one task
Bundle trivial items: Group small related changes (add export, update config, rename) into one task.
Parallelization & Grouping
During execution, tasks are grouped by subsystem to share agent context. Structure your plan to make grouping clear:
## Authentication Tasks ← These will run in one agent
### Task 1: Add login
### Task 2: Add logout
## Billing Tasks ← These will run in another agent (parallel)
### Task 3: Add billing API
### Task 4: Add webhooks
## Integration Tasks ← Sequential (depends on above)
### Task 5: Wire auth + billingExecution model:
- Tasks under same
##heading → grouped into one agent - Groups touching different subsystems → run in parallel
- Max 3-4 tasks per group (split larger sections)
Tasks in the same subsystem should be sequential or combined into one task.
Rules
- Explicit paths: Say "create
src/utils/helpers.ts" not "create a utility" - Context per task: List files the agent should read first
- Verify every task: End with a command that proves it works
- One agent per task: All steps in a task are handled by the same agent
Before Presenting
Before presenting the plan to the user, dispatch the ce:devils-advocate agent via Task tool to review it:
- Pass the full drafted plan text to the agent
- Load relevant domain skills based on what the plan involves. Evaluate which of these apply and include them in the agent prompt:
- Skill(ce:architecting-systems) - system design, module boundaries, dependencies - Skill(ce:managing-databases) - database schemas, queries, migrations - Skill(ce:handling-errors) - error handling patterns - Skill(ce:writing-tests) - test strategy and quality - Skill(ce:migrating-code) - code migrations, API versioning - Skill(ce:optimizing-performance) - performance-sensitive work - Skill(ce:refactoring-code) - structural refactoring
- The agent will look for: unstated assumptions, missing edge cases, tasks that are too vague, missing dependencies between tasks, verification gaps
- Incorporate valid feedback into the plan
- Note what the review caught in a brief "Review notes" comment at the bottom of the plan
Skip this step only if the plan is trivial (< 3 tasks, single subsystem, no architectural decisions).
Large Plans
For plans over ~500 lines, split into phases in a folder:
**/plans/YYYY-MM-DD-feature/
├── README.md # Overview + phase tracking
├── phase-1-setup.md
└── phase-2-feature.md