claude-code-workflow 7.2.23 → 7.2.25

package/.codex/skills/team-brainstorm/roles/synthesizer/role.md

@@ -1,57 +1,57 @@
----
-role: synthesizer
-prefix: SYNTH
-inner_loop: false
-message_types: [state_update]
----
-
-# Synthesizer
-
-Cross-idea integrator. Extracts themes from multiple ideas and challenge feedback, resolves conflicts, generates consolidated proposals.
-
-## Phase 2: Context Loading
-
-| Input | Source | Required |
-|-------|--------|----------|
-| Session folder | Task description (Session: line) | Yes |
-| All ideas | <session>/ideas/*.md files | Yes |
-| All critiques | <session>/critiques/*.md files | Yes |
-| GC rounds completed | <session>/.msg/meta.json gc_round | Yes |
-
-1. Extract session path from task description (match "Session: <path>")
-2. Glob all idea files from <session>/ideas/
-3. Glob all critique files from <session>/critiques/
-4. Read all idea and critique files for synthesis
-5. Read .msg/meta.json for context (topic, gc_round, generated_ideas, critique_insights)
-
-## Phase 3: Synthesis Execution
-
-| Step | Action |
-|------|--------|
-| 1. Theme Extraction | Identify common themes across ideas, rate strength (1-10), list supporting ideas |
-| 2. Conflict Resolution | Identify contradictory ideas, determine resolution approach, document rationale |
-| 3. Complementary Grouping | Group complementary ideas together |
-| 4. Gap Identification | Discover uncovered perspectives |
-| 5. Integrated Proposal | Generate 1-3 consolidated proposals |
-
-**Integrated Proposal Structure**:
-- Core concept description
-- Source ideas combined
-- Addressed challenges from critiques
-- Feasibility score (1-10), Innovation score (1-10)
-- Key benefits list, Remaining risks list
-
-**Output**: Write to `<session>/synthesis/synthesis-<num>.md`
-- Sections: Input summary, Extracted Themes, Conflict Resolution, Integrated Proposals, Coverage Analysis
-
-## Phase 4: Quality Check
-
-| Check | Pass Criteria | Action on Failure |
-|-------|---------------|-------------------|
-| Proposal count | >= 1 proposal | Generate at least one proposal |
-| Theme count | >= 2 themes | Look for more patterns |
-| Conflict resolution | All conflicts documented | Address unresolved conflicts |
-
-After passing checks, update shared state:
-- Set .msg/meta.json synthesis_themes
-- Each entry: name, strength, supporting_ideas
+---
+role: synthesizer
+prefix: SYNTH
+inner_loop: false
+message_types: [state_update]
+---
+
+# Synthesizer
+
+Cross-idea integrator. Extracts themes from multiple ideas and challenge feedback, resolves conflicts, generates consolidated proposals.
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Session folder | Task description (Session: line) | Yes |
+| All ideas | <session>/ideas/*.md files | Yes |
+| All critiques | <session>/critiques/*.md files | Yes |
+| GC rounds completed | <session>/.msg/meta.json gc_round | Yes |
+
+1. Extract session path from task description (match "Session: <path>")
+2. Glob all idea files from <session>/ideas/
+3. Glob all critique files from <session>/critiques/
+4. Read all idea and critique files for synthesis
+5. Read .msg/meta.json for context (topic, gc_round, generated_ideas, critique_insights)
+
+## Phase 3: Synthesis Execution
+
+| Step | Action |
+|------|--------|
+| 1. Theme Extraction | Identify common themes across ideas, rate strength (1-10), list supporting ideas |
+| 2. Conflict Resolution | Identify contradictory ideas, determine resolution approach, document rationale |
+| 3. Complementary Grouping | Group complementary ideas together |
+| 4. Gap Identification | Discover uncovered perspectives |
+| 5. Integrated Proposal | Generate 1-3 consolidated proposals |
+
+**Integrated Proposal Structure**:
+- Core concept description
+- Source ideas combined
+- Addressed challenges from critiques
+- Feasibility score (1-10), Innovation score (1-10)
+- Key benefits list, Remaining risks list
+
+**Output**: Write to `<session>/synthesis/synthesis-<num>.md`
+- Sections: Input summary, Extracted Themes, Conflict Resolution, Integrated Proposals, Coverage Analysis
+
+## Phase 4: Quality Check
+
+| Check | Pass Criteria | Action on Failure |
+|-------|---------------|-------------------|
+| Proposal count | >= 1 proposal | Generate at least one proposal |
+| Theme count | >= 2 themes | Look for more patterns |
+| Conflict resolution | All conflicts documented | Address unresolved conflicts |
+
+After passing checks, update shared state:
+- Set .msg/meta.json synthesis_themes
+- Each entry: name, strength, supporting_ideas

package/.codex/skills/team-brainstorm/specs/pipelines.md

@@ -1,72 +1,72 @@
-# Pipeline Definitions — team-brainstorm
-
-## Available Pipelines
-
-### Quick Pipeline (3 beats, strictly serial)
-
-```
-IDEA-001 → CHALLENGE-001 → SYNTH-001
-[ideator]   [challenger]   [synthesizer]
-```
-
-### Deep Pipeline (6 beats, Generator-Critic loop)
-
-```
-IDEA-001 → CHALLENGE-001 → IDEA-002(fix) → CHALLENGE-002 → SYNTH-001 → EVAL-001
-```
-
-GC loop check: if critique.severity >= HIGH → create IDEA-fix → CHALLENGE-2 → SYNTH; else skip to SYNTH
-
-### Full Pipeline (7 tasks, fan-out parallel ideation + GC)
-
-```
-[IDEA-001 + IDEA-002 + IDEA-003](parallel) → CHALLENGE-001(batch) → IDEA-004(fix) → SYNTH-001 → EVAL-001
-```
-
-## Task Metadata Registry
-
-| Task ID | Role | Phase | Dependencies | Description |
-|---------|------|-------|-------------|-------------|
-| IDEA-001 | ideator | generate | (none) | Multi-angle idea generation |
-| IDEA-002 | ideator | generate | (none) | Parallel angle (Full pipeline only) |
-| IDEA-003 | ideator | generate | (none) | Parallel angle (Full pipeline only) |
-| CHALLENGE-001 | challenger | challenge | IDEA-001 (or all IDEA-*) | Devil's advocate critique and feasibility challenge |
-| IDEA-004 | ideator | gc-fix | CHALLENGE-001 | Revision based on critique (GC loop, if triggered) |
-| CHALLENGE-002 | challenger | gc-fix | IDEA-004 | Re-critique of revised ideas (GC loop round 2) |
-| SYNTH-001 | synthesizer | synthesize | last CHALLENGE-* | Cross-idea integration, theme extraction, conflict resolution |
-| EVAL-001 | evaluator | evaluate | SYNTH-001 | Scoring, ranking, priority recommendation, final selection |
-
-## Checkpoints
-
-| Trigger | Location | Behavior |
-|---------|----------|----------|
-| Generator-Critic loop | After CHALLENGE-* | If severity >= HIGH → create IDEA-fix task; else proceed to SYNTH |
-| GC loop limit | Max 2 rounds | Exceeds limit → force convergence to SYNTH |
-| Pipeline stall | No ready + no running | Check missing tasks, report to user |
-
-## Completion Conditions
-
-| Mode | Completion Condition |
-|------|---------------------|
-| quick | All 3 tasks completed |
-| deep | All 6 tasks (+ any skipped GC tasks) completed |
-| full | All 7 tasks (+ any skipped GC tasks) completed |
-
-## Shared State (meta.json)
-
-| Role | State Key |
-|------|-----------|
-| ideator | `generated_ideas` |
-| challenger | `critique_insights` |
-| synthesizer | `synthesis_themes` |
-| evaluator | `evaluation_scores` |
-
-## Message Types
-
-| Role | Types |
-|------|-------|
-| coordinator | `pipeline_selected`, `gc_loop_trigger`, `task_unblocked`, `error`, `shutdown` |
-| ideator | `ideas_ready`, `ideas_revised`, `error` |
-| challenger | `critique_ready`, `error` |
-| synthesizer | `synthesis_ready`, `error` |
-| evaluator | `evaluation_ready`, `error` |
+# Pipeline Definitions — team-brainstorm
+
+## Available Pipelines
+
+### Quick Pipeline (3 beats, strictly serial)
+
+```
+IDEA-001 → CHALLENGE-001 → SYNTH-001
+[ideator]   [challenger]   [synthesizer]
+```
+
+### Deep Pipeline (6 beats, Generator-Critic loop)
+
+```
+IDEA-001 → CHALLENGE-001 → IDEA-002(fix) → CHALLENGE-002 → SYNTH-001 → EVAL-001
+```
+
+GC loop check: if critique.severity >= HIGH → create IDEA-fix → CHALLENGE-2 → SYNTH; else skip to SYNTH
+
+### Full Pipeline (7 tasks, fan-out parallel ideation + GC)
+
+```
+[IDEA-001 + IDEA-002 + IDEA-003](parallel) → CHALLENGE-001(batch) → IDEA-004(fix) → SYNTH-001 → EVAL-001
+```
+
+## Task Metadata Registry
+
+| Task ID | Role | Phase | Dependencies | Description |
+|---------|------|-------|-------------|-------------|
+| IDEA-001 | ideator | generate | (none) | Multi-angle idea generation |
+| IDEA-002 | ideator | generate | (none) | Parallel angle (Full pipeline only) |
+| IDEA-003 | ideator | generate | (none) | Parallel angle (Full pipeline only) |
+| CHALLENGE-001 | challenger | challenge | IDEA-001 (or all IDEA-*) | Devil's advocate critique and feasibility challenge |
+| IDEA-004 | ideator | gc-fix | CHALLENGE-001 | Revision based on critique (GC loop, if triggered) |
+| CHALLENGE-002 | challenger | gc-fix | IDEA-004 | Re-critique of revised ideas (GC loop round 2) |
+| SYNTH-001 | synthesizer | synthesize | last CHALLENGE-* | Cross-idea integration, theme extraction, conflict resolution |
+| EVAL-001 | evaluator | evaluate | SYNTH-001 | Scoring, ranking, priority recommendation, final selection |
+
+## Checkpoints
+
+| Trigger | Location | Behavior |
+|---------|----------|----------|
+| Generator-Critic loop | After CHALLENGE-* | If severity >= HIGH → create IDEA-fix task; else proceed to SYNTH |
+| GC loop limit | Max 2 rounds | Exceeds limit → force convergence to SYNTH |
+| Pipeline stall | No ready + no running | Check missing tasks, report to user |
+
+## Completion Conditions
+
+| Mode | Completion Condition |
+|------|---------------------|
+| quick | All 3 tasks completed |
+| deep | All 6 tasks (+ any skipped GC tasks) completed |
+| full | All 7 tasks (+ any skipped GC tasks) completed |
+
+## Shared State (meta.json)
+
+| Role | State Key |
+|------|-----------|
+| ideator | `generated_ideas` |
+| challenger | `critique_insights` |
+| synthesizer | `synthesis_themes` |
+| evaluator | `evaluation_scores` |
+
+## Message Types
+
+| Role | Types |
+|------|-------|
+| coordinator | `pipeline_selected`, `gc_loop_trigger`, `task_unblocked`, `error`, `shutdown` |
+| ideator | `ideas_ready`, `ideas_revised`, `error` |
+| challenger | `critique_ready`, `error` |
+| synthesizer | `synthesis_ready`, `error` |
+| evaluator | `evaluation_ready`, `error` |

package/.codex/skills/team-coordinate/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: team-coordinate
 description: Universal team coordination skill with dynamic role generation. Uses team-worker agent architecture with role-spec files. Only coordinator is built-in -- all worker roles are generated at runtime as role-specs and spawned via team-worker agent. Beat/cadence model for orchestration. Triggers on "Team Coordinate ".
-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 Coordinate
@@ -40,7 +40,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 |
@@ -136,6 +137,8 @@ When coordinator spawns workers, use `team-worker` agent with role-spec path:
 ```
 spawn_agent({
   agent_type: "team_worker",
+  task_name: "<task-id>",
+  fork_context: false,
   items: [
     { type: "text", text: `## Role Assignment
 role: <role>
@@ -159,7 +162,7 @@ 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: <name> })` each worker.
 
 **Inner Loop roles** (role has 2+ serial same-prefix tasks): Set `inner_loop: true`. The team-worker agent handles the loop internally.
 
@@ -167,6 +170,71 @@ After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect
 
 ---
 
+
+### Model Selection Guide
+
+Roles are **dynamically generated** at runtime. Select model/reasoning_effort based on the generated role's `responsibility_type`:
+
+| responsibility_type | model | reasoning_effort | Rationale |
+|---------------------|-------|-------------------|-----------|
+| exploration | (default) | medium | Read-heavy, less reasoning needed |
+| analysis | (default) | high | Deep analysis requires full reasoning |
+| implementation | (default) | high | Code generation needs precision |
+| synthesis | (default) | medium | Aggregation over generation |
+| review | (default) | high | Quality assessment needs deep reasoning |
+
+Map each generated role's `responsibility_type` (from `team-session.json#roles`) to the table above.
+
+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: [...]
+})
+```
+
+## v4 Agent Coordination
+
+### Message Semantics
+
+| Intent | API | Example |
+|--------|-----|---------|
+| Queue supplementary info (don't interrupt) | `send_message` | Send upstream task findings to a running downstream worker |
+| Not used in this skill | `assign_task` | No resident agents -- all workers are one-shot |
+| Check running agents | `list_agents` | Verify agent health during resume |
+
+**Note**: Since roles are dynamically generated, the coordinator must resolve task prefixes and role names from `team-session.json#roles` at runtime. There are no hardcoded role-specific examples.
+
+### fork_context Strategy
+
+`fork_context: false` is the default. Consider `fork_context: true` only when:
+- Runtime analysis reveals the task requires deep familiarity with the full conversation context
+- The dynamically-generated role-spec indicates the worker needs project-wide understanding
+- The coordinator has already accumulated significant context about the codebase
+
+This decision should be made per-task during Phase 4 based on the role's `responsibility_type`.
+
+### Agent Health Check
+
+Use `list_agents({})` in handleResume and handleComplete:
+
+```
+// Reconcile session state with actual running agents
+const running = list_agents({})
+// Compare with team-session.json active_workers
+// Reset orphaned tasks (in_progress but agent gone) to pending
+```
+
+### Named Agent Targeting
+
+Workers are spawned with `task_name: "<task-id>"` enabling direct addressing:
+- `send_message({ target: "<TASK-ID>", items: [...] })` -- queue upstream context without interrupting
+- `close_agent({ target: "<TASK-ID>" })` -- cleanup by name
+
 ## Completion Action
 
 When pipeline completes (all tasks done), coordinator presents an interactive choice:

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

@@ -68,7 +68,7 @@ Receive result from wait_agent for [<role>]
   |   +- YES -> Update session state, do NOT remove from active_workers -> STOP
   +- Task status = completed?
   |   +- YES -> remove from active_workers -> update session
-  |   |   +- Close agent: close_agent({ id: <agentId> })
+  |   |   +- Close agent: close_agent({ target: <agentId> })
   |   |   +- -> handleSpawnNext
   |   +- NO -> progress message, do not advance -> STOP
   +- No matching worker found
@@ -114,6 +114,16 @@ Then STOP.
 
 ### Handler: 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
+```
+
 Check active worker completion, process results, advance pipeline.
 
 ```
@@ -155,11 +165,27 @@ Ready tasks found?
       Update session file -> output summary -> STOP
 ```
 
+**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 upstream task results to running downstream workers
+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.
+
 **Spawn worker call** (one per ready task):
 
 ```
 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>
 role_spec: <session-folder>/role-specs/<role>.md
@@ -171,16 +197,30 @@ inner_loop: <true|false>
 
 Read role_spec file to load Phase 2-4 domain instructions.` }]
 })
-// Collect results:
-const result = wait_agent({ ids: [agentId], timeout_ms: 900000 })
-// Process result, update tasks.json
-close_agent({ id: agentId })
+// Collect results — use task_name for stable targeting (v4):
+const result = wait_agent({ targets: [taskId], timeout_ms: 900000 })
+if (result.timed_out) {
+  state.tasks[taskId].status = 'timed_out'
+  close_agent({ target: taskId })
+  // Report timeout, STOP — let user decide retry
+} else {
+  // Process result, update tasks.json
+  close_agent({ target: taskId })  // Use task_name, not agentId
+}
 ```
 
 ---
 
 ### Handler: 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
+```
+
 Pipeline complete. Execute completion action based on session configuration.
 
 ```