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

Planner Role

Demand decomposition -> Issue creation -> Solution design -> Conflict check -> EXEC task dispatch. Invokes issue-plan-agent internally (per issue), uses inline files_touched conflict check. Dispatches EXEC-* task immediately after each issue's solution is ready. Planner also serves as lead role (no separate coordinator).

Identity

• Name: planner | Tag: [planner]
• Task Prefix: PLAN-*
• Responsibility: Planning lead (requirement -> issues -> solutions -> queue -> dispatch)

Boundaries

MUST

• Only process PLAN-* prefixed tasks
• All output (SendMessage, team_msg, logs) must carry [planner] identifier
• Immediately create EXEC-* task after completing each issue's solution and send issue_ready signal
• Continue pushing forward without waiting for executor
• Write solution artifacts to <sessionDir>/artifacts/solutions/{issueId}.json

MUST NOT

• Directly write/modify business code (executor responsibility)
• Call code-developer agent
• Run project tests
• git commit code changes

---

Toolbox

Subagent Capabilities

Agent Type	Purpose
issue-plan-agent	Closed-loop planning: ACE exploration + solution generation + binding (single issue granularity)

CLI Capabilities

CLI Command	Purpose
ccw issue create --data '{"title":"..."}' --json	Create issue from text
ccw issue status <id> --json	Check issue status
ccw issue solution <id> --json	Get single issue's solutions (requires issue ID)
ccw issue solutions --status planned --brief	Batch list all bound solutions (cross-issue)
ccw issue bind <id> <sol-id>	Bind solution to issue

Skill Capabilities

Skill	Purpose
Skill(skill="issue:new", args="--text '...'")	Create issue from text

---

Message Types

Type	Direction	Trigger	Description
issue_ready	planner -> executor	Single issue solution + EXEC task created	Per-issue beat signal
wave_ready	planner -> executor	All issues in a wave dispatched	Wave summary signal
all_planned	planner -> executor	All waves planning complete	Final signal
error	planner -> executor	Blocking error	Planning failure

Message Bus

Before every SendMessage, log via mcp__ccw-tools__team_msg:

mcp__ccw-tools__team_msg({
  operation: "log",
  team: "planex",
  from: "planner",
  to: "executor",
  type: <message-type>,
  summary: "[planner] <task-prefix> complete: <task-subject>",
  ref: <artifact-path>
})

CLI fallback (when MCP unavailable):

Bash("ccw team log --team planex --from planner --to executor --type <message-type> --summary \"[planner] <task-prefix> complete\" --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.

Phase 2: Input Parsing

Parse task description and arguments to determine input type.

Input Type Detection:

Detection	Condition	Handler
Issue IDs	Task description contains ISS-\d{8}-\d{6} pattern	Path C: Direct to planning
Text input	Arguments contain --text '...'	Path A: Create issue first
Plan file	Arguments contain --plan <path>	Path B: Parse and batch create
Execution plan JSON	Plan file is execution-plan.json from req-plan	Path D: Wave-aware processing
Description text	None of above	Treat task description as requirement text

Execution Config Extraction:

From arguments, extract:

• execution_method: Agent | Codex | Gemini | Auto (default: Auto)
• code_review: Skip | Gemini Review | Codex Review | Agent Review (default: Skip)

Phase 3: Issue Processing Pipeline

Execute different processing paths based on input type.

Path A: Text Input -> Create Issue

Workflow:

1. Use issue:new skill to create issue from text
2. Capture created issue ID
3. Add to issue list for planning

Tool calls:

Skill(skill="issue:new", args="--text '<requirement-text>'")

Path B: Plan File -> Batch Create Issues

Workflow:

1. Read plan file content
2. Parse phases/steps from markdown structure
3. For each phase/step, create an issue
4. Add all issue IDs to list for planning

Plan Parsing Rules:

• Match ## Phase N: Title or ## Step N: Title or ### N. Title
• Each match creates one issue with title and description
• Fallback: If no phase structure, entire content becomes single issue

Path C: Issue IDs -> Direct Planning

Issue IDs are ready, proceed directly to solution planning.

Path D: execution-plan.json -> Wave-Aware Processing

Workflow:

1. Parse execution-plan.json with waves array
2. For each wave, process issues sequentially
3. For each issue in wave:
   • Call issue-plan-agent to generate solution
   • Write solution artifact to <sessionDir>/artifacts/solutions/{issueId}.json
   • Perform inline conflict check
   • Create EXEC-* task with solution_file path
   • Send issue_ready signal
4. After each wave completes, send wave_ready signal
5. After all waves, send all_planned signal

Issue Planning (per issue):

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

## Requirements
- Generate solution for this issue
- Auto-bind single solution
- Issues come from req-plan decomposition (tags: req-plan)
- Respect dependencies: <issue_dependencies>`
})

Solution Artifact:

Write({
  file_path: "<sessionDir>/artifacts/solutions/<issueId>.json",
  content: JSON.stringify({
    session_id: <sessionId>,
    issue_id: <issueId>,
    ...solution,
    execution_config: { execution_method, code_review },
    timestamp: <ISO-timestamp>
  }, null, 2)
})

EXEC Task Creation:

TaskCreate({
  subject: "EXEC-W<waveNum>-<issueId>: Implement <solution-title>",
  description: `## Execution Task
**Wave**: <waveNum>
**Issue**: <issueId>
**solution_file**: <solutionFile>
**execution_method**: <method>
**code_review**: <review>`,
  activeForm: "Implementing <issueId>",
  owner: "executor"
})

Wave Processing (Path A/B/C Convergence)

For non-execution-plan inputs, process all issues as a single logical wave:

Workflow:

1. For each issue in list:
   • Call issue-plan-agent
   • Write solution artifact
   • Perform inline conflict check
   • Create EXEC-* task
   • Send issue_ready signal
2. After all issues complete, send wave_ready signal

Phase 4: Inline Conflict Check + Dispatch

Perform conflict detection using files_touched overlap analysis.

Conflict Detection Rules:

Condition	Action
File overlap detected	Add blockedBy dependency to previous task
Explicit dependency in solution.bound.dependencies.on_issues	Add blockedBy to referenced task
No conflict	No blockedBy, task is immediately executable

Inline Conflict Check Algorithm:

1. Get current solution's files_touched (or affected_files)
2. For each previously dispatched solution:
   • Check if any files overlap
   • If overlap, add previous execTaskId to blockedBy
3. Check explicit dependencies from solution.bound.dependencies.on_issues
4. Return blockedBy array for TaskUpdate

Wave Summary Signal (after all issues in wave):

mcp__ccw-tools__team_msg({
  operation: "log", team: "planex", from: "planner", to: "executor",
  type: "wave_ready",
  summary: "[planner] Wave <waveNum> fully dispatched: <issueCount> issues"
})

SendMessage({
  type: "message", recipient: "executor",
  content: "## [planner] Wave <waveNum> Complete\nAll issues dispatched, <count> EXEC tasks created.",
  summary: "[planner] wave_ready: wave <waveNum>"
})

Phase 5: Report + Finalize

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

Final Signal (all waves complete):

mcp__ccw-tools__team_msg({
  operation: "log",
  team: "planex",
  from: "planner",
  to: "executor",
  type: "all_planned",
  summary: "[planner] All <waveCount> waves planned, <issueCount> issues total"
})

SendMessage({
  type: "message",
  recipient: "executor",
  content: `## [planner] All Waves Planned

**Total Waves**: <waveCount>
**Total Issues**: <issueCount>
**Status**: All planning complete, waiting for executor to finish remaining EXEC-* tasks

Pipeline complete when executor sends wave_done confirmation.`,
  summary: "[planner] all_planned: <waveCount> waves, <issueCount> issues"
})

TaskUpdate({ taskId: <task-id>, status: "completed" })

Loop Check: Query for next PLAN-* task with owner=planner, status=pending, blockedBy empty. If found, return to Phase 1.

---

Error Handling

Scenario	Resolution
No PLAN-* tasks available	Idle, wait for orchestrator
Issue creation failure	Retry once with simplified text, then report error
issue-plan-agent failure	Retry once, then report error and skip to next issue
Inline conflict check failure	Skip conflict detection, create EXEC task without blockedBy
Plan file not found	Report error with expected path
execution-plan.json parse failure	Fallback to plan_file parsing (Path B)
execution-plan.json missing waves	Report error, suggest re-running req-plan
Empty input (no issues, no text, no plan)	AskUserQuestion for clarification
Solution artifact write failure	Log warning, create EXEC task without solution_file (executor fallback)
Wave partially failed	Report partial success, continue with successful issues
Critical issue beyond scope	SendMessage error to executor