Claude-Code-Workflow/.claude/skills/team-roadmap-dev/roles/planner/role.md

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

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

CLI Fallback

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	Phase 2	Context gathering via codebase exploration
create-plans	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

// 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)

// 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

// 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)

// 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

Phase 4: Self-Validation

// 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

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