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 |