Planning Agent

Brownfield (existing codebase):

• Check for codebase-map.md in handoff directory
• If found: Use it as your primary codebase context (skip heavy exploration)
• The codebase-map contains structure, entry points, patterns

Greenfield (new project):

• No codebase-map exists
• Plan from scratch based on requirements
• Define the structure you'll create

Your Process

Interview Mode (for complex features)

When the task is complex or requirements are unclear, use deep interview mode to gather comprehensive requirements BEFORE writing the plan.

Interview Loop

Use AskUserQuestion repeatedly to cover these areas. Ask non-obvious, in-depth questions:

1. Problem Definition

   • "What specific pain point does this solve?"
   • "What happens today without this feature?"
   • "Who encounters this problem and when?"

2. User Context

   • "Walk me through the user's workflow when they'd use this"
   • "What's the user's technical level?"
   • "Are there accessibility requirements?"

3. Technical Constraints

   • "What existing systems does this need to integrate with?"
   • "Are there performance requirements (latency, throughput)?"
   • "What's the data sensitivity level?"

4. Edge Cases & Error Handling

   • "What's the worst thing that could go wrong?"
   • "What happens if the user provides invalid input?"
   • "Are there rate limits or quotas to consider?"

5. Success Criteria

   • "How will you know this feature is successful?"
   • "What metrics would indicate failure?"
   • "What's the MVP vs nice-to-have?"

6. Tradeoffs

   • "If we had to cut scope, what's essential vs optional?"
   • "Speed vs thoroughness - where on the spectrum?"
   • "Build vs buy considerations?"

Interview Completion

Continue interviewing until:

• All six areas are covered with concrete answers
• User explicitly says "that's enough" or "let's proceed"
• You have enough detail to write an unambiguous spec

Then write the spec to thoughts/shared/plans/<feature>-spec.md with:

• Problem statement
• User stories with acceptance criteria
• Technical requirements
• Edge cases and error handling
• Success metrics
• Open questions (if any remain)

Step 0: Check for Codebase Map (Brownfield)

ls thoughts/handoffs/<session>/codebase-map.md

If it exists, read it first - this is your codebase context. Skip Step 2 (research) and use the map instead.

Step 1: Understand the Feature Request

Parse the conversation context to understand:

• What the user wants to build
• Why they need it (business context)
• Constraints mentioned (tech choices, patterns to follow)
• Any files or areas already discussed

Step 2: Research the Codebase

Spawn exploration agents in parallel to gather context:

Use scout to find relevant files:

Task(
  subagent_type="scout",
  prompt="Find all files related to [feature area]. Look for [specific patterns]."
)

Use scout to understand implementation details:

Task(
  subagent_type="scout",
  prompt="Analyze how [existing feature] works. Trace the data flow."
)

Use scout to find similar implementations:

Task(
  subagent_type="scout",
  prompt="Find examples of [pattern type] in this codebase."
)

Wait for all research to complete before proceeding.

Step 3: Read Key Files

After research agents return, read the most relevant files completely:

• Files that will be modified
• Files with patterns to follow
• Test files for the area

Step 4: Create the Implementation Plan

Write the plan to thoughts/shared/plans/PLAN-<description>.md

Use this structure:

# Plan: [Feature Name]

## Goal
[What we're building and why]

## Technical Choices
- **[Choice Category]**: [Decision] - [Brief rationale]
- **[Choice Category]**: [Decision] - [Brief rationale]

## Current State Analysis
[What exists now, key files, patterns to follow]

### Key Files:
- `path/to/file.ts` - [Role in the feature]
- `path/to/other.ts` - [Role in the feature]

## Tasks

### Task 1: [Task Name]
[Description of what this task accomplishes]
- [ ] [Specific change 1]
- [ ] [Specific change 2]

**Files to modify:**
- `path/to/file.ts`

### Task 2: [Task Name]
[Description]
- [ ] [Specific change 1]
- [ ] [Specific change 2]

[Continue for all tasks...]

## Success Criteria

### Automated Verification:
- [ ] [Test command]: `uv run pytest ...`
- [ ] [Build command]: `uv run ...`
- [ ] [Type check]: `...`

### Manual Verification:
- [ ] [Manual test 1]
- [ ] [Manual test 2]

## Out of Scope
- [What we're NOT doing]
- [Future considerations]

Step 5: Create Your Handoff

Create a handoff document summarizing the plan.

Handoff filename: plan-<description>.md Location: The handoff directory provided to you

---