/engineer-plan — Implementation Planning

Create structured implementation plans that break specs into ordered, actionable tasks. Plans bridge architecture (tech spec) and execution (engineer-work).

When to Use

• User says "plan this", "create a plan", "implementation plan"
• After completing a tech spec and ready to break it into tasks
• When a feature needs structured decomposition before building

Process

Step 1: Gather Context

Check for existing specs (in priority order):

1. docs/tech-specs/ — Most detailed, preferred source
2. docs/prds/ — Product requirements if no tech spec
3. User-provided description or $ARGUMENTS

Also check docs/solutions/ for relevant past solutions.

Step 2: Research (Parallel Agents)

Spawn 2 agents IN PARALLEL using the Task tool:

Agent 1 — Codebase Analyst

Task(subagent_type: "general-purpose", description: "Analyze codebase for planning")
prompt: Analyze this project to inform an implementation plan for [FEATURE].
  Focus on: existing patterns to follow, files/directories that need modification,
  related code that could be affected, test patterns, tech stack (check package.json,
  config files). Return findings relevant to planning.

Agent 2 — Practices Researcher

Task(subagent_type: "general-purpose", description: "Research best practices")
prompt: Research implementation best practices for [FEATURE TYPE] given the
  project's tech stack. Focus on: recommended implementation order, common
  integration challenges, testing strategies. Return practical guidance.

If the feature involves unfamiliar framework APIs or third-party integrations, launch an additional agent:

Agent 3 — Docs Researcher (conditional)

Task(subagent_type: "general-purpose", description: "Research framework docs")
prompt: Research [specific framework/API] documentation for [FEATURE].
  Check version compatibility with the project's package.json.
  Focus on: correct API usage, deprecation notices, common pitfalls.

Skip this agent if the feature uses well-established patterns already present in the codebase.

Step 3: Choose Detail Level

Use AskUserQuestion:

• "What level of detail for this plan?" (header: "Detail")
  • "Minimal — task list with descriptions" — For small features, <1 day
  • "Standard — tasks with acceptance criteria (Recommended)" — For most features, 1 day - 1 week
  • "Comprehensive — detailed tasks with code guidance" — For complex features, >1 week

Step 4: Write Plan

Write the plan to docs/plans/YYYY-MM-DD-<name>.md.

Planning rules:

• Tasks ordered by dependency (what must be done first)
• Each task is independently implementable and testable
• Include clear acceptance criteria (standard/comprehensive)
• Mark parallel-safe tasks
• Effort estimates: S (single file), M (multiple files), L (cross-cutting)
• Include Task 0 for setup (branch, dependencies) if needed

Minimal plan format:

# Plan: [Feature Name]
**Date:** YYYY-MM-DD | **Spec:** [link] | **Detail:** Minimal

## Tasks
| # | Task | Description | Effort | Depends On |
|---|------|-------------|--------|------------|
| 0 | Setup | Branch, dependencies | S | — |
| 1 | ... | ... | S/M/L | — |

Standard plan format — adds per-task sections with:

• Key files to modify
• Acceptance criteria (2-4 bullets)
• Test expectations
• Dependency graph

Comprehensive plan format — adds per-task:

• Implementation guidance with code patterns
• Detailed test specifications
• Rollback procedures
• Risk assessment

Step 5: Handoff

Use AskUserQuestion:

• "Plan is ready. What's next?" (header: "Next step")
  • "Start building (/engineer-work)" — Execute the plan
  • "Refine the plan" — Adjust tasks or detail
  • "Done for now" — Save and close

Output

Save to: docs/plans/YYYY-MM-DD-<name>.md

Next Steps

• Ready to build? → /engineer-work
• Need a tech spec first? → /product-tech-spec
• Want to review after building? → /engineer-review