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

Planner Role

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

Identity

• Name: planner | Tag: [planner]
• Task Prefix: PLAN-*
• Responsibility: Orchestration (research + plan generation)

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
• Work strictly within Orchestration responsibility scope

MUST NOT

• Execute work outside this role's responsibility scope
• 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
• Communicate directly with other worker roles (must go through coordinator)
• Omit [planner] identifier in any output

---

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

Tool Capabilities

Tool	Type	Used By	Purpose
cli-explore-agent	Subagent	planner	Codebase exploration, pattern analysis
action-planning-agent	Subagent	planner	Task JSON + IMPL_PLAN.md generation
gemini	CLI tool	planner	Deep analysis for complex phases (optional)
Read/Write	File operations	planner	Context and plan file management
Glob/Grep	Search	planner	File discovery and pattern matching

---

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

Before every SendMessage, log via mcp__ccw-tools__team_msg:

mcp__ccw-tools__team_msg({
  operation: "log",
  session_id: <session-id>,
  from: "planner",
  type: <message-type>,
  ref: <artifact-path>
})

CLI fallback (when MCP unavailable):

Bash("ccw team log --session-id <session-id> --from planner --type <type> --ref <artifact-path> --json")

---

Execution (5-Phase)

Phase 1: Task Discovery

See SKILL.md Shared Infrastructure -> Worker Phase 1: Task Discovery

Standard task discovery flow: TaskList -> filter by prefix PLAN-* + owner match + pending + unblocked -> TaskGet -> TaskUpdate in_progress.

Resume Artifact Check: Check whether this task's output artifact already exists:

• <session>/phase-N/context.md exists -> skip to Phase 3
• Artifact incomplete or missing -> normal Phase 2-4 execution

Phase 2: Research (via command)

Objective: Gather codebase context for plan generation.

Loading steps:

Input	Source	Required
roadmap.md	/roadmap.md	Yes
Prior phase summaries	/phase-/summary-.md	No
Wisdom	/wisdom/	No

Delegate to commands/research.md:

Step	Action
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 progress via team_msg:

mcp__ccw-tools__team_msg({
  operation: "log", session_id: sessionId,
  from: "planner",
  type: "plan_progress",
  ref: "<session>/phase-<N>/context.md"
})

Phase 3: Create Plans (via command)

Objective: Generate wave-based execution plans.

Delegate to commands/create-plans.md:

Step	Action
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

Objective: Verify task JSONs before reporting.

Validation checks:

Check	Method	Pass Criteria
Referenced files exist	test -f <path> for modify actions	All files found or warning logged
Self-dependency	Check if depends_on includes own ID	No self-dependencies
Convergence criteria	Check convergence.criteria exists	Each task has criteria
Cross-dependency	Verify all depends_on IDs exist	All dependencies valid

Validation steps:

1. File existence check (for modify actions):

   • For each task file with action="modify"
   • Check file exists
   • Log warning if not found

2. Self-dependency check:

   • For each task, verify task.id not in task.depends_on
   • Log error if self-dependency detected

3. Convergence criteria check:

   • Verify each task has convergence.criteria array
   • Log warning if missing

4. Cross-dependency validation:

   • Collect all task IDs
   • Verify each depends_on reference exists
   • Log warning if unknown dependency

Phase 5: Report to Coordinator

See SKILL.md Shared Infrastructure -> Worker Phase 5: Report

Standard report flow: team_msg log -> SendMessage with [planner] prefix -> TaskUpdate completed -> Loop to Phase 1 for next task.

Wave count computation:

Step	Action
1	Start with wave=1, assigned=set()
2	Find tasks with all dependencies in assigned
3	Assign those tasks to current wave, add to assigned
4	Increment wave, repeat until all tasks assigned
5	Return wave count

Report message:

SendMessage({
  message: "[planner] Phase <N> planning complete.
- Tasks: <count>
- Waves: <wave-count>
- IMPL_PLAN: <session>/phase-<N>/IMPL_PLAN.md
- Task JSONs: <file-list>

All tasks validated. Ready for execution."
})

---

Error Handling

Scenario	Resolution
No PLAN-* tasks available	Idle, wait for coordinator assignment
Context/Plan file not found	Notify coordinator, request location
Command file not found	Fall back to inline execution
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
Critical issue beyond scope	SendMessage fix_required to coordinator
Unexpected error	Log error via team_msg, report to coordinator