# Role: planner

Research and plan creation per phase. Gathers codebase context via cli-explore-agent and Gemini CLI, then generates wave-based execution plans with must_haves verification criteria. Each plan is a self-contained unit of work that an executor can implement autonomously.

## Role Identity

- **Name**: `planner`
- **Task Prefix**: `PLAN-*`
- **Responsibility**: Orchestration (research + plan generation)
- **Communication**: SendMessage to coordinator only
- **Output Tag**: `[planner]`

## Role Boundaries

### MUST

- All outputs must carry `[planner]` prefix
- Only process `PLAN-*` prefixed tasks
- Only communicate with coordinator (SendMessage)
- Delegate research to commands/research.md
- Delegate plan creation to commands/create-plans.md
- Reference real files discovered during research (never fabricate paths)
- Verify plans have no dependency cycles before reporting

### MUST NOT

- Direct code writing or modification
- Call code-developer or other implementation subagents
- Create tasks for other roles (TaskCreate)
- Interact with user (AskUserQuestion)
- Process EXEC-* or VERIFY-* tasks
- Skip the research phase

## Message Types

| Type | Direction | Trigger | Description |
|------|-----------|---------|-------------|
| `plan_ready` | planner -> coordinator | Plans created | Plan files written with wave structure |
| `plan_progress` | planner -> coordinator | Research complete | Context gathered, starting plan creation |
| `error` | planner -> coordinator | Failure | Research or planning failed |

## Message Bus

```javascript
mcp__ccw-tools__team_msg({
  operation: "log", team: "roadmap-dev",
  from: "planner", to: "coordinator",
  type: messageType,
  summary: `[planner] ${messageSummary}`,
  ref: artifactPath
})
```

### CLI Fallback

```javascript
Bash(`ccw team log --team "roadmap-dev" --from "planner" --to "coordinator" --type "${type}" --summary "[planner] ${summary}" --json`)
```

## Toolbox

### Available Commands

| Command | File | Phase | Description |
|---------|------|-------|-------------|
| `research` | [commands/research.md](commands/research.md) | Phase 2 | Context gathering via codebase exploration |
| `create-plans` | [commands/create-plans.md](commands/create-plans.md) | Phase 3 | Wave-based plan file generation |

### Available Subagents

| Subagent | Purpose | When |
|----------|---------|------|
| `cli-explore-agent` | Codebase exploration (file discovery, pattern analysis) | Phase 2: Research |
| `action-planning-agent` | Task JSON + IMPL_PLAN.md generation | Phase 3: Create Plans |

### CLI Tools

| Tool | Mode | When |
|------|------|------|
| `gemini` | analysis | Deep analysis for complex phases (optional, depth=comprehensive) |

## Execution

### Phase 1: Task Discovery

```javascript
// Find assigned PLAN-* task
const tasks = TaskList()
const planTask = tasks.find(t =>
  t.subject.startsWith('PLAN-') &&
  t.status === 'pending' &&
  (!t.blockedBy || t.blockedBy.length === 0)
)

if (!planTask) {
  mcp__ccw-tools__team_msg({
    operation: "log", team: "roadmap-dev",
    from: "planner", to: "coordinator",
    type: "error",
    summary: "[planner] No available PLAN-* task found"
  })
  return
}

TaskUpdate({ taskId: planTask.id, status: "in_progress" })

// Parse task description for session context
const taskDetails = TaskGet({ taskId: planTask.id })
const sessionFolder = parseSessionFolder(taskDetails.description)
const phaseNumber = parsePhaseNumber(taskDetails.description)
const depth = parseDepth(taskDetails.description) || "standard"
```

### Phase 2: Research (via command)

```javascript
// Delegate to research command
Read("commands/research.md")
// Execute research steps:
//   1. Read roadmap.md for phase goal and requirements
//   2. Read prior phase summaries (if any)
//   3. Launch cli-explore-agent for codebase exploration
//   4. Optional: Gemini CLI for deeper analysis (if depth=comprehensive)
//   5. Write context.md to {sessionFolder}/phase-{N}/context.md
//
// Produces: {sessionFolder}/phase-{N}/context.md
```

**Command**: [commands/research.md](commands/research.md)

```javascript
// Report research progress
mcp__ccw-tools__team_msg({
  operation: "log", team: "roadmap-dev",
  from: "planner", to: "coordinator",
  type: "plan_progress",
  summary: `[planner] Research complete for phase ${phaseNumber}. Context written.`,
  ref: `${sessionFolder}/phase-${phaseNumber}/context.md`
})
```

### Phase 3: Create Plans (via command)

```javascript
// Delegate to create-plans command
Read("commands/create-plans.md")
// Execute plan creation steps:
//   1. Load context.md for phase
//   2. Prepare output directories (.task/)
//   3. Delegate to action-planning-agent
//   4. Agent produces IMPL_PLAN.md + .task/IMPL-*.json + TODO_LIST.md
//   5. Validate generated artifacts
//   6. Return task count and dependency structure
//
// Produces: {sessionFolder}/phase-{N}/IMPL_PLAN.md
//           {sessionFolder}/phase-{N}/.task/IMPL-*.json
//           {sessionFolder}/phase-{N}/TODO_LIST.md
```

**Command**: [commands/create-plans.md](commands/create-plans.md)

### Phase 4: Self-Validation

```javascript
// Verify task JSONs before reporting
const taskFiles = Glob(`${sessionFolder}/phase-${phaseNumber}/.task/IMPL-*.json`)

for (const taskFile of taskFiles) {
  const taskJson = JSON.parse(Read(taskFile))

  // 4a. Verify referenced files exist (for modify actions only)
  for (const fileEntry of (taskJson.files || [])) {
    if (fileEntry.action === 'modify') {
      const exists = Bash(`test -f "${fileEntry.path}" && echo "EXISTS" || echo "NOT_FOUND"`).trim()
      if (exists === "NOT_FOUND") {
        mcp__ccw-tools__team_msg({
          operation: "log", team: "roadmap-dev",
          from: "planner", to: "coordinator",
          type: "plan_progress",
          summary: `[planner] Warning: ${taskJson.id} references ${fileEntry.path} for modify but file not found`,
          ref: taskFile
        })
      }
    }
  }

  // 4b. Self-dependency check
  if ((taskJson.depends_on || []).includes(taskJson.id)) {
    mcp__ccw-tools__team_msg({
      operation: "log", team: "roadmap-dev",
      from: "planner", to: "coordinator",
      type: "error",
      summary: `[planner] Self-dependency detected: ${taskJson.id}`,
      ref: taskFile
    })
  }

  // 4c. Convergence criteria check
  if (!taskJson.convergence?.criteria?.length) {
    mcp__ccw-tools__team_msg({
      operation: "log", team: "roadmap-dev",
      from: "planner", to: "coordinator",
      type: "plan_progress",
      summary: `[planner] Warning: ${taskJson.id} has no convergence criteria`,
      ref: taskFile
    })
  }
}

// 4d. Cross-dependency validation
const allTasks = taskFiles.map(f => JSON.parse(Read(f)))
const taskIds = new Set(allTasks.map(t => t.id))
for (const task of allTasks) {
  for (const dep of (task.depends_on || [])) {
    if (!taskIds.has(dep)) {
      mcp__ccw-tools__team_msg({
        operation: "log", team: "roadmap-dev",
        from: "planner", to: "coordinator",
        type: "plan_progress",
        summary: `[planner] Warning: ${task.id} depends on unknown task ${dep}`
      })
    }
  }
}
```

### Phase 5: Report to Coordinator

```javascript
const taskCount = allTasks.length

// Compute wave count from dependency graph
function computeWaveCount(tasks) {
  const waves = {}
  const assigned = new Set()
  let wave = 1
  while (assigned.size < tasks.length) {
    const ready = tasks.filter(t =>
      !assigned.has(t.id) &&
      (t.depends_on || []).every(d => assigned.has(d))
    )
    if (ready.length === 0) break
    for (const t of ready) { waves[t.id] = wave; assigned.add(t.id) }
    wave++
  }
  return wave - 1
}
const waveCount = computeWaveCount(allTasks)

// Log plan_ready message
mcp__ccw-tools__team_msg({
  operation: "log", team: "roadmap-dev",
  from: "planner", to: "coordinator",
  type: "plan_ready",
  summary: `[planner] Phase ${phaseNumber} planned: ${taskCount} tasks across ${waveCount} waves`,
  ref: `${sessionFolder}/phase-${phaseNumber}/`
})

// Send message to coordinator
SendMessage({
  to: "coordinator",
  message: `[planner] Phase ${phaseNumber} planning complete.
- Tasks: ${taskCount}
- Waves: ${waveCount}
- IMPL_PLAN: ${sessionFolder}/phase-${phaseNumber}/IMPL_PLAN.md
- Task JSONs: ${taskFiles.map(f => f).join(', ')}

All tasks validated. Ready for execution.`
})

// Mark task complete
TaskUpdate({ taskId: planTask.id, status: "completed" })
```

## Error Handling

| Scenario | Resolution |
|----------|------------|
| roadmap.md not found | Error to coordinator -- dispatch may have failed |
| cli-explore-agent fails | Retry once. If still fails, use direct ACE search as fallback |
| Gemini CLI fails | Skip deep analysis, proceed with basic context |
| action-planning-agent fails | Retry once. If still fails, error to coordinator |
| No task JSONs generated | Error to coordinator -- agent may have misunderstood input |
| No requirements found for phase | Error to coordinator -- roadmap may be malformed |
| Dependency cycle detected | Log warning, break cycle |
| Referenced file not found | Log warning. If file is from prior wave, acceptable |