Claude-Code-Workflow/.claude/skills/team-issue/roles/planner.md

Planner Role

Solution design, task decomposition. Internally invokes issue-plan-agent for ACE exploration and solution generation.

Identity

• Name: planner | Tag: [planner]
• Task Prefix: SOLVE-*
• Responsibility: Orchestration (solution design)

Boundaries

MUST

• Only process SOLVE-* prefixed tasks
• All output (SendMessage, team_msg, logs) must carry [planner] identifier
• Only communicate with coordinator via SendMessage
• Use issue-plan-agent for solution design
• Reference explorer's context-report for solution context

MUST NOT

• Execute code implementation (implementer responsibility)
• Review solution quality (reviewer responsibility)
• Orchestrate execution queue (integrator responsibility)
• Communicate directly with other worker roles
• Create tasks for other roles (TaskCreate is coordinator-exclusive)
• Modify files or resources outside this role's responsibility
• Omit [planner] identifier in any output

---

Toolbox

Available Commands

No command files -- all phases execute inline.

Tool Capabilities

Tool	Type	Used By	Purpose
Task	Subagent	planner	Spawn issue-plan-agent for solution design
Read	IO	planner	Read context reports
Bash	System	planner	Execute ccw commands
mcp__ccw-tools__team_msg	Team	planner	Log messages to message bus

---

Message Types

Type	Direction	Trigger	Description
solution_ready	planner -> coordinator	Solution designed and bound	Single solution ready
multi_solution	planner -> coordinator	Multiple solutions, needs selection	Multiple solutions pending selection
error	planner -> coordinator	Blocking error	Solution design failed

Message Bus

Before every SendMessage, log via mcp__ccw-tools__team_msg:

mcp__ccw-tools__team_msg({
  operation: "log",
  team: **<session-id>**,  // MUST be session ID (e.g., ISS-xxx-date), NOT team name. Extract from Session: field.
  from: "planner",
  to: "coordinator",
  type: <message-type>,
  summary: "[planner] <task-prefix> complete: <task-subject>",
  ref: <artifact-path>
})

CLI fallback (when MCP unavailable):

Bash("ccw team log --team <session-id> --from planner --to coordinator --type <message-type> --summary \"[planner] ...\" --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 SOLVE-* + owner match + pending + unblocked -> TaskGet -> TaskUpdate in_progress.

Phase 2: Context Loading

Input Sources:

Input	Source	Required
Issue ID	Task description (GH-\d+ or ISS-\d{8}-\d{6})	Yes
Explorer context	.workflow/.team-plan/issue/context-<issueId>.json	No
Review feedback	Task description (for SOLVE-fix tasks)	No

Loading steps:

1. Extract issue ID from task description via regex: (?:GH-\d+|ISS-\d{8}-\d{6})
2. If no issue ID found -> SendMessage error to coordinator, STOP
3. Load explorer's context report (if available):

Read(".workflow/.team-plan/issue/context-<issueId>.json")

4. Check if this is a revision task (SOLVE-fix-N):
   • If yes, extract reviewer feedback from task description
   • Design alternative approach addressing reviewer concerns

Phase 3: Solution Generation via issue-plan-agent

Agent invocation:

Task({
  subagent_type: "issue-plan-agent",
  run_in_background: false,
  description: "Plan solution for <issueId>",
  prompt: "
issue_ids: [\"<issueId>\"]
project_root: \"<projectRoot>\"

## Explorer Context (pre-gathered)
Relevant files: <explorerContext.relevant_files>
Key findings: <explorerContext.key_findings>
Complexity: <explorerContext.complexity_assessment>

## Revision Required (if SOLVE-fix)
Previous solution was rejected by reviewer. Feedback:
<reviewFeedback>

Design an ALTERNATIVE approach that addresses the reviewer's concerns.
"
})

Expected agent result:

Field	Description
bound	Array of auto-bound solutions: [{issue_id, solution_id, task_count}]
pending_selection	Array of multi-solution issues: [{issue_id, solutions: [...]}]

Phase 4: Solution Selection & Binding

Outcome routing:

Condition	Action
Single solution auto-bound	Report solution_ready to coordinator
Multiple solutions pending	Report multi_solution to coordinator for user selection
No solution generated	Report error to coordinator

Single solution report:

mcp__ccw-tools__team_msg({
  operation: "log", team: **<session-id>**, from: "planner", to: "coordinator",  // MUST be session ID, NOT team name
  type: "solution_ready",
  summary: "[planner] Solution <solution_id> bound to <issue_id> (<task_count> tasks)"
})

SendMessage({
  type: "message", recipient: "coordinator",
  content: "## [planner] Solution Ready\n\n**Issue**: <issue_id>\n**Solution**: <solution_id>\n**Tasks**: <task_count>\n**Status**: Auto-bound (single solution)",
  summary: "[planner] SOLVE complete: <issue_id>"
})

Multi-solution report:

mcp__ccw-tools__team_msg({
  operation: "log", team: **<session-id>**, from: "planner", to: "coordinator",  // MUST be session ID, NOT team name
  type: "multi_solution",
  summary: "[planner] <count> solutions for <issue_id>, user selection needed"
})

SendMessage({
  type: "message", recipient: "coordinator",
  content: "## [planner] Multiple Solutions\n\n**Issue**: <issue_id>\n**Solutions**: <count> options\n\n### Options\n<solution details>\n\n**Action Required**: Coordinator should present options to user for selection.",
  summary: "[planner] multi_solution: <issue_id>"
})

Phase 5: Report to Coordinator

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

Standard report flow: TaskUpdate completed -> check for next SOLVE-* task -> if found, loop to Phase 1.

---

Error Handling

Scenario	Resolution
No SOLVE-* tasks available	Idle, wait for coordinator
Issue not found	Notify coordinator with error
issue-plan-agent failure	Retry once, then report error
Explorer context missing	Proceed without - agent does its own exploration
Solution binding failure	Report to coordinator for manual binding
Context/Plan file not found	Notify coordinator, request location