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 + billing

Execution 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