claude-code-workflow 7.2.23 → 7.2.25

package/.codex/skills/team-ultra-analyze/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: team-ultra-analyze
 description: Deep collaborative analysis team skill. All roles route via this SKILL.md. Beat model is coordinator-only (monitor.md). Structure is roles/ + specs/. Triggers on "team ultra-analyze", "team analyze".
-allowed-tools: spawn_agent(*), wait_agent(*), send_input(*), close_agent(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*)
+allowed-tools: spawn_agent(*), wait_agent(*), send_message(*), assign_task(*), close_agent(*), list_agents(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*)
 ---
 
 # Team Ultra Analyze
@@ -62,7 +62,8 @@ Before calling ANY tool, apply this check:
 
 | Tool Call | Verdict | Reason |
 |-----------|---------|--------|
-| `spawn_agent`, `wait_agent`, `close_agent`, `send_input` | ALLOWED | Orchestration |
+| `spawn_agent`, `wait_agent`, `close_agent`, `send_message`, `assign_task` | ALLOWED | Orchestration |
+| `list_agents` | ALLOWED | Agent health check |
 | `request_user_input` | ALLOWED | User interaction |
 | `mcp__ccw-tools__team_msg` | ALLOWED | Message bus |
 | `Read/Write` on `.workflow/.team/` files | ALLOWED | Session state |
@@ -93,6 +94,8 @@ Coordinator spawns workers using this template:
 ```
 spawn_agent({
   agent_type: "team_worker",
+  task_name: "<task-id>",
+  fork_context: false,
   items: [
     { type: "text", text: `## Role Assignment
 role: <role>
@@ -116,7 +119,29 @@ pipeline_phase: <pipeline-phase>` },
 })
 ```
 
-After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect results, then `close_agent({ id })` each worker.
+After spawning, use `wait_agent({ targets: [...], timeout_ms: 900000 })` to collect results, then `close_agent({ target })` each worker.
+
+
+### Model Selection Guide
+
+| Role | model | reasoning_effort | Rationale |
+|------|-------|-------------------|-----------|
+| Explorer (EXPLORE-*) | (default) | medium | File reading and pattern scanning, less reasoning needed |
+| Analyst (ANALYZE-*) | (default) | high | Deep analysis requires full reasoning |
+| Discussant (DISCUSS-*) | (default) | high | Synthesis of multiple viewpoints, dialectic reasoning |
+| Synthesizer (SYNTH-*) | (default) | medium | Aggregation and summary over generation |
+
+Override model/reasoning_effort in spawn_agent when cost optimization is needed:
+```
+spawn_agent({
+  agent_type: "team_worker",
+  task_name: "<task-id>",
+  fork_context: false,
+  model: "<model-override>",
+  reasoning_effort: "<effort-level>",
+  items: [...]
+})
+```
 
 ## User Commands
 
@@ -148,6 +173,51 @@ After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect
 |   +-- issues.md
 ```
 
+## v4 Agent Coordination
+
+### Message Semantics
+
+| Intent | API | Example |
+|--------|-----|---------|
+| Send exploration findings to running analysts | `send_message` | Queue upstream context without interrupting ANALYZE-* workers |
+| Not used in this skill | `assign_task` | No resident agents -- all workers are one-shot |
+| Check running agents | `list_agents` | Verify parallel explorer/analyst health during resume |
+
+### Parallel Phase Coordination
+
+Standard/Deep modes spawn N parallel agents in EXPLORE and ANALYZE phases. Use batch spawn + wait:
+
+```
+// EXPLORE phase: spawn N explorers in parallel
+const explorerNames = ["EXPLORE-001", "EXPLORE-002", ..., "EXPLORE-00N"]
+for (const name of explorerNames) {
+  spawn_agent({ agent_type: "team_worker", task_name: name, ... })
+}
+wait_agent({ targets: explorerNames, timeout_ms: 900000 })
+// Collect all results, then spawn ANALYZE phase
+
+// ANALYZE phase: send exploration context to analysts via items (not send_message)
+// since analysts are spawned AFTER explorers complete
+```
+
+### Agent Health Check
+
+Use `list_agents({})` in handleResume and handleComplete:
+
+```
+// Reconcile session state with actual running agents
+const running = list_agents({})
+// Compare with tasks.json active_agents
+// Reset orphaned tasks (in_progress but agent gone) to pending
+// Critical for parallel phases -- multiple agents may crash independently
+```
+
+### Named Agent Targeting
+
+Workers are spawned with `task_name: "<task-id>"` enabling direct addressing:
+- `send_message({ target: "ANALYZE-001", items: [...] })` -- queue supplementary exploration findings
+- `close_agent({ target: "EXPLORE-001" })` -- cleanup by name after wait_agent returns
+
 ## Completion Action
 
 When pipeline completes, coordinator presents:

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

@@ -1,90 +1,90 @@
----
-role: analyst
-prefix: ANALYZE
-inner_loop: false
-additional_prefixes: [ANALYZE-fix]
-message_types:
-  success: analysis_ready
-  error: error
----
-
-# Deep Analyst
-
-Perform deep multi-perspective analysis on exploration results via CLI tools. Generate structured insights, discussion points, and recommendations with confidence levels.
-
-## Phase 2: Context Loading
-
-| Input | Source | Required |
-|-------|--------|----------|
-| Task description | From task subject/description | Yes |
-| Session path | Extracted from task description | Yes |
-| Exploration results | `<session>/explorations/*.json` | Yes |
-
-1. Extract session path, topic, perspective, dimensions from task description
-2. Detect direction-fix mode: `type:\s*direction-fix` with `adjusted_focus:\s*(.+)`
-3. Load corresponding exploration results:
-
-| Condition | Source |
-|-----------|--------|
-| Direction fix | Read ALL exploration files, merge context |
-| Normal ANALYZE-N | Read exploration matching number N |
-| Fallback | Read first available exploration file |
-
-4. Select CLI tool by perspective:
-
-| Perspective | CLI Tool | Rule Template |
-|-------------|----------|---------------|
-| technical | gemini | analysis-analyze-code-patterns |
-| architectural | claude | analysis-review-architecture |
-| business | codex | analysis-analyze-code-patterns |
-| domain_expert | gemini | analysis-analyze-code-patterns |
-| direction-fix (any) | gemini | analysis-diagnose-bug-root-cause |
-
-## Phase 3: Deep Analysis via CLI
-
-Build analysis prompt with exploration context:
-
-```
-PURPOSE: <Normal: "Deep analysis of '<topic>' from <perspective> perspective">
-         <Fix: "Supplementary analysis with adjusted focus on '<adjusted_focus>'">
-Success: Actionable insights with confidence levels and evidence references
-
-PRIOR EXPLORATION CONTEXT:
-- Key files: <top 5-8 files from exploration>
-- Patterns found: <top 3-5 patterns>
-- Key findings: <top 3-5 findings>
-
-TASK:
-- <perspective-specific analysis tasks>
-- Generate structured findings with confidence levels (high/medium/low)
-- Identify discussion points requiring user input
-- List open questions needing further exploration
-
-MODE: analysis
-CONTEXT: @**/* | Topic: <topic>
-EXPECTED: Structured analysis with: key_insights, key_findings, discussion_points, open_questions, recommendations
-CONSTRAINTS: Focus on <perspective> perspective | <dimensions>
-```
-
-Execute: `ccw cli -p "<prompt>" --tool <cli-tool> --mode analysis --rule <rule>`
-
-## Phase 4: Result Aggregation
-
-Write analysis output to `<session>/analyses/analysis-<num>.json`:
-
-```json
-{
-  "perspective": "<perspective>",
-  "dimensions": ["<dim1>", "<dim2>"],
-  "is_direction_fix": false,
-  "key_insights": [{"insight": "...", "confidence": "high", "evidence": "file:line"}],
-  "key_findings": [{"finding": "...", "file_ref": "...", "impact": "..."}],
-  "discussion_points": ["..."],
-  "open_questions": ["..."],
-  "recommendations": [{"action": "...", "rationale": "...", "priority": "high"}],
-  "_metadata": {"cli_tool": "...", "cli_rule": "...", "perspective": "...", "timestamp": "..."}
-}
-```
-
-Update `<session>/wisdom/.msg/meta.json` under `analyst` namespace:
-- Read existing -> merge `{ "analyst": { perspective, insight_count, finding_count, is_direction_fix } }` -> write back
+---
+role: analyst
+prefix: ANALYZE
+inner_loop: false
+additional_prefixes: [ANALYZE-fix]
+message_types:
+  success: analysis_ready
+  error: error
+---
+
+# Deep Analyst
+
+Perform deep multi-perspective analysis on exploration results via CLI tools. Generate structured insights, discussion points, and recommendations with confidence levels.
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From task subject/description | Yes |
+| Session path | Extracted from task description | Yes |
+| Exploration results | `<session>/explorations/*.json` | Yes |
+
+1. Extract session path, topic, perspective, dimensions from task description
+2. Detect direction-fix mode: `type:\s*direction-fix` with `adjusted_focus:\s*(.+)`
+3. Load corresponding exploration results:
+
+| Condition | Source |
+|-----------|--------|
+| Direction fix | Read ALL exploration files, merge context |
+| Normal ANALYZE-N | Read exploration matching number N |
+| Fallback | Read first available exploration file |
+
+4. Select CLI tool by perspective:
+
+| Perspective | CLI Tool | Rule Template |
+|-------------|----------|---------------|
+| technical | gemini | analysis-analyze-code-patterns |
+| architectural | claude | analysis-review-architecture |
+| business | codex | analysis-analyze-code-patterns |
+| domain_expert | gemini | analysis-analyze-code-patterns |
+| direction-fix (any) | gemini | analysis-diagnose-bug-root-cause |
+
+## Phase 3: Deep Analysis via CLI
+
+Build analysis prompt with exploration context:
+
+```
+PURPOSE: <Normal: "Deep analysis of '<topic>' from <perspective> perspective">
+         <Fix: "Supplementary analysis with adjusted focus on '<adjusted_focus>'">
+Success: Actionable insights with confidence levels and evidence references
+
+PRIOR EXPLORATION CONTEXT:
+- Key files: <top 5-8 files from exploration>
+- Patterns found: <top 3-5 patterns>
+- Key findings: <top 3-5 findings>
+
+TASK:
+- <perspective-specific analysis tasks>
+- Generate structured findings with confidence levels (high/medium/low)
+- Identify discussion points requiring user input
+- List open questions needing further exploration
+
+MODE: analysis
+CONTEXT: @**/* | Topic: <topic>
+EXPECTED: Structured analysis with: key_insights, key_findings, discussion_points, open_questions, recommendations
+CONSTRAINTS: Focus on <perspective> perspective | <dimensions>
+```
+
+Execute: `ccw cli -p "<prompt>" --tool <cli-tool> --mode analysis --rule <rule>`
+
+## Phase 4: Result Aggregation
+
+Write analysis output to `<session>/analyses/analysis-<num>.json`:
+
+```json
+{
+  "perspective": "<perspective>",
+  "dimensions": ["<dim1>", "<dim2>"],
+  "is_direction_fix": false,
+  "key_insights": [{"insight": "...", "confidence": "high", "evidence": "file:line"}],
+  "key_findings": [{"finding": "...", "file_ref": "...", "impact": "..."}],
+  "discussion_points": ["..."],
+  "open_questions": ["..."],
+  "recommendations": [{"action": "...", "rationale": "...", "priority": "high"}],
+  "_metadata": {"cli_tool": "...", "cli_rule": "...", "perspective": "...", "timestamp": "..."}
+}
+```
+
+Update `<session>/wisdom/.msg/meta.json` under `analyst` namespace:
+- Read existing -> merge `{ "analyst": { perspective, insight_count, finding_count, is_direction_fix } }` -> write back

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

@@ -1,73 +1,73 @@
-# Analyze Task
-
-Parse topic -> detect pipeline mode and perspectives -> output analysis config.
-
-**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
-
-## Signal Detection
-
-### Pipeline Mode Detection
-
-Parse `--mode` from arguments first. If not specified, auto-detect from topic description:
-
-| Condition | Mode | Depth |
-|-----------|------|-------|
-| `--mode=quick` or topic contains "quick/overview/fast" | Quick | 1 |
-| `--mode=deep` or topic contains "deep/thorough/detailed/comprehensive" | Deep | N (from perspectives) |
-| Default (no match) | Standard | N (from perspectives) |
-
-### Dimension Detection
-
-Scan topic keywords to select analysis perspectives:
-
-| Dimension | Keywords |
-|-----------|----------|
-| architecture | architecture, design, structure |
-| implementation | implement, code, source |
-| performance | performance, optimize, speed |
-| security | security, auth, vulnerability |
-| concept | concept, theory, principle |
-| comparison | compare, vs, difference |
-| decision | decision, choice, tradeoff |
-
-**Depth** = number of selected perspectives. Quick mode always uses depth=1.
-
-## Pipeline Mode Rules
-
-| Mode | Task Structure |
-|------|----------------|
-| quick | EXPLORE-001 -> ANALYZE-001 -> SYNTH-001 (serial, depth=1) |
-| standard | EXPLORE-001..N (parallel) -> ANALYZE-001..N (parallel) -> DISCUSS-001 -> SYNTH-001 |
-| deep | Same as standard but SYNTH-001 omitted (created dynamically after discussion loop) |
-
-## Output
-
-Write analysis config to coordinator state (not a file), to be used by dispatch.md:
-
-```json
-{
-  "pipeline_mode": "<quick|standard|deep>",
-  "depth": <number>,
-  "perspectives": ["<perspective1>", "<perspective2>"],
-  "topic": "<original topic>",
-  "dimensions": ["<dim1>", "<dim2>"]
-}
-```
-
-## Complexity Scoring
-
-| Factor | Points |
-|--------|--------|
-| Per perspective | +1 |
-| Deep mode | +2 |
-| Cross-domain (3+ perspectives) | +1 |
-
-Results: 1-3 Quick, 4-6 Standard, 7+ Deep (if not explicitly set)
-
-## Discussion Loop Configuration
-
-| Mode | Max Discussion Rounds |
-|------|----------------------|
-| quick | 0 |
-| standard | 1 |
-| deep | 5 |
+# Analyze Task
+
+Parse topic -> detect pipeline mode and perspectives -> output analysis config.
+
+**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
+
+## Signal Detection
+
+### Pipeline Mode Detection
+
+Parse `--mode` from arguments first. If not specified, auto-detect from topic description:
+
+| Condition | Mode | Depth |
+|-----------|------|-------|
+| `--mode=quick` or topic contains "quick/overview/fast" | Quick | 1 |
+| `--mode=deep` or topic contains "deep/thorough/detailed/comprehensive" | Deep | N (from perspectives) |
+| Default (no match) | Standard | N (from perspectives) |
+
+### Dimension Detection
+
+Scan topic keywords to select analysis perspectives:
+
+| Dimension | Keywords |
+|-----------|----------|
+| architecture | architecture, design, structure |
+| implementation | implement, code, source |
+| performance | performance, optimize, speed |
+| security | security, auth, vulnerability |
+| concept | concept, theory, principle |
+| comparison | compare, vs, difference |
+| decision | decision, choice, tradeoff |
+
+**Depth** = number of selected perspectives. Quick mode always uses depth=1.
+
+## Pipeline Mode Rules
+
+| Mode | Task Structure |
+|------|----------------|
+| quick | EXPLORE-001 -> ANALYZE-001 -> SYNTH-001 (serial, depth=1) |
+| standard | EXPLORE-001..N (parallel) -> ANALYZE-001..N (parallel) -> DISCUSS-001 -> SYNTH-001 |
+| deep | Same as standard but SYNTH-001 omitted (created dynamically after discussion loop) |
+
+## Output
+
+Write analysis config to coordinator state (not a file), to be used by dispatch.md:
+
+```json
+{
+  "pipeline_mode": "<quick|standard|deep>",
+  "depth": <number>,
+  "perspectives": ["<perspective1>", "<perspective2>"],
+  "topic": "<original topic>",
+  "dimensions": ["<dim1>", "<dim2>"]
+}
+```
+
+## Complexity Scoring
+
+| Factor | Points |
+|--------|--------|
+| Per perspective | +1 |
+| Deep mode | +2 |
+| Cross-domain (3+ perspectives) | +1 |
+
+Results: 1-3 Quick, 4-6 Standard, 7+ Deep (if not explicitly set)
+
+## Discussion Loop Configuration
+
+| Mode | Max Discussion Rounds |
+|------|----------------------|
+| quick | 0 |
+| standard | 1 |
+| deep | 5 |

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

@@ -210,6 +210,7 @@ state.tasks[taskId].status = 'in_progress'
 // 2) Spawn worker
 const agentId = spawn_agent({
   agent_type: "team_worker",
+  task_name: taskId,  // e.g., "EXPLORE-001" — enables named targeting
   items: [
     { type: "text", text: `## Role Assignment
 role: ${role}
@@ -236,15 +237,22 @@ state.active_agents[taskId] = { agentId, role, started_at: now }
 After spawning all ready tasks:
 
 ```javascript
-// 4) Batch wait for all spawned workers
-const agentIds = Object.values(state.active_agents)
-  .map(a => a.agentId)
-wait_agent({ ids: agentIds })
-
-// 5) Collect results and update tasks.json
-for (const [taskId, agent] of Object.entries(state.active_agents)) {
-  state.tasks[taskId].status = 'completed'
-  delete state.active_agents[taskId]
+// 4) Batch wait — use task_name for stable targeting (v4)
+const taskNames = Object.keys(state.active_agents)
+const waitResult = wait_agent({ targets: taskNames, timeout_ms: 900000 })
+if (waitResult.timed_out) {
+  for (const taskId of taskNames) {
+    state.tasks[taskId].status = 'timed_out'
+    close_agent({ target: taskId })
+    delete state.active_agents[taskId]
+  }
+} else {
+  // 5) Collect results and update tasks.json
+  for (const [taskId, agent] of Object.entries(state.active_agents)) {
+    state.tasks[taskId].status = 'completed'
+    close_agent({ target: taskId })  // Use task_name, not agentId
+    delete state.active_agents[taskId]
+  }
 }
 ```
 
@@ -258,6 +266,21 @@ for (const [taskId, agent] of Object.entries(state.active_agents)) {
 | all | DISCUSS phase | One discussant at a time |
 | all | SYNTH phase | One synthesizer |
 
+**Cross-Agent Supplementary Context** (v4):
+
+When spawning workers in a later pipeline phase, send upstream results as supplementary context to already-running workers:
+
+```
+// Example: Send exploration results to running analysts
+send_message({
+  target: "<running-agent-task-name>",
+  items: [{ type: "text", text: `## Supplementary Context\n${upstreamFindings}` }]
+})
+// Note: send_message queues info without interrupting the agent's current work
+```
+
+Use `send_message` (not `assign_task`) for supplementary info that enriches but doesn't redirect the agent's current task.
+
 5. **STOP** after processing -- wait for next event
 
 ### handleCheck
@@ -282,6 +305,16 @@ Output status -- do NOT advance pipeline.
 
 ### handleResume
 
+**Agent Health Check** (v4):
+```
+// Verify actual running agents match session state
+const runningAgents = list_agents({})
+// For each active_agent in tasks.json:
+//   - If agent NOT in runningAgents -> agent crashed
+//   - Reset that task to pending, remove from active_agents
+// This prevents stale agent references from blocking the pipeline
+```
+
 Resume pipeline after user pause or interruption.
 
 1. Audit tasks.json for inconsistencies:
@@ -291,6 +324,14 @@ Resume pipeline after user pause or interruption.
 
 ### handleComplete
 
+**Cleanup Verification** (v4):
+```
+// Verify all agents are properly closed
+const remaining = list_agents({})
+// If any team agents still running -> close_agent each
+// Ensures clean session shutdown
+```
+
 Triggered when all pipeline tasks are completed.
 
 **Completion check**: