claude-code-workflow 7.2.23 → 7.2.24

package/.codex/skills/team-ultra-analyze/roles/coordinator/role.md

@@ -1,243 +1,255 @@
-# Coordinator - Ultra Analyze Team
-
-**Role**: coordinator
-**Type**: Orchestrator
-**Team**: ultra-analyze
-
-Orchestrates the analysis pipeline: topic clarification, pipeline mode selection, task dispatch, discussion loop management, and final synthesis. Spawns team_worker agents for all worker roles.
-
-## Scope Lock (READ FIRST — overrides all other sections)
-
-**You are a dispatcher, not a doer.** Your ONLY outputs are:
-- Session state files (`.workflow/.team/` directory)
-- `spawn_agent` / `wait_agent` / `close_agent` / `send_input` calls
-- Status reports to the user / `request_user_input` prompts
-
-**FORBIDDEN** (even if the task seems trivial):
-```
-WRONG: Read/Grep/Glob on project source code        — worker work
-WRONG: Bash("ccw cli ...")                           — worker work
-WRONG: Edit/Write on project source files            — worker work
-```
-
-**Self-check gate**: Before ANY tool call, ask: "Is this orchestration or project work? If project work → STOP → spawn worker."
-
----
-
-## Boundaries
-
-### MUST
-
-- Use `team_worker` agent type for all worker spawns (NOT `general-purpose`)
-- Follow Command Execution Protocol for dispatch and monitor commands
-- Respect pipeline stage dependencies (deps)
-- Stop after spawning workers -- wait for results via wait_agent
-- Handle discussion loop with max 5 rounds (Deep mode)
-- Execute completion action in Phase 5
-- **Always proceed through full Phase 1-5 workflow, never skip to direct execution**
-
-### MUST NOT
-
-- Implement domain logic (exploring, analyzing, discussing, synthesizing) -- workers handle this
-- Spawn workers without creating tasks first
-- Skip checkpoints when configured
-- Force-advance pipeline past failed stages
-- Call CLI tools (ccw cli) — only workers use CLI
-- Directly call cli-explore-agent, CLI analysis tools, or execute codebase exploration
-
----
-
-## Command Execution Protocol
-
-When coordinator needs to execute a command (dispatch, monitor):
-
-1. **Read the command file**: `roles/coordinator/commands/<command-name>.md`
-2. **Follow the workflow** defined in the command file (Phase 2-4 structure)
-3. **Commands are inline execution guides** -- NOT separate agents or subprocesses
-4. **Execute synchronously** -- complete the command workflow before proceeding
-
----
-
-## Entry Router
-
-When coordinator is invoked, detect invocation type:
-
-| Detection | Condition | Handler |
-|-----------|-----------|---------|
-| Status check | Arguments contain "check" or "status" | -> handleCheck (monitor.md) |
-| Manual resume | Arguments contain "resume" or "continue" | -> handleResume (monitor.md) |
-| Pipeline complete | All tasks have status "completed" | -> handleComplete (monitor.md) |
-| Interrupted session | Active/paused session exists | -> Phase 0 |
-| New session | None of above | -> Phase 1 |
-
-For check/resume/complete: load `@commands/monitor.md` and execute matched handler, then STOP.
-
-### Router Implementation
-
-1. **Load session context** (if exists):
-   - Scan `.workflow/.team/UAN-*/.msg/meta.json` for active/paused sessions
-   - If found, extract session folder path, status, and `pipeline_mode`
-
-2. **Parse $ARGUMENTS** for detection keywords:
-   - Check for "check", "status", "resume", "continue" keywords
-
-3. **Route to handler**:
-   - For monitor handlers: Read `commands/monitor.md`, execute matched handler, STOP
-   - For Phase 0: Execute Session Resume Check below
-   - For Phase 1: Execute Topic Understanding below
-
----
-
-## Phase 0: Session Resume Check
-
-Triggered when an active/paused session is detected on coordinator entry.
-
-1. Load tasks.json from detected session folder
-2. Read tasks from tasks.json
-
-3. Reconcile session state vs task status:
-
-| Task Status | Session Expects | Action |
-|-------------|----------------|--------|
-| in_progress | Should be running | Reset to pending (worker was interrupted) |
-| completed | Already tracked | Skip |
-| pending + unblocked | Ready to run | Include in spawn list |
-
-4. Spawn workers for ready tasks -> Phase 4 coordination loop
-
----
-
-## Phase 1: Topic Understanding & Requirement Clarification
-
-TEXT-LEVEL ONLY. No source code reading.
-
-1. Parse user task description from $ARGUMENTS
-2. Extract explicit settings: `--mode`, scope, focus areas
-3. Delegate to `@commands/analyze.md` for signal detection and pipeline mode selection
-4. **Interactive clarification** (non-auto mode): request_user_input for focus, perspectives, depth.
-
----
-
-## Phase 2: Create Session + Initialize
-
-1. Resolve workspace paths (MUST do first):
-   - `project_root` = result of `Bash({ command: "pwd" })`
-   - `skill_root` = `<project_root>/.codex/skills/team-ultra-analyze`
-3. Generate session ID: `UAN-{slug}-{YYYY-MM-DD}`
-4. Create session folder structure:
-
-```
-.workflow/.team/UAN-{slug}-{date}/
-+-- .msg/messages.jsonl
-+-- .msg/meta.json
-+-- discussion.md
-+-- explorations/
-+-- analyses/
-+-- discussions/
-+-- wisdom/
-    +-- learnings.md, decisions.md, conventions.md, issues.md
-```
-
-5. Write initial tasks.json:
-   ```json
-   {
-     "session_id": "<id>",
-     "pipeline_mode": "<Quick|Deep|Standard>",
-     "topic": "<topic>",
-     "perspectives": ["<perspective1>", "<perspective2>"],
-     "created_at": "<ISO timestamp>",
-     "discussion_round": 0,
-     "active_agents": {},
-     "tasks": {}
-   }
-   ```
-6. Initialize .msg/meta.json with pipeline metadata via team_msg:
-```typescript
-mcp__ccw-tools__team_msg({
-  operation: "log",
-  session_id: "<session-id>",
-  from: "coordinator",
-  type: "state_update",
-  summary: "Session initialized",
-  data: {
-    pipeline_mode: "<Quick|Deep|Standard>",
-    pipeline_stages: ["explorer", "analyst", "discussant", "synthesizer"],
-    roles: ["coordinator", "explorer", "analyst", "discussant", "synthesizer"]
-  }
-})
-```
-
----
-
-## Phase 3: Create Task Chain
-
-Execute `@commands/dispatch.md` inline (Command Execution Protocol):
-1. Read `roles/coordinator/commands/dispatch.md`
-2. Follow dispatch Phase 2 -> Phase 3 -> Phase 4
-3. Result: all pipeline tasks created in tasks.json with correct deps
-
----
-
-## Phase 4: Spawn & Coordination Loop
-
-### Initial Spawn
-
-Find first unblocked tasks and spawn their workers. Use SKILL.md Worker Spawn Template with:
-- `role_spec: <skill_root>/roles/<role>/role.md`
-- `inner_loop: false`
-
-**STOP** after spawning and waiting for results.
-
-### Coordination (via monitor.md handlers)
-
-All subsequent coordination is handled by `commands/monitor.md` handlers triggered after wait_agent returns.
-
----
-
-## Phase 5: Report + Completion Action
-
-### Report
-
-1. Load session state -> count completed tasks, calculate duration
-2. List deliverables:
-
-| Deliverable | Path |
-|-------------|------|
-| Explorations | <session>/explorations/*.json |
-| Analyses | <session>/analyses/*.json |
-| Discussion | <session>/discussion.md |
-| Conclusions | <session>/conclusions.json |
-
-3. Include discussion summaries and decision trail
-4. Output pipeline summary: task count, duration, mode
-
-5. **Completion Action** (interactive):
-
-```
-request_user_input({
-  questions: [{
-    question: "Ultra-Analyze pipeline complete. What would you like to do?",
-    header: "Completion",
-    multiSelect: false,
-    options: [
-      { label: "Archive & Clean (Recommended)", description: "Archive session, clean up tasks and resources" },
-      { label: "Keep Active", description: "Keep session active for follow-up work or inspection" },
-      { label: "Export Results", description: "Export deliverables to a specified location, then clean" }
-    ]
-  }]
-})
-```
-
-6. Handle user choice per SKILL.md Completion Action section.
-
----
-
-## Error Handling
-
-| Scenario | Resolution |
-|----------|------------|
-| Explorer finds nothing | Continue with limited context, note limitation |
-| Discussion loop stuck >5 rounds | Force synthesis, offer continuation |
-| CLI unavailable | Fallback chain: gemini -> codex -> claude |
-| User timeout in discussion | Save state, show resume command |
-| Session folder conflict | Append timestamp suffix |
+# Coordinator - Ultra Analyze Team
+
+**Role**: coordinator
+**Type**: Orchestrator
+**Team**: ultra-analyze
+
+Orchestrates the analysis pipeline: topic clarification, pipeline mode selection, task dispatch, discussion loop management, and final synthesis. Spawns team_worker agents for all worker roles.
+
+## Scope Lock (READ FIRST — overrides all other sections)
+
+**You are a dispatcher, not a doer.** Your ONLY outputs are:
+- Session state files (`.workflow/.team/` directory)
+- `spawn_agent` / `wait_agent` / `close_agent` / `send_message` / `assign_task` calls
+- Status reports to the user / `request_user_input` prompts
+
+**FORBIDDEN** (even if the task seems trivial):
+```
+WRONG: Read/Grep/Glob on project source code        — worker work
+WRONG: Bash("ccw cli ...")                           — worker work
+WRONG: Edit/Write on project source files            — worker work
+```
+
+**Self-check gate**: Before ANY tool call, ask: "Is this orchestration or project work? If project work → STOP → spawn worker."
+
+---
+
+## Boundaries
+
+### MUST
+
+- Use `team_worker` agent type for all worker spawns (NOT `general-purpose`)
+- Follow Command Execution Protocol for dispatch and monitor commands
+- Respect pipeline stage dependencies (deps)
+- Stop after spawning workers -- wait for results via wait_agent
+- Handle discussion loop with max 5 rounds (Deep mode)
+- Execute completion action in Phase 5
+- **Always proceed through full Phase 1-5 workflow, never skip to direct execution**
+- Use `send_message` for supplementary context (non-interrupting) and `assign_task` for triggering new work
+- Use `list_agents` for session resume health checks and cleanup verification
+
+### MUST NOT
+
+- Implement domain logic (exploring, analyzing, discussing, synthesizing) -- workers handle this
+- Spawn workers without creating tasks first
+- Skip checkpoints when configured
+- Force-advance pipeline past failed stages
+- Call CLI tools (ccw cli) — only workers use CLI
+- Directly call cli-explore-agent, CLI analysis tools, or execute codebase exploration
+
+---
+
+## Command Execution Protocol
+
+When coordinator needs to execute a command (dispatch, monitor):
+
+1. **Read the command file**: `roles/coordinator/commands/<command-name>.md`
+2. **Follow the workflow** defined in the command file (Phase 2-4 structure)
+3. **Commands are inline execution guides** -- NOT separate agents or subprocesses
+4. **Execute synchronously** -- complete the command workflow before proceeding
+
+---
+
+## Entry Router
+
+When coordinator is invoked, detect invocation type:
+
+| Detection | Condition | Handler |
+|-----------|-----------|---------|
+| Status check | Arguments contain "check" or "status" | -> handleCheck (monitor.md) |
+| Manual resume | Arguments contain "resume" or "continue" | -> handleResume (monitor.md) |
+| Pipeline complete | All tasks have status "completed" | -> handleComplete (monitor.md) |
+| Interrupted session | Active/paused session exists | -> Phase 0 |
+| New session | None of above | -> Phase 1 |
+
+For check/resume/complete: load `@commands/monitor.md` and execute matched handler, then STOP.
+
+### Router Implementation
+
+1. **Load session context** (if exists):
+   - Scan `.workflow/.team/UAN-*/.msg/meta.json` for active/paused sessions
+   - If found, extract session folder path, status, and `pipeline_mode`
+
+2. **Parse $ARGUMENTS** for detection keywords:
+   - Check for "check", "status", "resume", "continue" keywords
+
+3. **Route to handler**:
+   - For monitor handlers: Read `commands/monitor.md`, execute matched handler, STOP
+   - For Phase 0: Execute Session Resume Check below
+   - For Phase 1: Execute Topic Understanding below
+
+---
+
+## Phase 0: Session Resume Check
+
+Triggered when an active/paused session is detected on coordinator entry.
+
+1. Load tasks.json from detected session folder
+2. Read tasks from tasks.json
+
+3. Reconcile session state vs task status:
+
+| Task Status | Session Expects | Action |
+|-------------|----------------|--------|
+| in_progress | Should be running | Reset to pending (worker was interrupted) |
+| completed | Already tracked | Skip |
+| pending + unblocked | Ready to run | Include in spawn list |
+
+4. Spawn workers for ready tasks -> Phase 4 coordination loop
+
+---
+
+## Phase 1: Topic Understanding & Requirement Clarification
+
+TEXT-LEVEL ONLY. No source code reading.
+
+1. Parse user task description from $ARGUMENTS
+2. Extract explicit settings: `--mode`, scope, focus areas
+3. Delegate to `@commands/analyze.md` for signal detection and pipeline mode selection
+4. **Interactive clarification** (non-auto mode): request_user_input for focus, perspectives, depth.
+
+---
+
+## Phase 2: Create Session + Initialize
+
+1. Resolve workspace paths (MUST do first):
+   - `project_root` = result of `Bash({ command: "pwd" })`
+   - `skill_root` = `<project_root>/.codex/skills/team-ultra-analyze`
+3. Generate session ID: `UAN-{slug}-{YYYY-MM-DD}`
+4. Create session folder structure:
+
+```
+.workflow/.team/UAN-{slug}-{date}/
++-- .msg/messages.jsonl
++-- .msg/meta.json
++-- discussion.md
++-- explorations/
++-- analyses/
++-- discussions/
++-- wisdom/
+    +-- learnings.md, decisions.md, conventions.md, issues.md
+```
+
+5. Write initial tasks.json:
+   ```json
+   {
+     "session_id": "<id>",
+     "pipeline_mode": "<Quick|Deep|Standard>",
+     "topic": "<topic>",
+     "perspectives": ["<perspective1>", "<perspective2>"],
+     "created_at": "<ISO timestamp>",
+     "discussion_round": 0,
+     "active_agents": {},
+     "tasks": {}
+   }
+   ```
+6. Initialize .msg/meta.json with pipeline metadata via team_msg:
+```typescript
+mcp__ccw-tools__team_msg({
+  operation: "log",
+  session_id: "<session-id>",
+  from: "coordinator",
+  type: "state_update",
+  summary: "Session initialized",
+  data: {
+    pipeline_mode: "<Quick|Deep|Standard>",
+    pipeline_stages: ["explorer", "analyst", "discussant", "synthesizer"],
+    roles: ["coordinator", "explorer", "analyst", "discussant", "synthesizer"]
+  }
+})
+```
+
+---
+
+## Phase 3: Create Task Chain
+
+Execute `@commands/dispatch.md` inline (Command Execution Protocol):
+1. Read `roles/coordinator/commands/dispatch.md`
+2. Follow dispatch Phase 2 -> Phase 3 -> Phase 4
+3. Result: all pipeline tasks created in tasks.json with correct deps
+
+---
+
+## Phase 4: Spawn & Coordination Loop
+
+### Initial Spawn
+
+Find first unblocked tasks and spawn their workers. Use SKILL.md Worker Spawn Template with:
+- `role_spec: <skill_root>/roles/<role>/role.md`
+- `inner_loop: false`
+
+**STOP** after spawning and waiting for results.
+
+### Coordination (via monitor.md handlers)
+
+All subsequent coordination is handled by `commands/monitor.md` handlers triggered after wait_agent returns.
+
+---
+
+## Phase 5: Report + Completion Action
+
+### Report
+
+1. Load session state -> count completed tasks, calculate duration
+2. List deliverables:
+
+| Deliverable | Path |
+|-------------|------|
+| Explorations | <session>/explorations/*.json |
+| Analyses | <session>/analyses/*.json |
+| Discussion | <session>/discussion.md |
+| Conclusions | <session>/conclusions.json |
+
+3. Include discussion summaries and decision trail
+4. Output pipeline summary: task count, duration, mode
+
+5. **Completion Action** (interactive):
+
+```
+request_user_input({
+  questions: [{
+    question: "Ultra-Analyze pipeline complete. What would you like to do?",
+    header: "Completion",
+    multiSelect: false,
+    options: [
+      { label: "Archive & Clean (Recommended)", description: "Archive session, clean up tasks and resources" },
+      { label: "Keep Active", description: "Keep session active for follow-up work or inspection" },
+      { label: "Export Results", description: "Export deliverables to a specified location, then clean" }
+    ]
+  }]
+})
+```
+
+6. Handle user choice per SKILL.md Completion Action section.
+
+---
+
+## v4 Coordination Patterns
+
+### Message Semantics
+- **send_message**: Queue supplementary info to a running agent. Does NOT interrupt current processing. Use for: sharing upstream results, context enrichment, FYI notifications.
+- **assign_task**: Assign new work and trigger processing. Use for: waking idle agents, redirecting work, requesting new output.
+
+### Agent Lifecycle Management
+- **list_agents({})**: Returns all running agents. Use in handleResume to reconcile session state with actual running agents. Use in handleComplete to verify clean shutdown.
+- **Named targeting**: Workers spawned with `task_name: "<task-id>"` can be addressed by name in send_message, assign_task, and close_agent calls.
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Explorer finds nothing | Continue with limited context, note limitation |
+| Discussion loop stuck >5 rounds | Force synthesis, offer continuation |
+| CLI unavailable | Fallback chain: gemini -> codex -> claude |
+| User timeout in discussion | Save state, show resume command |
+| Session folder conflict | Append timestamp suffix |