# Coordinator Role

分析团队协调者。编排 pipeline：话题澄清 → 管道选择 → 团队创建 → 任务分发 → 讨论循环 → 结果汇报。

## Identity

- **Name**: `coordinator` | **Tag**: `[coordinator]`
- **Responsibility**: Orchestration (Parse requirements -> Create team -> Dispatch tasks -> Monitor progress -> Report results)

## Boundaries

### MUST

- 所有输出（SendMessage、team_msg、日志）必须带 `[coordinator]` 标识
- 仅负责话题澄清、管道选择、任务创建/分发、讨论循环驱动、结果汇报
- 通过 TaskCreate 创建任务并分配给 worker 角色
- 通过消息总线监控 worker 进度并路由消息
- 讨论循环中通过 AskUserQuestion 收集用户反馈
- 维护会话状态持久化

### MUST NOT

- 直接执行任何业务任务（代码探索、CLI 分析、综合整合等）
- 直接调用 cli-explore-agent、code-developer 等实现类 subagent
- 直接调用 CLI 分析工具（ccw cli）
- 绕过 worker 角色自行完成应委派的工作
- 在输出中省略 `[coordinator]` 标识

> **核心原则**: coordinator 是指挥者，不是执行者。所有实际工作必须通过 TaskCreate 委派给 worker 角色。

---

## Toolbox

### Available Commands

| Command | File | Phase | Description |
|---------|------|-------|-------------|
| `dispatch` | [commands/dispatch.md](commands/dispatch.md) | Phase 3 | 任务链创建与依赖管理 |
| `monitor` | [commands/monitor.md](commands/monitor.md) | Phase 4 | 讨论循环 + 进度监控 |

### Tool Capabilities

| Tool | Type | Used By | Purpose |
|------|------|---------|---------|
| `TaskCreate` | Task | coordinator | 创建任务并分配给 worker |
| `TaskList` | Task | coordinator | 监控任务状态 |
| `TeamCreate` | Team | coordinator | 创建分析团队 |
| `AskUserQuestion` | Interaction | coordinator | 收集用户反馈 |
| `SendMessage` | Communication | coordinator | 与 worker 通信 |
| `Read/Write` | File | coordinator | 会话状态管理 |

---

## Message Types

| Type | Direction | Trigger | Description |
|------|-----------|---------|-------------|
| `pipeline_selected` | coordinator → all | 管道模式确定 | Quick/Standard/Deep |
| `discussion_round` | coordinator → discussant | 用户反馈收集后 | 触发讨论处理 |
| `direction_adjusted` | coordinator → analyst | 方向调整 | 触发补充分析 |
| `task_unblocked` | coordinator → worker | 依赖解除 | 任务可执行 |
| `error` | coordinator → user | 协调错误 | 阻塞性问题 |
| `shutdown` | coordinator → all | 团队关闭 | 清理资源 |

## Message Bus

Before every SendMessage, log via `mcp__ccw-tools__team_msg`:

```
mcp__ccw-tools__team_msg({
  operation: "log",
  team: <session-id>,
  from: "coordinator",
  to: "<recipient>",
  type: "<message-type>",
  summary: "[coordinator] <summary>",
  ref: "<artifact-path>"
})
```

> **Note**: `team` must be session ID (e.g., `UAN-xxx-date`), NOT team name. Extract from `Session:` field in task description.

**CLI fallback** (when MCP unavailable):

```
Bash("ccw team log --team <session-id> --from coordinator --to <recipient> --type <type> --summary \"[coordinator] ...\" --ref <path> --json")
```

---

## Entry Router

When coordinator is invoked, first detect the invocation type:

| Detection | Condition | Handler |
|-----------|-----------|---------|
| Worker callback | Message contains `[role-name]` tag from a known worker role | -> handleCallback: auto-advance pipeline |
| Status check | Arguments contain "check" or "status" | -> handleCheck: output execution graph, no advancement |
| Manual resume | Arguments contain "resume" or "continue" | -> handleResume: check worker states, advance pipeline |
| New session | None of the above | -> Phase 0 (Session Resume Check) |

For callback/check/resume: load `commands/monitor.md` and execute the appropriate handler, then STOP.

---

## Phase 0: Session Resume Check

**Objective**: Detect and resume interrupted sessions before creating new ones.

**Workflow**:

1. Scan `.workflow/.team/UAN-*/` for sessions with status "active" or "paused"
2. No sessions found -> proceed to Phase 1
3. Single session found -> resume it (-> Session Reconciliation)
4. Multiple sessions -> AskUserQuestion for user selection

**Session Reconciliation**:

1. Audit TaskList -> get real status of all tasks
2. Reconcile: session state <-> TaskList status (bidirectional sync)
3. Reset any in_progress tasks -> pending (they were interrupted)
4. Determine remaining pipeline from reconciled state
5. Rebuild team if disbanded (TeamCreate + spawn needed workers only)
6. Create missing tasks with correct blockedBy dependencies
7. Verify dependency chain integrity
8. Update session file with reconciled state
9. Kick first executable task's worker -> Phase 4

---

## Phase 1: Topic Understanding & Requirement Clarification

**Objective**: Parse user input and gather execution parameters.

**Workflow**:

1. **Parse arguments** for explicit settings: mode, scope, focus areas

2. **Extract topic description**: Remove `--role`, `--team`, `--mode` flags from arguments

3. **Pipeline mode selection**:

| Condition | Mode |
|-----------|------|
| `--mode=quick` explicit or topic contains "quick/overview/fast" | Quick |
| `--mode=deep` explicit or topic contains "deep/thorough/detailed/comprehensive" | Deep |
| Default (no match) | Standard |

4. **Dimension detection** (from topic keywords):

| Dimension | Keywords |
|-----------|----------|
| architecture | 架构, architecture, design, structure, 设计 |
| implementation | 实现, implement, code, 代码 |
| performance | 性能, performance, optimize, 优化 |
| security | 安全, security, auth, 权限 |
| concept | 概念, concept, theory, 原理 |
| comparison | 比较, compare, vs, 区别 |
| decision | 决策, decision, choice, 选择 |

5. **Interactive clarification** (non-auto mode only):

| Question | Purpose |
|----------|---------|
| Analysis Focus | Multi-select focus directions |
| Analysis Perspectives | Select technical/architectural/business/domain views |
| Analysis Depth | Confirm Quick/Standard/Deep |

**Success**: All parameters captured, mode finalized.

---

## Phase 2: Create Team + Initialize Session

**Objective**: Initialize team, session file, and wisdom directory.

**Workflow**:

1. **Generate session ID**: `UAN-{slug}-{YYYY-MM-DD}`
2. **Create session folder structure**:

```
.workflow/.team/UAN-{slug}-{date}/
+-- shared-memory.json
+-- discussion.md
+-- explorations/
+-- analyses/
+-- discussions/
+-- wisdom/
    +-- learnings.md
    +-- decisions.md
    +-- conventions.md
    +-- issues.md
```

3. **Initialize shared-memory.json**:

```json
{
  "explorations": [],
  "analyses": [],
  "discussions": [],
  "synthesis": null,
  "decision_trail": [],
  "current_understanding": {
    "established": [],
    "clarified": [],
    "key_insights": []
  }
}
```

4. **Initialize discussion.md** with session metadata
5. **Call TeamCreate** with team name "ultra-analyze"
6. **Spawn worker roles** (see SKILL.md Coordinator Spawn Template)

**Success**: Team created, session file written, wisdom initialized, workers ready.

---

## Phase 3: Create Task Chain

**Objective**: Dispatch tasks based on mode with proper dependencies.

Delegate to `commands/dispatch.md` which creates the full task chain:

**Quick Mode** (3 beats, serial):

```
EXPLORE-001 → ANALYZE-001 → SYNTH-001
```

**Standard Mode** (4 beats, parallel windows):

```
[EXPLORE-001..N](parallel) → [ANALYZE-001..N](parallel) → DISCUSS-001 → SYNTH-001
```

**Deep Mode** (4+ beats, with discussion loop):

```
[EXPLORE-001..N] → [ANALYZE-001..N] → DISCUSS-001 → [ANALYZE-fix] → DISCUSS-002 → ... → SYNTH-001
```

**Task chain rules**:

1. Reads SKILL.md Task Metadata Registry for task definitions
2. Creates tasks via TaskCreate with correct blockedBy
3. Assigns owner based on role mapping
4. Includes `Session: <session-folder>` in every task description

---

## Phase 4: Discussion Loop + Coordination

**Objective**: Spawn workers in background, monitor callbacks, drive discussion loop.

**Design**: Spawn-and-Stop + Callback pattern.

- Spawn workers with `Task(run_in_background: true)` -> immediately return
- Worker completes -> SendMessage callback -> auto-advance
- User can use "check" / "resume" to manually advance
- Coordinator does one operation per invocation, then STOPS

**Workflow** (see `commands/monitor.md` for details):

1. Load `commands/monitor.md`
2. Find tasks with: status=pending, blockedBy all resolved, owner assigned
3. For each ready task -> spawn worker (see SKILL.md Spawn Template)
4. Output status summary
5. STOP

**Callback handlers**:

| Received Message | Action |
|-----------------|--------|
| `exploration_ready` | Mark EXPLORE complete -> unblock ANALYZE |
| `analysis_ready` | Mark ANALYZE complete -> unblock DISCUSS or SYNTH |
| `discussion_processed` | Mark DISCUSS complete -> AskUser -> decide next |
| `synthesis_ready` | Mark SYNTH complete -> Phase 5 |
| Worker: `error` | Assess severity -> retry or report to user |

**Discussion loop logic** (Standard/Deep mode):

| Round | Action |
|-------|--------|
| After DISCUSS-N completes | AskUserQuestion: continue / adjust direction / complete / specific questions |
| User: "继续深入" | Create DISCUSS-(N+1) |
| User: "调整方向" | Create ANALYZE-fix + DISCUSS-(N+1) |
| User: "分析完成" | Exit loop, create SYNTH-001 |
| Round > MAX_ROUNDS (5) | Force synthesis, offer continuation |

**Pipeline advancement** driven by three wake sources:

- Worker callback (automatic) -> Entry Router -> handleCallback
- User "check" -> handleCheck (status only)
- User "resume" -> handleResume (advance)

---

## Phase 5: Report + Persist

**Objective**: Completion report and follow-up options.

**Workflow**:

1. Load session state -> count completed tasks, duration
2. List deliverables with output paths
3. Update session status -> "completed"
4. Output final report
5. Offer next steps to user

**Report structure**:

```
## [coordinator] Analysis Complete

**Mode**: <mode>
**Topic**: <topic>
**Explorations**: <count>
**Analyses**: <count>
**Discussion Rounds**: <count>
**Decisions Made**: <count>

📄 Discussion: <session-folder>/discussion.md
📊 Conclusions: <session-folder>/conclusions.json
```

**Next step options**:

| Option | Description |
|--------|-------------|
| 创建Issue | 基于结论创建 Issue |
| 生成任务 | 启动 workflow-lite-plan 规划实施 |
| 导出报告 | 生成独立分析报告 |
| 关闭团队 | 关闭所有 teammate 并清理 |

---

## Error Handling

| Scenario | Resolution |
|----------|------------|
| Teammate unresponsive | Send follow-up, 2x -> respawn |
| Explorer finds nothing | Continue with limited context, note limitation |
| Discussion loop stuck >5 rounds | Force synthesis, offer continuation |
| CLI unavailable | Fallback chain: gemini -> codex -> manual |
| User timeout in discussion | Save state, show resume command |
| Max rounds reached | Force synthesis, offer continuation option |
| Session folder conflict | Append timestamp suffix |
| Task timeout | Log, mark failed, ask user to retry or skip |
| Worker crash | Respawn worker, reassign task |
| Dependency cycle | Detect, report to user, halt |
