From 88ea7fc6d7ab9c04509ad7ce6f3a252861860918 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Fri, 27 Mar 2026 22:25:32 +0800 Subject: [PATCH] refactor: deep Codex v4 API conversion for all 20 team skills MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Upgrade all team-* skills from mechanical v3→v4 API renames to deep v4 tool integration with skill-adaptive patterns: - list_agents: health checks in handleResume, cleanup verification in handleComplete, added to allowed-tools and coordinator toolbox - Named targeting: task_name uses task-id (e.g. EXPLORE-001) instead of generic -worker, enabling send_message/assign_task by name - Message semantics: send_message for supplementary cross-agent context vs assign_task for triggering work, with skill-specific examples - Model selection: per-role reasoning_effort guidance matching each skill's actual roles (not generic boilerplate) - timeout_ms: added to all wait_agent calls, timed_out handling in all 18 monitor.md files - Skill-adaptive v4 sections: ultra-analyze N-parallel coordination, lifecycle-v4 supervisor assign_task/send_message distinction, brainstorm ideator parallel patterns, iterdev generator-critic loops, frontend-debug iterative debug assign_task, perf-opt benchmark context sharing, executor lightweight trimmed v4, etc. 60 files changed across 20 team skills (SKILL.md, monitor.md, role.md) Co-Authored-By: Claude Opus 4.6 --- .codex/skills/team-arch-opt/SKILL.md | 73 ++++++++++++++- .../roles/coordinator/commands/monitor.md | 60 +++++++++++-- .../team-arch-opt/roles/coordinator/role.md | 14 ++- .codex/skills/team-brainstorm/SKILL.md | 76 +++++++++++++++- .../roles/coordinator/commands/monitor.md | 53 +++++++++-- .../team-brainstorm/roles/coordinator/role.md | 14 ++- .codex/skills/team-coordinate/SKILL.md | 74 ++++++++++++++- .../roles/coordinator/commands/monitor.md | 50 +++++++++-- .../team-coordinate/roles/coordinator/role.md | 15 +++- .codex/skills/team-designer/SKILL.md | 2 +- .codex/skills/team-executor/SKILL.md | 31 ++++++- .../roles/executor/commands/monitor.md | 38 ++++---- .codex/skills/team-frontend-debug/SKILL.md | 69 +++++++++++++- .../roles/coordinator/commands/monitor.md | 36 +++++++- .../roles/coordinator/role.md | 14 ++- .codex/skills/team-frontend/SKILL.md | 80 ++++++++++++++++- .../roles/coordinator/commands/monitor.md | 36 +++++++- .../team-frontend/roles/coordinator/role.md | 14 ++- .codex/skills/team-issue/SKILL.md | 87 +++++++++++++++++- .../roles/coordinator/commands/monitor.md | 53 +++++++++-- .../team-issue/roles/coordinator/role.md | 14 ++- .codex/skills/team-iterdev/SKILL.md | 67 +++++++++++++- .../roles/coordinator/commands/monitor.md | 53 +++++++++-- .../team-iterdev/roles/coordinator/role.md | 14 ++- .../team-lifecycle-v4/MIGRATION-PLAN.md | 12 +-- .codex/skills/team-lifecycle-v4/SKILL.md | 87 +++++++++++++++--- .../roles/coordinator/commands/dispatch.md | 2 +- .../roles/coordinator/commands/monitor.md | 90 ++++++++++++++----- .../roles/coordinator/role.md | 14 ++- .../roles/supervisor/role.md | 2 +- .codex/skills/team-perf-opt/SKILL.md | 71 ++++++++++++++- .../roles/coordinator/commands/monitor.md | 36 +++++++- .../team-perf-opt/roles/coordinator/role.md | 14 ++- .codex/skills/team-planex/SKILL.md | 68 +++++++++++++- .../roles/coordinator/commands/monitor.md | 56 ++++++++++-- .../team-planex/roles/coordinator/role.md | 14 ++- .codex/skills/team-quality-assurance/SKILL.md | 63 ++++++++++++- .../roles/coordinator/commands/monitor.md | 36 +++++++- .../roles/coordinator/role.md | 14 ++- .codex/skills/team-review/SKILL.md | 61 ++++++++++++- .../roles/coordinator/commands/monitor.md | 52 +++++++++-- .../team-review/roles/coordinator/role.md | 14 ++- .codex/skills/team-roadmap-dev/SKILL.md | 58 +++++++++++- .../roles/coordinator/commands/monitor.md | 36 +++++++- .../roles/coordinator/role.md | 17 +++- .codex/skills/team-tech-debt/SKILL.md | 59 +++++++++++- .../roles/coordinator/commands/monitor.md | 59 ++++++++++-- .../team-tech-debt/roles/coordinator/role.md | 14 ++- .codex/skills/team-testing/SKILL.md | 75 +++++++++++++++- .../roles/coordinator/commands/monitor.md | 59 ++++++++++-- .../team-testing/roles/coordinator/role.md | 14 ++- .codex/skills/team-uidesign/SKILL.md | 68 +++++++++++++- .../roles/coordinator/commands/monitor.md | 52 +++++++++-- .../team-uidesign/roles/coordinator/role.md | 14 ++- .codex/skills/team-ultra-analyze/SKILL.md | 76 +++++++++++++++- .../roles/coordinator/commands/monitor.md | 59 ++++++++++-- .../roles/coordinator/role.md | 14 ++- .codex/skills/team-ux-improve/SKILL.md | 67 +++++++++++++- .../roles/coordinator/commands/monitor.md | 35 ++++++++ .../team-ux-improve/roles/coordinator/role.md | 14 ++- 60 files changed, 2318 insertions(+), 215 deletions(-) diff --git a/.codex/skills/team-arch-opt/SKILL.md b/.codex/skills/team-arch-opt/SKILL.md index 0efdbf04..f232b002 100644 --- a/.codex/skills/team-arch-opt/SKILL.md +++ b/.codex/skills/team-arch-opt/SKILL.md @@ -1,7 +1,7 @@ --- name: team-arch-opt description: Unified team skill for architecture optimization. Uses team-worker agent architecture with role directories for domain logic. Coordinator orchestrates pipeline, workers are team-worker agents. Triggers on "team arch-opt". -allowed-tools: spawn_agent(*), wait_agent(*), send_input(*), close_agent(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__ace-tool__search_context(*) +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(*), mcp__ace-tool__search_context(*) --- # Team Architecture Optimization @@ -54,7 +54,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 | @@ -84,6 +85,8 @@ Coordinator spawns workers using this template: ``` spawn_agent({ agent_type: "team_worker", + task_name: "", + fork_context: false, items: [ { type: "text", text: `## Role Assignment role: @@ -107,11 +110,34 @@ 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. **Inner Loop roles** (refactorer): Set `inner_loop: true`. **Single-task roles** (analyzer, designer, validator, reviewer): Set `inner_loop: false`. +### Model Selection Guide + +Architecture optimization is reasoning-intensive. All analysis and design roles need high reasoning effort. + +| Role | reasoning_effort | Rationale | +|------|-------------------|-----------| +| analyzer | high | Deep structural analysis of codebase architecture | +| designer | high | Architecture redesign requires careful reasoning about tradeoffs | +| refactorer | high | Code transformations must preserve correctness | +| validator | high | Validation must thoroughly check refactoring correctness | +| reviewer | high | Code quality review demands deep understanding | + +Override in spawn_agent when needed: +``` +spawn_agent({ + agent_type: "team_worker", + task_name: "", + fork_context: false, + reasoning_effort: "high", + items: [...] +}) +``` + ## User Commands | Command | Action | @@ -161,6 +187,47 @@ After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect - [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions, task registry, parallel modes +## v4 Agent Coordination + +### Message Semantics + +| Intent | API | Example | +|--------|-----|---------| +| Queue supplementary info (don't interrupt) | `send_message` | Send codebase patterns to running analyzer | +| Assign new work / trigger processing | `assign_task` | Assign fix task to refactorer after review feedback | +| Check running agents | `list_agents` | Verify agent health during resume | + +### Agent Health Check + +Use `list_agents({})` in handleResume and handleComplete: + +``` +// Reconcile session state with actual running agents +const running = list_agents({}) +// Compare with session.json active tasks +// Reset orphaned tasks (in_progress but agent gone) to pending +``` + +### Named Agent Targeting + +Workers are spawned with `task_name: ""` enabling direct addressing: +- `send_message({ target: "ANALYZE-001", items: [...] })` -- queue analysis context without interrupting +- `assign_task({ target: "REFACTOR-001", items: [...] })` -- assign fix task after review feedback +- `close_agent({ target: "VALIDATE-001" })` -- cleanup by name + +### Merged Exploration Pattern + +For architecture analysis, analyzer may need broad codebase exploration. Consider spawning analyzer with `fork_context: true` when deep structural analysis of interconnected modules is needed: +``` +spawn_agent({ + agent_type: "team_worker", + task_name: "ANALYZE-001", + fork_context: true, // Share coordinator's codebase context + reasoning_effort: "high", + items: [...] +}) +``` + ## Error Handling | Scenario | Resolution | diff --git a/.codex/skills/team-arch-opt/roles/coordinator/commands/monitor.md b/.codex/skills/team-arch-opt/roles/coordinator/commands/monitor.md index 94dd46c4..b3444a73 100644 --- a/.codex/skills/team-arch-opt/roles/coordinator/commands/monitor.md +++ b/.codex/skills/team-arch-opt/roles/coordinator/commands/monitor.md @@ -41,6 +41,16 @@ Fan-out mode adds per-branch grouping. Independent mode adds per-pipeline groupi ## 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 +``` + 1. Read tasks.json, check active_agents 2. No active agents -> handleSpawnNext 3. Has active agents -> check each status @@ -74,6 +84,7 @@ state.tasks[taskId].status = 'in_progress' // 2) Spawn worker const agentId = spawn_agent({ agent_type: "team_worker", + task_name: taskId, // e.g., "DESIGN-001" — enables named targeting items: [ { type: "text", text: `## Role Assignment role: ${task.role} @@ -109,20 +120,43 @@ state.active_agents[taskId] = { agentId, role: task.role, started_at: now } | Fan-out (REFACTOR-B{NN} done) | VALIDATE + REVIEW ready | Spawn both for that branch in parallel | | Independent | Any unblocked task | Spawn all ready tasks across all pipelines in parallel | +**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 design analysis results to running refactorers +send_message({ + target: "", + 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. + ### Wait and Process Results 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, timeout_ms: 900000 }) - -// 5) Collect results -for (const [taskId, agent] of Object.entries(state.active_agents)) { - state.tasks[taskId].status = 'completed' - close_agent({ id: agent.agentId }) - 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) { + // Mark timed-out agents, close them, report to user + for (const taskId of taskNames) { + state.tasks[taskId].status = 'timed_out' + close_agent({ target: taskId }) + delete state.active_agents[taskId] + } +} else { + // 5) Collect results + 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] + } } ``` @@ -159,6 +193,14 @@ Fix cycle tracking per branch in tasks.json `fix_cycles`: ## 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 done. Generate report and completion action. Completion check by mode: diff --git a/.codex/skills/team-arch-opt/roles/coordinator/role.md b/.codex/skills/team-arch-opt/roles/coordinator/role.md index b06ceb4e..e474dda5 100644 --- a/.codex/skills/team-arch-opt/roles/coordinator/role.md +++ b/.codex/skills/team-arch-opt/roles/coordinator/role.md @@ -6,7 +6,7 @@ Orchestrate team-arch-opt: analyze -> dispatch -> spawn -> monitor -> report. **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 +- `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): @@ -34,6 +34,8 @@ WRONG: Bash running build/test/lint commands — worker work - Handle review-fix cycles with max 3 iterations - 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 (analyzing, refactoring, reviewing) -- workers handle this @@ -173,6 +175,16 @@ Delegate to @commands/monitor.md#handleSpawnNext: - auto_archive -> Archive & Clean (rm -rf session folder) - auto_keep -> Keep Active (status=paused) +## 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: ""` can be addressed by name in send_message, assign_task, and close_agent calls. + ## Error Handling | Error | Resolution | diff --git a/.codex/skills/team-brainstorm/SKILL.md b/.codex/skills/team-brainstorm/SKILL.md index 37552b59..b1c37186 100644 --- a/.codex/skills/team-brainstorm/SKILL.md +++ b/.codex/skills/team-brainstorm/SKILL.md @@ -1,7 +1,7 @@ --- name: team-brainstorm description: Unified team skill for brainstorming team. Uses team-worker agent architecture with role directories for domain logic. Coordinator orchestrates pipeline, workers are team-worker agents. Triggers on "team brainstorm". -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 Brainstorm @@ -53,7 +53,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 | @@ -83,6 +84,8 @@ Coordinator spawns workers using this template: ``` spawn_agent({ agent_type: "team_worker", + task_name: "", + fork_context: false, items: [ { type: "text", text: `## Role Assignment role: @@ -106,7 +109,7 @@ 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. **Parallel ideator spawn** (Full pipeline with N angles): @@ -115,6 +118,8 @@ When Full pipeline has N parallel IDEA tasks, spawn N distinct team-worker agent ``` spawn_agent({ agent_type: "team_worker", + task_name: "ideator-", + fork_context: false, items: [ { type: "text", text: `## Role Assignment role: ideator @@ -139,7 +144,29 @@ 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 | +|------|-------|-------------------|-----------| +| Ideator (IDEA-*) | (default) | high | Creative divergent thinking requires full reasoning | +| Challenger (CHALLENGE-*) | (default) | high | Critical analysis of ideas needs deep reasoning | +| Synthesizer (SYNTH-*) | (default) | medium | Aggregation and convergence over generation | +| Evaluator (EVAL-*) | (default) | medium | Scoring and ranking against criteria | + +Override model/reasoning_effort in spawn_agent when cost optimization is needed: +``` +spawn_agent({ + agent_type: "team_worker", + task_name: "", + fork_context: false, + model: "", + reasoning_effort: "", + items: [...] +}) +``` ## User Commands @@ -178,6 +205,47 @@ After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect - [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions and task registry +## v4 Agent Coordination + +### Message Semantics + +| Intent | API | Example | +|--------|-----|---------| +| Share idea context across ideators | `send_message` | Send seed ideas to running ideator for cross-pollination | +| Not used in this skill | `assign_task` | No resident agents -- all workers are one-shot | +| Check running agents | `list_agents` | Verify parallel ideator health during Full pipeline | + +### Parallel Ideator Coordination (Full Pipeline) + +Full pipeline spawns N parallel ideators for different brainstorming angles. Use batch spawn + wait: + +``` +// Spawn N ideators in parallel, each with a different angle +const ideatorNames = ["IDEA-001", "IDEA-002", "IDEA-003"] +for (const name of ideatorNames) { + spawn_agent({ agent_type: "team_worker", task_name: name, fork_context: false, ... }) +} +wait_agent({ targets: ideatorNames, timeout_ms: 900000 }) +// Collect all idea outputs, feed to challenger as upstream context +``` + +### 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 +``` + +### Named Agent Targeting + +Workers are spawned with `task_name: ""` enabling direct addressing: +- `send_message({ target: "IDEA-002", items: [...] })` -- share context from another ideator +- `close_agent({ target: "IDEA-001" })` -- cleanup by name after wait_agent returns + ## Error Handling | Scenario | Resolution | diff --git a/.codex/skills/team-brainstorm/roles/coordinator/commands/monitor.md b/.codex/skills/team-brainstorm/roles/coordinator/commands/monitor.md index 7d03b4b1..671d01f4 100644 --- a/.codex/skills/team-brainstorm/roles/coordinator/commands/monitor.md +++ b/.codex/skills/team-brainstorm/roles/coordinator/commands/monitor.md @@ -51,7 +51,7 @@ Worker completed. Process and advance. - Log team_msg with type "gc_loop_trigger" or "task_unblocked" - If skipping GC tasks, mark them as completed (skip) -5. Close completed agent: `close_agent({ id: })` +5. Close completed agent: `close_agent({ target: })` 6. Proceed to handleSpawnNext ## handleCheck @@ -69,6 +69,16 @@ Read-only status report, then STOP. ## 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 +``` + 1. Audit task list: Tasks stuck in "in_progress" -> reset to "pending" 2. Proceed to handleSpawnNext @@ -86,6 +96,7 @@ Find ready tasks, spawn workers, STOP. ``` const agentId = spawn_agent({ agent_type: "team_worker", + task_name: taskId, // e.g., "IDEA-001" — enables named targeting items: [{ type: "text", text: `## Role Assignment role: role_spec: ~ or /.codex/skills/team-brainstorm/roles//role.md @@ -99,10 +110,10 @@ Find ready tasks, spawn workers, STOP. Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).` }] }) ``` - d. Collect agent results: `wait_agent({ ids: [agentId], timeout_ms: 900000 })` + d. Collect agent results: `wait_agent({ targets: [taskId], timeout_ms: 900000 })` e. Read discoveries from output files f. Update tasks.json with results - g. Close agent: `close_agent({ id: agentId })` + g. Close agent: `close_agent({ target: taskId })` // Use task_name, not agentId 5. Parallel spawn rules: | Pipeline | Scenario | Spawn Behavior | @@ -118,18 +129,48 @@ const agentIds = [] for (const task of readyIdeatorTasks) { agentIds.push(spawn_agent({ agent_type: "team_worker", + task_name: task.id, // e.g., "IDEA-001" — enables named targeting items: [{ type: "text", text: `...role: ideator-...` }] })) } -const results = wait_agent({ ids: agentIds, timeout_ms: 900000 }) -// Process results, close agents -for (const id of agentIds) { close_agent({ id }) } +// Use task_name for stable targeting (v4) +const taskNames = readyIdeatorTasks.map(t => t.id) +const results = wait_agent({ targets: taskNames, timeout_ms: 900000 }) +if (results.timed_out) { + for (const taskId of taskNames) { state.tasks[taskId].status = 'timed_out'; close_agent({ target: taskId }) } +} else { + // Process results, close agents + for (const taskId of taskNames) { close_agent({ target: taskId }) } +} ``` +**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 ideation results to running challenger +send_message({ + target: "", + 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. + 6. Update session, output summary, STOP ## 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 done. Generate report and completion action. Completion check by mode: diff --git a/.codex/skills/team-brainstorm/roles/coordinator/role.md b/.codex/skills/team-brainstorm/roles/coordinator/role.md index e41b4d4d..b72b4f41 100644 --- a/.codex/skills/team-brainstorm/roles/coordinator/role.md +++ b/.codex/skills/team-brainstorm/roles/coordinator/role.md @@ -6,7 +6,7 @@ Orchestrate team-brainstorm: topic clarify -> dispatch -> spawn -> monitor -> re **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 +- `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): @@ -34,6 +34,8 @@ WRONG: Edit/Write on project source files — worker work - Manage Generator-Critic loop count (max 2 rounds) - 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 - Generate ideas, challenge assumptions, synthesize, or evaluate -- workers handle this @@ -149,6 +151,16 @@ Delegate to @commands/monitor.md#handleSpawnNext: - auto_archive -> Archive & Clean (status=completed, clean up session) - auto_keep -> Keep Active (status=paused) +## 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: ""` can be addressed by name in send_message, assign_task, and close_agent calls. + ## Error Handling | Error | Resolution | diff --git a/.codex/skills/team-coordinate/SKILL.md b/.codex/skills/team-coordinate/SKILL.md index 44021193..19bc546e 100644 --- a/.codex/skills/team-coordinate/SKILL.md +++ b/.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: "", + fork_context: false, items: [ { type: "text", text: `## Role Assignment role: @@ -159,7 +162,7 @@ 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. **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: "", + fork_context: false, + model: "", + reasoning_effort: "", + 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: ""` enabling direct addressing: +- `send_message({ target: "", items: [...] })` -- queue upstream context without interrupting +- `close_agent({ target: "" })` -- cleanup by name + ## Completion Action When pipeline completes (all tasks done), coordinator presents an interactive choice: diff --git a/.codex/skills/team-coordinate/roles/coordinator/commands/monitor.md b/.codex/skills/team-coordinate/roles/coordinator/commands/monitor.md index 498e61f5..87fef0ec 100644 --- a/.codex/skills/team-coordinate/roles/coordinator/commands/monitor.md +++ b/.codex/skills/team-coordinate/roles/coordinator/commands/monitor.md @@ -68,7 +68,7 @@ Receive result from wait_agent for [] | +- 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: }) + | | +- Close agent: close_agent({ target: }) | | +- -> 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: "", + 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_spec: /role-specs/.md @@ -171,16 +197,30 @@ inner_loop: 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. ``` diff --git a/.codex/skills/team-coordinate/roles/coordinator/role.md b/.codex/skills/team-coordinate/roles/coordinator/role.md index f2bef9a5..77b37469 100644 --- a/.codex/skills/team-coordinate/roles/coordinator/role.md +++ b/.codex/skills/team-coordinate/roles/coordinator/role.md @@ -31,7 +31,7 @@ OK: Write(".workflow/.team/TC-xxx/tasks.json", ...) — task management OK: Read("roles/coordinator/commands/analyze-task.md") — own instructions OK: Read("specs/role-spec-template.md") — generating role-specs OK: spawn_agent({ agent_type: "team_worker", ... }) — delegation -OK: wait_agent({ ids: [...] }) — monitoring +OK: wait_agent({ targets: [...], timeout_ms: 900000 }) — monitoring ``` **Self-check gate**: After Phase 1 analysis, before ANY other action, ask yourself: @@ -57,6 +57,8 @@ OK: wait_agent({ ids: [...] }) — monitoring - Handle consensus_blocked HIGH verdicts (create revision tasks or pause) - Detect fast-advance orphans on resume/check and reset to pending - Execute completion action when pipeline finishes +- 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 - **Read source code or perform codebase exploration** (delegate to worker roles) @@ -124,6 +126,7 @@ Phase 1 needs task analysis | tasks.json | File | Task lifecycle (create/read/update) | | team_msg | System | Message bus operations | | request_user_input | System | User interaction | +| list_agents | System | Runtime agent discovery and health check | --- @@ -373,6 +376,16 @@ Delegate to `@commands/dispatch.md` which creates the full task chain: --- +## 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: ""` can be addressed by name in send_message, assign_task, and close_agent calls. + ## Error Handling | Error | Resolution | diff --git a/.codex/skills/team-designer/SKILL.md b/.codex/skills/team-designer/SKILL.md index fca1acf8..34b03682 100644 --- a/.codex/skills/team-designer/SKILL.md +++ b/.codex/skills/team-designer/SKILL.md @@ -1,7 +1,7 @@ --- name: team-designer description: Meta-skill for generating team skills following the v4 architecture pattern. Produces complete skill packages with SKILL.md router, coordinator, worker roles, specs, and templates. Triggers on "team-designer", "design team". -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(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*) --- # Team Skill Designer diff --git a/.codex/skills/team-executor/SKILL.md b/.codex/skills/team-executor/SKILL.md index 9a71f3a3..91d48b72 100644 --- a/.codex/skills/team-executor/SKILL.md +++ b/.codex/skills/team-executor/SKILL.md @@ -1,7 +1,7 @@ --- name: team-executor description: Lightweight session execution skill. Resumes existing team-coordinate sessions for pure execution via team-worker agents. No analysis, no role generation -- only loads and executes. Session path required. Triggers on "Team Executor". -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 Executor @@ -109,6 +109,8 @@ When executor spawns workers, use `team-worker` agent with role-spec path: ``` spawn_agent({ agent_type: "team_worker", + task_name: "", + fork_context: false, items: [ { type: "text", text: `## Role Assignment role: @@ -132,10 +134,35 @@ 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 + +team-executor loads roles dynamically from session role-specs. Use reasoning_effort based on the role type defined in the session: +- Implementation/fix roles: `reasoning_effort: "high"` +- Verification/test roles: `reasoning_effort: "medium"` +- Default when role type is unclear: `reasoning_effort: "high"` + +## v4 Agent Coordination + +### State Reconciliation + +On resume, executor reconciles session state with actual running agents: +``` +const running = list_agents({}) +// Compare with session's task-analysis.json active tasks +// Reset orphaned tasks (in_progress but agent gone) to pending +``` + +### Worker Communication + +- `send_message({ target: "", items: [...] })` -- queue supplementary context +- `assign_task({ target: "", items: [...] })` -- assign new work to inner_loop worker +- `close_agent({ target: "" })` -- cleanup completed worker + ## Completion Action When pipeline completes (all tasks done), executor presents an interactive choice: diff --git a/.codex/skills/team-executor/roles/executor/commands/monitor.md b/.codex/skills/team-executor/roles/executor/commands/monitor.md index ff7db4fa..9f83a63c 100644 --- a/.codex/skills/team-executor/roles/executor/commands/monitor.md +++ b/.codex/skills/team-executor/roles/executor/commands/monitor.md @@ -167,22 +167,30 @@ After spawning all ready tasks: const agentIds = Object.values(state.active_agents) .filter(a => !a.resident) .map(a => a.agentId) -wait_agent({ ids: agentIds, timeout_ms: 900000 }) - -// Collect results from discoveries/{task_id}.json -for (const [taskId, agent] of Object.entries(state.active_agents)) { - if (agent.resident) continue - try { - const disc = JSON.parse(Read(`${sessionFolder}/discoveries/${taskId}.json`)) - state.tasks[taskId].status = disc.status || 'completed' - state.tasks[taskId].findings = disc.findings || '' - state.tasks[taskId].error = disc.error || null - } catch { - state.tasks[taskId].status = 'failed' - state.tasks[taskId].error = 'No discovery file produced' +const waitResult = wait_agent({ targets: agentIds, timeout_ms: 900000 }) +if (waitResult.timed_out) { + for (const [taskId, agent] of Object.entries(state.active_agents)) { + if (agent.resident) continue + state.tasks[taskId].status = 'timed_out' + close_agent({ target: agent.agentId }) + delete state.active_agents[taskId] + } +} else { + // Collect results from discoveries/{task_id}.json + for (const [taskId, agent] of Object.entries(state.active_agents)) { + if (agent.resident) continue + try { + const disc = JSON.parse(Read(`${sessionFolder}/discoveries/${taskId}.json`)) + state.tasks[taskId].status = disc.status || 'completed' + state.tasks[taskId].findings = disc.findings || '' + state.tasks[taskId].error = disc.error || null + } catch { + state.tasks[taskId].status = 'failed' + state.tasks[taskId].error = 'No discovery file produced' + } + close_agent({ target: agent.agentId }) + delete state.active_agents[taskId] } - close_agent({ id: agent.agentId }) - delete state.active_agents[taskId] } ``` diff --git a/.codex/skills/team-frontend-debug/SKILL.md b/.codex/skills/team-frontend-debug/SKILL.md index 7517b678..f475a79b 100644 --- a/.codex/skills/team-frontend-debug/SKILL.md +++ b/.codex/skills/team-frontend-debug/SKILL.md @@ -1,7 +1,7 @@ --- name: team-frontend-debug description: Frontend debugging team using Chrome DevTools MCP. Dual-mode — feature-list testing or bug-report debugging. Triggers on "team-frontend-debug", "frontend debug". -allowed-tools: spawn_agent(*), wait_agent(*), send_input(*), close_agent(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__chrome-devtools__*(*) +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(*), mcp__chrome-devtools__*(*) --- # Frontend Debug Team @@ -64,7 +64,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 | @@ -131,6 +132,8 @@ Coordinator spawns workers using this template: ``` spawn_agent({ agent_type: "team_worker", + task_name: "", + fork_context: false, items: [ { type: "text", text: `## Role Assignment role: @@ -154,7 +157,20 @@ 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 + +Debug workflows require tool-heavy interaction (Chrome DevTools MCP). Reasoning effort varies by role. + +| Role | reasoning_effort | Rationale | +|------|-------------------|-----------| +| tester | medium | Systematic feature testing via DevTools, follows test plan | +| reproducer | medium | Reproduce bugs via DevTools interaction steps | +| analyzer | high | Root cause analysis requires deep reasoning about evidence | +| fixer | high | Code fixes must address root cause precisely | +| verifier | medium | Verification follows defined success criteria via DevTools | ## User Commands @@ -166,6 +182,53 @@ After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect | `feedback ` | Inject feedback for revision | | `retry ` | Re-run a failed task | +## v4 Agent Coordination + +### Message Semantics + +| Intent | API | Example | +|--------|-----|---------| +| Queue supplementary info (don't interrupt) | `send_message` | Send DevTools evidence to running analyzer | +| Assign new work / trigger debug round | `assign_task` | Assign re-fix after verification failure | +| Check running agents | `list_agents` | Verify agent health during resume | + +### 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 tasks +// Reset orphaned tasks (in_progress but agent gone) to pending +``` + +### Named Agent Targeting + +Workers are spawned with `task_name: ""` enabling direct addressing: +- `send_message({ target: "ANALYZE-001", items: [...] })` -- send evidence from reproducer to analyzer +- `assign_task({ target: "FIX-001", items: [...] })` -- assign fix based on analysis results +- `close_agent({ target: "VERIFY-001" })` -- cleanup after verification + +### Iterative Debug Loop Pattern + +When verifier reports a fix did not resolve the issue, coordinator uses `assign_task` to trigger re-analysis and re-fix: +``` +// Verifier reports failure -> coordinator dispatches re-fix +assign_task({ + target: "FIX-001", // reuse existing fixer if inner_loop, or spawn new + items: [ + { type: "text", text: `## Re-fix Assignment +verification_result: FAIL +failure_evidence: +previous_fix_summary: +instruction: Analyze verification failure and apply corrected fix.` } + ] +}) +``` + +This pattern enables iterative debug rounds: FIX -> VERIFY -> re-FIX -> re-VERIFY (max 3 rounds). + ## Completion Action When pipeline completes, coordinator presents: diff --git a/.codex/skills/team-frontend-debug/roles/coordinator/commands/monitor.md b/.codex/skills/team-frontend-debug/roles/coordinator/commands/monitor.md index 98883521..f2708da9 100644 --- a/.codex/skills/team-frontend-debug/roles/coordinator/commands/monitor.md +++ b/.codex/skills/team-frontend-debug/roles/coordinator/commands/monitor.md @@ -67,6 +67,16 @@ Output: ## 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 +``` + 1. No active workers -> handleSpawnNext 2. Has active -> check each status - completed -> mark done @@ -90,6 +100,7 @@ Find ready tasks, spawn workers, STOP. ``` spawn_agent({ agent_type: "team_worker", + task_name: taskId, // e.g., "TEST-001" — enables named targeting items: [{ description: "Spawn worker for ", team_name: "frontend-debug", @@ -110,10 +121,33 @@ Find ready tasks, spawn workers, STOP. ``` - Add to active_workers 5. Update session, output summary, STOP -6. Use `wait_agent({ ids: [] })` to wait for callbacks. Workers use `report_agent_job_result()` to send results back. +6. Use `wait_agent({ targets: [], timeout_ms: 900000 })` to wait for callbacks. If `result.timed_out`, mark tasks as `timed_out` and close agents. Use `close_agent({ target: taskId })` with task_name for cleanup. Workers use `report_agent_job_result()` to send results back. + +**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 analysis results to running fixer +send_message({ + target: "", + 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. ## 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 done. Generate debug report and completion action. 1. Generate debug summary: diff --git a/.codex/skills/team-frontend-debug/roles/coordinator/role.md b/.codex/skills/team-frontend-debug/roles/coordinator/role.md index 1eb43780..f0c2a5f5 100644 --- a/.codex/skills/team-frontend-debug/roles/coordinator/role.md +++ b/.codex/skills/team-frontend-debug/roles/coordinator/role.md @@ -6,7 +6,7 @@ Orchestrate team-frontend-debug: analyze -> dispatch -> spawn -> monitor -> repo **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 +- `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): @@ -36,6 +36,8 @@ WRONG: mcp__chrome-devtools__* calls — worker work - Handle iteration loops (analyzer requesting more evidence) - Execute completion action when pipeline finishes - **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 - Read source code or explore codebase (delegate to workers) @@ -141,6 +143,16 @@ Delegate to @commands/monitor.md#handleSpawnNext: - interactive -> request_user_input (Archive/Keep/Export) - auto_archive -> Archive & Clean +## 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: ""` can be addressed by name in send_message, assign_task, and close_agent calls. + ## Error Handling | Error | Resolution | diff --git a/.codex/skills/team-frontend/SKILL.md b/.codex/skills/team-frontend/SKILL.md index 2e9cb91e..7ba250b8 100644 --- a/.codex/skills/team-frontend/SKILL.md +++ b/.codex/skills/team-frontend/SKILL.md @@ -1,7 +1,7 @@ --- name: team-frontend description: Unified team skill for frontend development. Pure router — all roles read this file. Beat model is coordinator-only in monitor.md. Built-in ui-ux-pro-max design intelligence. Triggers on "team frontend". -allowed-tools: spawn_agent(*), wait_agent(*), send_input(*), close_agent(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), WebFetch(*), WebSearch(*), mcp__ace-tool__search_context(*) +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(*), WebFetch(*), WebSearch(*), mcp__ace-tool__search_context(*) --- # Team Frontend Development @@ -54,7 +54,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 | @@ -84,6 +85,8 @@ Coordinator spawns workers using this template: ``` spawn_agent({ agent_type: "team_worker", + task_name: "", + fork_context: false, items: [ { type: "text", text: `## Role Assignment role: @@ -107,7 +110,29 @@ 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 | +|------|-------|-------------------|-----------| +| Analyst (ANALYZE-*) | (default) | high | Design intelligence requires deep UI/UX reasoning | +| Architect (ARCH-*) | (default) | high | Component spec and design token generation needs precision | +| Developer (DEV-*) | (default) | high | Frontend code generation needs full reasoning | +| QA (QA-*) | (default) | high | 5-dimension audit requires thorough analysis | + +Override model/reasoning_effort in spawn_agent when cost optimization is needed: +``` +spawn_agent({ + agent_type: "team_worker", + task_name: "", + fork_context: false, + model: "", + reasoning_effort: "", + items: [...] +}) +``` ## User Commands @@ -141,6 +166,55 @@ After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect - [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions and task registry +## v4 Agent Coordination + +### Message Semantics + +| Intent | API | Example | +|--------|-----|---------| +| Send architecture specs to running developer | `send_message` | Queue design tokens and component specs to DEV-* | +| 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 | + +### Pipeline Pattern + +Sequential pipeline with GC loops: analyst -> architect -> developer -> QA. In **system mode**, architect revision (ARCH-002) and developer (DEV-001) may run in parallel after QA-001 arch review. + +### fork_context Consideration + +Developer workers (DEV-*) benefit from `fork_context: true` when the coordinator has accumulated significant design context (analysis results, architecture specs, design tokens). This avoids the developer needing to re-read all upstream artifacts: + +``` +// Consider fork_context: true for developer in feature/system modes +spawn_agent({ + agent_type: "team_worker", + task_name: "DEV-001", + fork_context: true, // Developer gets full coordinator context including design decisions + items: [...] +}) +``` + +### GC Loop (QA Fix Cycle) + +QA may flag FIX_REQUIRED, creating DEV-fix + QA-recheck tasks (max 2 rounds). If QA score remains < 6 after 2 rounds, escalate to user. + +### 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 +``` + +### Named Agent Targeting + +Workers are spawned with `task_name: ""` enabling direct addressing: +- `send_message({ target: "DEV-001", items: [...] })` -- queue architecture specs to running developer +- `close_agent({ target: "ARCH-001" })` -- cleanup by name after completion + ## Error Handling | Scenario | Resolution | diff --git a/.codex/skills/team-frontend/roles/coordinator/commands/monitor.md b/.codex/skills/team-frontend/roles/coordinator/commands/monitor.md index a55a29e6..f26c6cb7 100644 --- a/.codex/skills/team-frontend/roles/coordinator/commands/monitor.md +++ b/.codex/skills/team-frontend/roles/coordinator/commands/monitor.md @@ -109,6 +109,7 @@ Find and spawn the next ready tasks. ``` spawn_agent({ agent_type: "team_worker", + task_name: taskId, // e.g., "DEV-001" — enables named targeting items: [{ description: "Spawn worker for ", team_name: "frontend", @@ -136,7 +137,22 @@ Execute built-in Phase 1 -> role-spec Phase 2-4 -> built-in Phase 5.` | feature | After QA-001 arch review | Spawn DEV-001 | | system | After QA-001 arch review | Spawn ARCH-002 + DEV-001 in parallel | -4. STOP after spawning -- use `wait_agent({ ids: [] })` to wait for next callback +4. STOP after spawning -- use `wait_agent({ targets: [], timeout_ms: 900000 })` to wait for next callback. If `result.timed_out`, mark tasks as `timed_out` and close agents. Use `close_agent({ target: taskId })` with task_name for cleanup. + +**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 analysis results to running developer +send_message({ + target: "", + 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. ### handleCheck @@ -157,6 +173,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: @@ -166,6 +192,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**: diff --git a/.codex/skills/team-frontend/roles/coordinator/role.md b/.codex/skills/team-frontend/roles/coordinator/role.md index 786a4e54..4b15aedc 100644 --- a/.codex/skills/team-frontend/roles/coordinator/role.md +++ b/.codex/skills/team-frontend/roles/coordinator/role.md @@ -6,7 +6,7 @@ Orchestrate team-frontend: analyze -> dispatch -> spawn -> monitor -> report. **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 +- `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): @@ -34,6 +34,8 @@ WRONG: Edit/Write on project source files — worker work - Handle GC loops (developer <-> qa) with max 2 iterations - 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 (analyzing, designing, coding, reviewing) -- workers handle this @@ -165,6 +167,16 @@ Delegate to @commands/monitor.md#handleSpawnNext: - auto_archive -> Archive & Clean (status=completed, remove/archive session folder) - auto_keep -> Keep Active (status=paused) +## 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: ""` can be addressed by name in send_message, assign_task, and close_agent calls. + ## Error Handling | Error | Resolution | diff --git a/.codex/skills/team-issue/SKILL.md b/.codex/skills/team-issue/SKILL.md index 9563c61d..4a8c9bc7 100644 --- a/.codex/skills/team-issue/SKILL.md +++ b/.codex/skills/team-issue/SKILL.md @@ -1,7 +1,7 @@ --- name: team-issue description: Unified team skill for issue resolution. Uses team-worker agent architecture with role directories for domain logic. Coordinator orchestrates pipeline, workers are team-worker agents. Triggers on "team issue". -allowed-tools: spawn_agent(*), wait_agent(*), send_input(*), close_agent(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__ace-tool__search_context(*), mcp__ccw-tools__team_msg(*) +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(*), mcp__ace-tool__search_context(*), mcp__ccw-tools__team_msg(*) --- # Team Issue Resolution @@ -54,7 +54,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 | @@ -85,6 +86,8 @@ Coordinator spawns workers using this template: ``` spawn_agent({ agent_type: "team_worker", + task_name: "", + fork_context: false, items: [ { type: "text", text: `## Role Assignment role: @@ -108,13 +111,15 @@ 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. **Parallel spawn** (Batch mode, N explorer or M implementer instances): ``` spawn_agent({ agent_type: "team_worker", + task_name: "", + fork_context: false, items: [ { type: "text", text: `## Role Assignment role: @@ -139,7 +144,30 @@ 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 | Context gathering, file reading, less reasoning | +| Planner (SOLVE-*) | (default) | high | Solution design requires deep analysis | +| Reviewer (AUDIT-*) | (default) | high | Code review and plan validation need full reasoning | +| Integrator (MARSHAL-*) | (default) | medium | Queue ordering and dependency resolution | +| Implementer (BUILD-*) | (default) | high | Code generation needs precision | + +Override model/reasoning_effort in spawn_agent when cost optimization is needed: +``` +spawn_agent({ + agent_type: "team_worker", + task_name: "", + fork_context: false, + model: "", + reasoning_effort: "", + items: [...] +}) +``` ## User Commands @@ -176,6 +204,57 @@ After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect - [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions and task registry +## v4 Agent Coordination + +### Message Semantics + +| Intent | API | Example | +|--------|-----|---------| +| Send exploration context to running planner | `send_message` | Queue EXPLORE-* findings to SOLVE-* worker | +| Not used in this skill | `assign_task` | No resident agents -- all workers are one-shot | +| Check running agents | `list_agents` | Verify parallel explorer/implementer health | + +### Pipeline Pattern + +Pipeline with context passing: explore -> plan -> review (optional) -> marshal -> implement. In **Batch mode**, N explorers and M implementers run in parallel: + +``` +// Batch mode: spawn N explorers in parallel (max 5) +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 }) + +// After MARSHAL completes: spawn M implementers in parallel (max 3) +const buildNames = ["BUILD-001", "BUILD-002", ..., "BUILD-00M"] +for (const name of buildNames) { + spawn_agent({ agent_type: "team_worker", task_name: name, ... }) +} +wait_agent({ targets: buildNames, timeout_ms: 900000 }) +``` + +### Review-Fix Cycle + +Reviewer (AUDIT-*) may reject plans, triggering fix cycles (max 2). Dynamic SOLVE-fix and AUDIT re-review tasks are created in tasks.json. + +### 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 +``` + +### Named Agent Targeting + +Workers are spawned with `task_name: ""` enabling direct addressing: +- `send_message({ target: "SOLVE-001", items: [...] })` -- queue exploration context to running planner +- `close_agent({ target: "BUILD-001" })` -- cleanup by name after completion + ## Error Handling | Scenario | Resolution | diff --git a/.codex/skills/team-issue/roles/coordinator/commands/monitor.md b/.codex/skills/team-issue/roles/coordinator/commands/monitor.md index 0beddf41..c1549714 100644 --- a/.codex/skills/team-issue/roles/coordinator/commands/monitor.md +++ b/.codex/skills/team-issue/roles/coordinator/commands/monitor.md @@ -61,7 +61,7 @@ Worker completed. Process and advance. - Create BUILD-001..M tasks dynamically (add to tasks.json per dispatch.md Batch Pipeline BUILD section) - Proceed to handleSpawnNext -6. Close completed agent: `close_agent({ id: })` +6. Close completed agent: `close_agent({ target: })` 7. Proceed to handleSpawnNext ## handleCheck @@ -79,6 +79,16 @@ Read-only status report, then STOP. ## 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 +``` + 1. Audit task list: Tasks stuck in "in_progress" -> reset to "pending" 2. Proceed to handleSpawnNext @@ -96,6 +106,7 @@ Find ready tasks, spawn workers, STOP. ``` 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_spec: ~ or /.codex/skills/team-issue/roles//role.md @@ -109,10 +120,10 @@ Find ready tasks, spawn workers, STOP. Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).` }] }) ``` - d. Collect results: `wait_agent({ ids: [agentId], timeout_ms: 900000 })` + d. Collect results: `wait_agent({ targets: [taskId], timeout_ms: 900000 })` e. Read discoveries from output files f. Update tasks.json with results - g. Close agent: `close_agent({ id: agentId })` + g. Close agent: `close_agent({ target: taskId })` // Use task_name, not agentId 5. Parallel spawn rules: @@ -130,6 +141,7 @@ const agentIds = [] for (const task of readyTasks) { agentIds.push(spawn_agent({ agent_type: "team_worker", + task_name: task.id, // e.g., "EXPLORE-001" — enables named targeting items: [{ type: "text", text: `## Role Assignment role: role_spec: ~ or /.codex/skills/team-issue/roles//role.md @@ -144,15 +156,44 @@ Read role_spec file to load Phase 2-4 domain instructions. Execute built-in Phase 1 (task discovery, owner=-) -> role Phase 2-4 -> built-in Phase 5 (report).` }] })) } -const results = wait_agent({ ids: agentIds, timeout_ms: 900000 }) -// Process results, close agents -for (const id of agentIds) { close_agent({ id }) } +// Use task_name for stable targeting (v4) +const taskNames = readyTasks.map(t => t.id) +const results = wait_agent({ targets: taskNames, timeout_ms: 900000 }) +if (results.timed_out) { + for (const taskId of taskNames) { state.tasks[taskId].status = 'timed_out'; close_agent({ target: taskId }) } +} else { + // Process results, close agents + for (const taskId of taskNames) { close_agent({ target: taskId }) } +} ``` +**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 planner +send_message({ + target: "", + 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. + 6. Update session, output summary, STOP ## 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 done. Generate report and completion action. Completion check by mode: diff --git a/.codex/skills/team-issue/roles/coordinator/role.md b/.codex/skills/team-issue/roles/coordinator/role.md index a54b269f..387bd0a0 100644 --- a/.codex/skills/team-issue/roles/coordinator/role.md +++ b/.codex/skills/team-issue/roles/coordinator/role.md @@ -10,7 +10,7 @@ Orchestrate the issue resolution pipeline: clarify requirements -> create team - **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 +- `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): @@ -38,6 +38,8 @@ WRONG: Edit/Write on project source files — worker work - Handle review-fix cycles with max 2 iterations - 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, planning, reviewing, implementing) -- workers handle this @@ -183,6 +185,16 @@ Delegate to @commands/monitor.md#handleSpawnNext: | Keep Active | Update session status="paused" -> output: "Resume with: Skill(skill='team-issue', args='resume')" | | New Batch | Return to Phase 1 | +## 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: ""` can be addressed by name in send_message, assign_task, and close_agent calls. + ## Error Handling | Error | Resolution | diff --git a/.codex/skills/team-iterdev/SKILL.md b/.codex/skills/team-iterdev/SKILL.md index ec93c0f5..99657397 100644 --- a/.codex/skills/team-iterdev/SKILL.md +++ b/.codex/skills/team-iterdev/SKILL.md @@ -1,7 +1,7 @@ --- name: team-iterdev description: Unified team skill for iterative development team. Pure router — all roles read this file. Beat model is coordinator-only in monitor.md. Generator-Critic loops (developer<->reviewer, max 3 rounds). Triggers on "team iterdev". -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 IterDev @@ -54,7 +54,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 | @@ -84,6 +85,8 @@ Coordinator spawns workers using this template: ``` spawn_agent({ agent_type: "team_worker", + task_name: "", + fork_context: false, items: [ { type: "text", text: `## Role Assignment role: @@ -107,7 +110,19 @@ 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 + +Iterative development uses Generator-Critic loops. Developer and reviewer need high reasoning for code generation and review quality. + +| Role | reasoning_effort | Rationale | +|------|-------------------|-----------| +| architect | high | Design decisions require careful tradeoff analysis | +| developer | high | Code generation needs precision, inner loop role | +| tester | medium | Test execution follows defined verification plan | +| reviewer | high | Critical review quality drives GC loop effectiveness | ## User Commands @@ -145,6 +160,52 @@ After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect - [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions and task registry +## v4 Agent Coordination + +### Message Semantics + +| Intent | API | Example | +|--------|-----|---------| +| Queue supplementary info (don't interrupt) | `send_message` | Send design context to running developer | +| Assign GC iteration round | `assign_task` | Assign revision to developer after reviewer feedback | +| Check running agents | `list_agents` | Verify agent health during resume | + +### Agent Health Check + +Use `list_agents({})` in handleResume and handleComplete: + +``` +// Reconcile session state with actual running agents +const running = list_agents({}) +// Compare with task-ledger.json active tasks +// Reset orphaned tasks (in_progress but agent gone) to pending +``` + +### Named Agent Targeting + +Workers are spawned with `task_name: ""` enabling direct addressing: +- `send_message({ target: "DEV-001", items: [...] })` -- send design context to developer +- `assign_task({ target: "DEV-001", items: [...] })` -- assign revision after reviewer feedback +- `close_agent({ target: "REVIEW-001" })` -- cleanup after GC loop completes + +### Generator-Critic Loop via assign_task (Deep Interaction Pattern) + +The developer-reviewer GC loop uses `assign_task` for iteration rounds: +``` +// Round N: Reviewer found issues -> coordinator assigns revision to developer +assign_task({ + target: "DEV-001", + items: [ + { type: "text", text: `## GC Revision Round ${N} +review_feedback: +iteration: ${N}/3 +instruction: Address reviewer feedback. Focus on: .` } + ] +}) +``` + +After developer completes revision, coordinator spawns/assigns reviewer for next round. Max 3 rounds per GC cycle. + ## Error Handling | Scenario | Resolution | diff --git a/.codex/skills/team-iterdev/roles/coordinator/commands/monitor.md b/.codex/skills/team-iterdev/roles/coordinator/commands/monitor.md index 09f77194..f6bd069f 100644 --- a/.codex/skills/team-iterdev/roles/coordinator/commands/monitor.md +++ b/.codex/skills/team-iterdev/roles/coordinator/commands/monitor.md @@ -93,6 +93,7 @@ state.tasks[taskId].status = 'in_progress' // 2) Spawn worker const agentId = spawn_agent({ agent_type: "team_worker", + task_name: taskId, // e.g., "DEV-001" — enables named targeting items: [ { type: "text", text: `## Role Assignment role: ${role} @@ -110,12 +111,19 @@ Execute built-in Phase 1 -> role-spec Phase 2-4 -> built-in Phase 5.` } // 3) Track agent state.active_agents[taskId] = { agentId, role, started_at: now } -// 4) Wait for completion -wait_agent({ ids: [agentId] }) - -// 5) Collect results and update tasks.json -state.tasks[taskId].status = 'completed' -delete state.active_agents[taskId] +// 4) Wait for completion — use task_name for stable targeting (v4) +const waitResult = wait_agent({ targets: [taskId], timeout_ms: 900000 }) +if (waitResult.timed_out) { + state.tasks[taskId].status = 'timed_out' + close_agent({ target: taskId }) + delete state.active_agents[taskId] + // Report timeout, STOP +} else { + // 5) Collect results and update tasks.json + state.tasks[taskId].status = 'completed' + close_agent({ target: taskId }) // Use task_name, not agentId + delete state.active_agents[taskId] +} ``` 4. **Parallel spawn rules**: @@ -128,6 +136,21 @@ delete state.active_agents[taskId] | Multi-Sprint | VERIFY + DEV-fix both unblocked | Spawn BOTH in parallel, wait_agent for both | | Multi-Sprint | Other stages | One worker at a time | +**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 design results to running developer +send_message({ + target: "", + 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 @@ -149,6 +172,16 @@ Session: ### 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: @@ -158,6 +191,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 by mode**: diff --git a/.codex/skills/team-iterdev/roles/coordinator/role.md b/.codex/skills/team-iterdev/roles/coordinator/role.md index 28c654a7..12d67653 100644 --- a/.codex/skills/team-iterdev/roles/coordinator/role.md +++ b/.codex/skills/team-iterdev/roles/coordinator/role.md @@ -6,7 +6,7 @@ Orchestrate team-iterdev: analyze -> dispatch -> spawn -> monitor -> report. **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 +- `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): @@ -35,6 +35,8 @@ WRONG: Edit/Write on project source files — worker work - Maintain tasks.json for real-time progress - 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 (designing, coding, testing, reviewing) -- workers handle this @@ -169,6 +171,16 @@ Delegate to @commands/monitor.md#handleSpawnNext: - auto_archive -> Archive & Clean (status=completed) - auto_keep -> Keep Active (status=paused) +## 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: ""` can be addressed by name in send_message, assign_task, and close_agent calls. + ## Error Handling | Error | Resolution | diff --git a/.codex/skills/team-lifecycle-v4/MIGRATION-PLAN.md b/.codex/skills/team-lifecycle-v4/MIGRATION-PLAN.md index 04bf76c5..6f6d01bb 100644 --- a/.codex/skills/team-lifecycle-v4/MIGRATION-PLAN.md +++ b/.codex/skills/team-lifecycle-v4/MIGRATION-PLAN.md @@ -19,7 +19,7 @@ | Worker spawn | `Agent({ subagent_type: "team-worker", prompt })` | `spawn_agent({ agent_type: "tlv4_worker", items })` | | Supervisor spawn | `Agent({ subagent_type: "team-supervisor", prompt })` | `spawn_agent({ agent_type: "tlv4_supervisor", items })` | | Supervisor wake | `SendMessage({ recipient: "supervisor", content })` | `send_input({ id: supervisorId, items })` | -| Supervisor shutdown | `SendMessage({ type: "shutdown_request" })` | `close_agent({ id: supervisorId })` | +| Supervisor shutdown | `SendMessage({ type: "shutdown_request" })` | `close_agent({ target: supervisorId })` | | 等待完成 | 后台回调 -> monitor.md | `wait_agent({ ids, timeout_ms })` | | 任务状态 | `TaskCreate` / `TaskUpdate` | `tasks.json` 文件读写 | | 团队管理 | `TeamCreate` / `TeamDelete` | session folder init / cleanup | @@ -222,14 +222,14 @@ scope: [${task.deps}] pipeline_progress: ${done}/${total} tasks completed` } ] }) -wait_agent({ ids: [supervisorId], timeout_ms: 300000 }) +wait_agent({ targets: [supervisorId], timeout_ms: 300000 }) ``` ### Supervisor Shutdown ```javascript // 对齐 Claude Code SendMessage({ type: "shutdown_request" }) -close_agent({ id: supervisorId }) +close_agent({ target: supervisorId }) ``` ### Wave 执行引擎 @@ -300,7 +300,7 @@ pipeline_phase: ${task.pipeline_phase}` }, // 2) 批量等待 if (agentMap.length > 0) { - wait_agent({ ids: agentMap.map(a => a.agentId), timeout_ms: 900000 }) + wait_agent({ targets: agentMap.map(a => a.agentId), timeout_ms: 900000 }) } // 3) 收集结果，合并到 tasks.json @@ -315,7 +315,7 @@ pipeline_phase: ${task.pipeline_phase}` }, state.tasks[taskId].status = 'failed' state.tasks[taskId].error = 'No discovery file produced' } - close_agent({ id: agentId }) + close_agent({ target: agentId }) } // 4) 执行 CHECKPOINT 任务 (send_input 唤醒 supervisor) @@ -329,7 +329,7 @@ scope: [${task.deps.join(', ')}] pipeline_progress: ${completedCount}/${totalCount} tasks completed` } ] }) - wait_agent({ ids: [supervisorId], timeout_ms: 300000 }) + wait_agent({ targets: [supervisorId], timeout_ms: 300000 }) // 读取 checkpoint 报告 try { diff --git a/.codex/skills/team-lifecycle-v4/SKILL.md b/.codex/skills/team-lifecycle-v4/SKILL.md index 164b6a31..44c25273 100644 --- a/.codex/skills/team-lifecycle-v4/SKILL.md +++ b/.codex/skills/team-lifecycle-v4/SKILL.md @@ -1,7 +1,7 @@ --- name: team-lifecycle-v4 description: Full lifecycle team skill with clean architecture. SKILL.md is a universal router — all roles read it. Beat model is coordinator-only. Structure is roles/ + specs/ + templates/. Triggers on "team lifecycle v4". -allowed-tools: spawn_agent(*), wait_agent(*), send_input(*), close_agent(*), report_agent_job_result(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), request_user_input(*) +allowed-tools: spawn_agent(*), wait_agent(*), send_message(*), assign_task(*), close_agent(*), list_agents(*), report_agent_job_result(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), request_user_input(*) --- # Team Lifecycle v4 @@ -29,7 +29,7 @@ Skill(skill="team-lifecycle-v4", args="task description") spawn_agent ... spawn_agent (team_worker) (team_supervisor) per-task resident agent - lifecycle send_input-driven + lifecycle assign_task-driven | | +-- wait_agent --------+ | @@ -63,7 +63,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 | @@ -94,6 +95,8 @@ Coordinator spawns workers using this template: ``` spawn_agent({ agent_type: "team_worker", + task_name: "", + fork_context: false, items: [ { type: "text", text: `## Role Assignment role: @@ -120,13 +123,15 @@ pipeline_phase: ` }, ## Supervisor Spawn Template -Supervisor is a **resident agent** (independent from team_worker). Spawned once during session init, woken via send_input for each CHECKPOINT task. +Supervisor is a **resident agent** (independent from team_worker). Spawned once during session init, woken via assign_task for each CHECKPOINT task. ### Spawn (Phase 2 -- once per session) ``` supervisorId = spawn_agent({ agent_type: "team_supervisor", + task_name: "supervisor", + fork_context: false, items: [ { type: "text", text: `## Role Assignment role: supervisor @@ -137,7 +142,7 @@ requirement: Read role_spec file (/roles/supervisor/role.md) to load checkpoint definitions. Init: load baseline context, report ready, go idle. -Wake cycle: orchestrator sends checkpoint requests via send_input.` } +Wake cycle: orchestrator sends checkpoint requests via assign_task.` } ] }) ``` @@ -145,8 +150,8 @@ Wake cycle: orchestrator sends checkpoint requests via send_input.` } ### Wake (per CHECKPOINT task) ``` -send_input({ - id: supervisorId, +assign_task({ + target: "supervisor", items: [ { type: "text", text: `## Checkpoint Request task_id: @@ -154,13 +159,38 @@ scope: [] pipeline_progress: / tasks completed` } ] }) -wait_agent({ ids: [supervisorId], timeout_ms: 300000 }) +wait_agent({ targets: ["supervisor"], timeout_ms: 300000 }) ``` ### Shutdown (pipeline complete) ``` -close_agent({ id: supervisorId }) +close_agent({ target: "supervisor" }) +``` + + +### Model Selection Guide + +| Role | model | reasoning_effort | Rationale | +|------|-------|-------------------|-----------| +| Analyst (RESEARCH-*) | (default) | medium | Read-heavy exploration, less reasoning needed | +| Writer (DRAFT-*) | (default) | high | Spec writing requires precision and completeness | +| Planner (PLAN-*) | (default) | high | Architecture decisions need full reasoning | +| Executor (IMPL-*) | (default) | high | Code generation needs precision | +| Tester (TEST-*) | (default) | high | Test generation requires deep code understanding | +| Reviewer (REVIEW-*, QUALITY-*, IMPROVE-*) | (default) | high | Deep analysis for quality assessment | +| Supervisor (CHECKPOINT-*) | (default) | medium | Gate checking, report aggregation | + +Override model/reasoning_effort in spawn_agent when cost optimization is needed: +``` +spawn_agent({ + agent_type: "team_worker", + task_name: "", + fork_context: false, + model: "", + reasoning_effort: "", + items: [...] +}) ``` ## Wave Execution Engine @@ -172,9 +202,9 @@ For each wave in the pipeline: 3. **Build upstream context** -- For each task, gather findings from `context_from` tasks via tasks.json and `discoveries/{id}.json` 4. **Separate task types** -- Split into regular tasks and CHECKPOINT tasks 5. **Spawn regular tasks** -- For each regular task, call `spawn_agent({ agent_type: "team_worker", items: [...] })`, collect agent IDs -6. **Wait** -- `wait_agent({ ids: [...], timeout_ms: 900000 })` -7. **Collect results** -- Read `discoveries/{task_id}.json` for each agent, update tasks.json status/findings/error, then `close_agent({ id })` each worker -8. **Execute checkpoints** -- For each CHECKPOINT task, `send_input` to supervisor, `wait_agent`, read checkpoint report from `artifacts/`, parse verdict +6. **Wait** -- `wait_agent({ targets: [...], timeout_ms: 900000 })` +7. **Collect results** -- Read `discoveries/{task_id}.json` for each agent, update tasks.json status/findings/error, then `close_agent({ target })` each worker +8. **Execute checkpoints** -- For each CHECKPOINT task, `assign_task` to supervisor, `wait_agent`, read checkpoint report from `artifacts/`, parse verdict 9. **Handle block** -- If verdict is `block`, prompt user via `request_user_input` with options: Override / Revise upstream / Abort 10. **Persist** -- Write updated state to `/tasks.json` @@ -189,6 +219,39 @@ For each wave in the pipeline: | `recheck` | Re-run quality check | | `improve [dimension]` | Auto-improve weakest dimension | +## v4 Agent Coordination + +### Message Semantics + +| Intent | API | Example | +|--------|-----|---------| +| Queue supplementary info (don't interrupt) | `send_message` | Send planning results to running implementers | +| Wake resident supervisor for checkpoint | `assign_task` | Trigger CHECKPOINT-* evaluation on supervisor | +| Supervisor reports back to coordinator | `send_message` | Supervisor sends checkpoint verdict as supplementary info | +| Check running agents | `list_agents` | Verify agent + supervisor health during resume | + +**CRITICAL**: The supervisor is a **resident agent** woken via `assign_task`, NOT `send_message`. Regular workers complete and are closed; the supervisor persists across checkpoints. See "Supervisor Spawn Template" above. + +### 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 +// ALSO check supervisor: if supervisor missing but CHECKPOINT tasks pending -> respawn +``` + +### Named Agent Targeting + +Workers are spawned with `task_name: ""` enabling direct addressing: +- `send_message({ target: "IMPL-001", items: [...] })` -- queue planning context to running implementer +- `assign_task({ target: "supervisor", items: [...] })` -- wake supervisor for checkpoint +- `close_agent({ target: "IMPL-001" })` -- cleanup regular worker by name +- `close_agent({ target: "supervisor" })` -- shutdown supervisor at pipeline end + ## Completion Action When pipeline completes, coordinator presents: diff --git a/.codex/skills/team-lifecycle-v4/roles/coordinator/commands/dispatch.md b/.codex/skills/team-lifecycle-v4/roles/coordinator/commands/dispatch.md index 96b62770..76c97f75 100644 --- a/.codex/skills/team-lifecycle-v4/roles/coordinator/commands/dispatch.md +++ b/.codex/skills/team-lifecycle-v4/roles/coordinator/commands/dispatch.md @@ -48,7 +48,7 @@ CHECKPOINT tasks are dispatched like regular tasks but handled differently at sp - Added to tasks.json with proper deps (upstream tasks that must complete first) - Owner: supervisor -- **NOT spawned as tlv4_worker** — coordinator wakes the resident supervisor via send_input +- **NOT spawned as tlv4_worker** — coordinator wakes the resident supervisor via assign_task - If `supervision: false` in tasks.json, skip creating CHECKPOINT tasks entirely - RoleSpec in description: `/.codex/skills/team-lifecycle-v4/roles/supervisor/role.md` diff --git a/.codex/skills/team-lifecycle-v4/roles/coordinator/commands/monitor.md b/.codex/skills/team-lifecycle-v4/roles/coordinator/commands/monitor.md index e7490b89..4aa4acf6 100644 --- a/.codex/skills/team-lifecycle-v4/roles/coordinator/commands/monitor.md +++ b/.codex/skills/team-lifecycle-v4/roles/coordinator/commands/monitor.md @@ -5,7 +5,7 @@ Synchronous pipeline coordination using spawn_agent + wait_agent. ## Constants - WORKER_AGENT: tlv4_worker -- SUPERVISOR_AGENT: tlv4_supervisor (resident, woken via send_input) +- SUPERVISOR_AGENT: tlv4_supervisor (resident, woken via assign_task) ## Handler Router @@ -35,6 +35,16 @@ Output: ## 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 +``` + 1. Read tasks.json, check active_agents 2. No active agents -> handleSpawnNext 3. Has active agents -> check each: @@ -63,6 +73,7 @@ state.tasks[task.id].status = 'in_progress' // 2) Spawn worker const agentId = spawn_agent({ agent_type: "tlv4_worker", + task_name: task.id, // e.g., "PLAN-001" — enables named targeting items: [ { type: "text", text: `## Role Assignment role: ${task.role} @@ -92,30 +103,52 @@ state.active_agents[task.id] = { agentId, role: task.role, started_at: now } After spawning all ready regular tasks: ```javascript -// 4) Batch wait for all spawned workers -const agentIds = Object.values(state.active_agents) - .filter(a => !a.resident) - .map(a => a.agentId) -wait_agent({ ids: agentIds, timeout_ms: 900000 }) - -// 5) Collect results from discoveries/{task_id}.json -for (const [taskId, agent] of Object.entries(state.active_agents)) { - if (agent.resident) continue - try { - const disc = JSON.parse(Read(`${sessionFolder}/discoveries/${taskId}.json`)) - state.tasks[taskId].status = disc.status || 'completed' - state.tasks[taskId].findings = disc.findings || '' - state.tasks[taskId].quality_score = disc.quality_score || null - state.tasks[taskId].error = disc.error || null - } catch { - state.tasks[taskId].status = 'failed' - state.tasks[taskId].error = 'No discovery file produced' +// 4) Batch wait — use task_name for stable targeting (v4) +const taskNames = Object.entries(state.active_agents) + .filter(([_, a]) => !a.resident) + .map(([taskId]) => taskId) +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 from discoveries/{task_id}.json + for (const [taskId, agent] of Object.entries(state.active_agents)) { + if (agent.resident) continue + try { + const disc = JSON.parse(Read(`${sessionFolder}/discoveries/${taskId}.json`)) + state.tasks[taskId].status = disc.status || 'completed' + state.tasks[taskId].findings = disc.findings || '' + state.tasks[taskId].quality_score = disc.quality_score || null + state.tasks[taskId].error = disc.error || null + } catch { + state.tasks[taskId].status = 'failed' + state.tasks[taskId].error = 'No discovery file produced' + } + close_agent({ target: taskId }) // Use task_name, not agentId + delete state.active_agents[taskId] } - close_agent({ id: agent.agentId }) - delete state.active_agents[taskId] } ``` +**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 planning results to running implementers +send_message({ + target: "", + 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. + ### Handle CHECKPOINT Tasks For each ready CHECKPOINT task: @@ -125,7 +158,7 @@ For each ready CHECKPOINT task: 2. Determine scope: list task IDs that this checkpoint depends on (its deps) 3. Wake supervisor: ```javascript - send_input({ + assign_task({ id: supervisorId, items: [ { type: "text", text: `## Checkpoint Request @@ -134,7 +167,8 @@ For each ready CHECKPOINT task: pipeline_progress: ${completedCount}/${totalCount} tasks completed` } ] }) - wait_agent({ ids: [supervisorId], timeout_ms: 300000 }) + const cpResult = wait_agent({ targets: [supervisorId], timeout_ms: 300000 }) + if (cpResult.timed_out) { /* mark checkpoint timed_out, close supervisor, STOP */ } ``` 4. Read checkpoint report from artifacts/${task.id}-report.md 5. Parse verdict (pass / warn / block): @@ -153,11 +187,19 @@ After processing all results: ## 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 done. Generate report and completion action. 1. Shutdown resident supervisor (if active): ```javascript - close_agent({ id: supervisorId }) + close_agent({ target: supervisorId }) ``` Remove from active_agents in tasks.json 2. Generate summary (deliverables, stats, discussions) diff --git a/.codex/skills/team-lifecycle-v4/roles/coordinator/role.md b/.codex/skills/team-lifecycle-v4/roles/coordinator/role.md index 7e2c0349..a0819ee7 100644 --- a/.codex/skills/team-lifecycle-v4/roles/coordinator/role.md +++ b/.codex/skills/team-lifecycle-v4/roles/coordinator/role.md @@ -6,7 +6,7 @@ Orchestrate team-lifecycle-v4: analyze -> dispatch -> spawn -> monitor -> report **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 +- `spawn_agent` / `wait_agent` / `close_agent` / `send_message` / `assign_task` calls - Status reports to the user - `request_user_input` prompts @@ -38,6 +38,8 @@ WRONG: Bash("npm test"), Bash("tsc"), etc. — worker work - Maintain session state (tasks.json) - Handle capability_gap reports - Execute completion action when pipeline finishes +- 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 - Read source code or explore codebase (delegate to workers) @@ -166,6 +168,16 @@ Delegate to @commands/monitor.md#handleSpawnNext: - auto_archive -> Archive & Clean (rm -rf session folder) - auto_keep -> Keep Active +## 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: ""` can be addressed by name in send_message, assign_task, and close_agent calls. + ## Error Handling | Error | Resolution | diff --git a/.codex/skills/team-lifecycle-v4/roles/supervisor/role.md b/.codex/skills/team-lifecycle-v4/roles/supervisor/role.md index 148d80d6..3f6d83de 100644 --- a/.codex/skills/team-lifecycle-v4/roles/supervisor/role.md +++ b/.codex/skills/team-lifecycle-v4/roles/supervisor/role.md @@ -17,7 +17,7 @@ Process and execution supervision at pipeline phase transition points. ## Identity - Tag: [supervisor] | Prefix: CHECKPOINT-* - Responsibility: Verify cross-artifact consistency, process compliance, and execution health between pipeline phases -- Residency: Spawned once, awakened via `send_input` at each checkpoint trigger (not SendMessage) +- Residency: Spawned once, awakened via `assign_task` at each checkpoint trigger (not SendMessage) ## Boundaries diff --git a/.codex/skills/team-perf-opt/SKILL.md b/.codex/skills/team-perf-opt/SKILL.md index 49c8de1d..4cf61c6d 100644 --- a/.codex/skills/team-perf-opt/SKILL.md +++ b/.codex/skills/team-perf-opt/SKILL.md @@ -1,7 +1,7 @@ --- name: team-perf-opt description: Unified team skill for performance optimization. Coordinator orchestrates pipeline, workers are team-worker agents. Supports single/fan-out/independent parallel modes. Triggers on "team perf-opt". -allowed-tools: spawn_agent(*), wait_agent(*), send_input(*), close_agent(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__ace-tool__search_context(*) +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(*), mcp__ace-tool__search_context(*) --- # Team Performance Optimization @@ -65,7 +65,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 | @@ -96,6 +97,8 @@ Coordinator spawns workers using this template: ``` spawn_agent({ agent_type: "team_worker", + task_name: "", + fork_context: false, items: [ { type: "text", text: `## Role Assignment role: @@ -119,11 +122,37 @@ 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. **Inner Loop roles** (optimizer): Set `inner_loop: true`. **Single-task roles** (profiler, strategist, benchmarker, reviewer): Set `inner_loop: false`. + +### Model Selection Guide + +Performance optimization is measurement-driven. Profiler and benchmarker need consistent context for before/after comparison. + +| Role | reasoning_effort | Rationale | +|------|-------------------|-----------| +| profiler | high | Must identify subtle bottlenecks from profiling data | +| strategist | high | Optimization strategy requires understanding tradeoffs | +| optimizer | high | Performance-critical code changes need precision | +| benchmarker | medium | Benchmark execution follows defined measurement plan | +| reviewer | high | Must verify optimizations don't introduce regressions | + +### Benchmark Context Sharing with fork_context + +For before/after comparison, benchmarker should share context with profiler's baseline: +``` +spawn_agent({ + agent_type: "team_worker", + task_name: "BENCH-001", + fork_context: true, // Share context so benchmarker sees profiler's baseline metrics + reasoning_effort: "medium", + items: [...] +}) +``` + ## User Commands | Command | Action | @@ -155,6 +184,42 @@ After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect +-- .msg/meta.json # Session metadata ``` +## v4 Agent Coordination + +### Message Semantics + +| Intent | API | Example | +|--------|-----|---------| +| Queue supplementary info (don't interrupt) | `send_message` | Send baseline metrics to running optimizer | +| Assign fix after benchmark regression | `assign_task` | Assign FIX task when benchmark shows regression | +| Check running agents | `list_agents` | Verify agent health during resume | + +### Agent Health Check + +Use `list_agents({})` in handleResume and handleComplete: + +``` +// Reconcile session state with actual running agents +const running = list_agents({}) +// Compare with session.json active tasks +// Reset orphaned tasks (in_progress but agent gone) to pending +``` + +### Named Agent Targeting + +Workers are spawned with `task_name: ""` enabling direct addressing: +- `send_message({ target: "IMPL-001", items: [...] })` -- send strategy details to optimizer +- `assign_task({ target: "IMPL-001", items: [...] })` -- assign fix after benchmark regression +- `close_agent({ target: "BENCH-001" })` -- cleanup after benchmarking completes + +### Baseline-to-Result Pipeline + +Profiler baseline metrics flow through the pipeline and must reach benchmarker for comparison: +1. PROFILE-001 produces `baseline-metrics.json` in artifacts/ +2. Coordinator includes baseline reference in upstream context for all downstream workers +3. BENCH-001 reads baseline and compares against post-optimization measurements +4. If regression detected, coordinator auto-creates FIX task with regression details + ## Completion Action When the pipeline completes: diff --git a/.codex/skills/team-perf-opt/roles/coordinator/commands/monitor.md b/.codex/skills/team-perf-opt/roles/coordinator/commands/monitor.md index 60f5f834..8518eac7 100644 --- a/.codex/skills/team-perf-opt/roles/coordinator/commands/monitor.md +++ b/.codex/skills/team-perf-opt/roles/coordinator/commands/monitor.md @@ -65,6 +65,7 @@ Find and spawn the next ready tasks. ``` spawn_agent({ agent_type: "team_worker", + task_name: taskId, // e.g., "IMPL-001" — enables named targeting items: [{ description: "Spawn worker for ", team_name: "perf-opt", @@ -93,7 +94,22 @@ Execute built-in Phase 1 -> role-spec Phase 2-4 -> built-in Phase 5.` | Fan-out (IMPL-B{NN} done) | BENCH-B{NN} + REVIEW-B{NN} ready | Spawn both for that branch in parallel | | Independent | Any unblocked task | Spawn all ready tasks across all pipelines in parallel | -4. STOP after spawning -- use `wait_agent({ ids: [] })` to wait for next callback +4. STOP after spawning -- use `wait_agent({ targets: [], timeout_ms: 900000 })` to wait for next callback. If `result.timed_out`, mark tasks as `timed_out` and close agents. Use `close_agent({ target: taskId })` with task_name for cleanup. + +**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 profiling results to running optimizers +send_message({ + target: "", + 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. ### Review-Fix Cycle (CP-3) @@ -242,6 +258,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: @@ -262,6 +288,14 @@ Handle consensus_blocked signals from discuss rounds. ### 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 and no fix cycles remain. **Completion check varies by mode**: diff --git a/.codex/skills/team-perf-opt/roles/coordinator/role.md b/.codex/skills/team-perf-opt/roles/coordinator/role.md index adc56347..bdfb01ac 100644 --- a/.codex/skills/team-perf-opt/roles/coordinator/role.md +++ b/.codex/skills/team-perf-opt/roles/coordinator/role.md @@ -10,7 +10,7 @@ Orchestrates the performance optimization pipeline: manages task chains, spawns **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 +- `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): @@ -35,6 +35,8 @@ WRONG: Edit/Write on project source files — worker work - Handle review-fix cycles with max 3 iterations per branch - 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 @@ -155,6 +157,16 @@ All subsequent coordination handled by `@commands/monitor.md`. --- +## 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: ""` can be addressed by name in send_message, assign_task, and close_agent calls. + ## Error Handling | Scenario | Resolution | diff --git a/.codex/skills/team-planex/SKILL.md b/.codex/skills/team-planex/SKILL.md index 9cd94770..a529f149 100644 --- a/.codex/skills/team-planex/SKILL.md +++ b/.codex/skills/team-planex/SKILL.md @@ -1,7 +1,7 @@ --- name: team-planex description: Unified team skill for plan-and-execute pipeline. Pure router — coordinator always. Beat model is coordinator-only in monitor.md. Triggers on "team planex". -allowed-tools: spawn_agent(*), wait_agent(*), send_input(*), close_agent(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__ccw-tools__team_msg(*) +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(*), mcp__ccw-tools__team_msg(*) --- # Team PlanEx @@ -53,7 +53,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 | @@ -83,6 +84,8 @@ Coordinator spawns workers using this template: ``` spawn_agent({ agent_type: "team_worker", + task_name: "", + fork_context: false, items: [ { type: "text", text: `## Role Assignment role: @@ -107,7 +110,27 @@ 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 | +|------|-------|-------------------|-----------| +| Planner (PLAN-*) | (default) | high | Solution planning requires deep code analysis | +| Executor (EXEC-*) | (default) | high | Code implementation needs precision | + +Override model/reasoning_effort in spawn_agent when cost optimization is needed: +``` +spawn_agent({ + agent_type: "team_worker", + task_name: "", + fork_context: false, + model: "", + reasoning_effort: "", + items: [...] +}) +``` ## User Commands @@ -140,6 +163,45 @@ After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect - [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions, task metadata registry, execution method selection +## v4 Agent Coordination + +### Message Semantics + +| Intent | API | Example | +|--------|-----|---------| +| Send plan updates to running executor | `send_message` | Queue planner solution details to EXEC-* workers | +| Not used in this skill | `assign_task` | No resident agents -- planner and executor are one-shot | +| Check running agents | `list_agents` | Verify planner/executor health during resume | + +### Two-Phase Pipeline Pattern + +Plan-and-execute is a **Two-Phase pattern**: planner creates solution plans (PLAN-*), then coordinator spawns executors (EXEC-*) for each planned issue. The planner may dynamically create EXEC-* task entries in tasks.json. + +``` +// Phase 1: Planner runs, creates EXEC-* tasks in tasks.json +spawn_agent({ agent_type: "team_worker", task_name: "PLAN-001", ... }) +wait_agent({ targets: ["PLAN-001"], timeout_ms: 900000 }) +// Phase 2: Executors run per-issue, may run in sequence or parallel +// Inner loop: planner/executor handle multiple tasks internally +``` + +### 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 +``` + +### Named Agent Targeting + +Workers are spawned with `task_name: ""` enabling direct addressing: +- `send_message({ target: "EXEC-001", items: [...] })` -- queue plan solution to running executor +- `close_agent({ target: "PLAN-001" })` -- cleanup by name after completion + ## Error Handling | Scenario | Resolution | diff --git a/.codex/skills/team-planex/roles/coordinator/commands/monitor.md b/.codex/skills/team-planex/roles/coordinator/commands/monitor.md index 9c3c8ec0..8350dc67 100644 --- a/.codex/skills/team-planex/roles/coordinator/commands/monitor.md +++ b/.codex/skills/team-planex/roles/coordinator/commands/monitor.md @@ -42,7 +42,7 @@ Receive result from wait_agent for [] | +- YES -> Update session -> STOP +- Task status = completed? | +- YES -> remove from active_workers -> update session - | | +- Close agent: close_agent({ id: }) + | | +- Close agent: close_agent({ target: }) | | +- role = planner? | | | +- Check for new EXEC-* tasks in tasks.json (planner creates them) | | | +- -> handleSpawnNext (spawn executor for new EXEC-* tasks) @@ -87,6 +87,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 +``` + ``` Load active_workers +- No active workers -> handleSpawnNext @@ -120,6 +130,7 @@ Collect task states from tasks.json +- Spawn team_worker: const agentId = spawn_agent({ agent_type: "team_worker", + task_name: taskId, // e.g., "PLAN-001" — enables named targeting items: [{ type: "text", text: `## Role Assignment role: role_spec: ~ or /.codex/skills/team-planex/roles//role.md @@ -130,14 +141,49 @@ requirement: inner_loop: true execution_method: ` }] }) - // 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 + } else { + // Process result, update tasks.json + close_agent({ target: taskId }) // Use task_name, not agentId + } +- Add to session.active_workers Update session -> 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 planning results to running executors +send_message({ + target: "", + 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. + +--- + +### Pipeline Complete (PIPELINE_COMPLETE -> Phase 5) + +**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 +``` + +When all tasks are completed (no pending, no in_progress), transition to coordinator Phase 5. + --- ## Phase 4: Validation diff --git a/.codex/skills/team-planex/roles/coordinator/role.md b/.codex/skills/team-planex/roles/coordinator/role.md index db2f27f0..4ce0a368 100644 --- a/.codex/skills/team-planex/roles/coordinator/role.md +++ b/.codex/skills/team-planex/roles/coordinator/role.md @@ -6,7 +6,7 @@ Orchestrate team-planex: analyze -> dispatch -> spawn -> monitor -> report. **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 +- `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): @@ -33,6 +33,8 @@ WRONG: Edit/Write on project source files — worker work - Monitor progress via `commands/monitor.md` with Spawn-and-Stop pattern - Maintain session state (.msg/meta.json) - **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 - Execute planning or implementation work directly (delegate to workers) @@ -148,6 +150,16 @@ Delegate to `@commands/dispatch.md`: - auto_keep -> Keep Active (status=paused) - auto_yes -> Archive & Clean without prompting +## 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: ""` can be addressed by name in send_message, assign_task, and close_agent calls. + ## Error Handling | Error | Resolution | diff --git a/.codex/skills/team-quality-assurance/SKILL.md b/.codex/skills/team-quality-assurance/SKILL.md index d7b68d73..815dc7bb 100644 --- a/.codex/skills/team-quality-assurance/SKILL.md +++ b/.codex/skills/team-quality-assurance/SKILL.md @@ -1,7 +1,7 @@ --- name: team-quality-assurance description: Unified team skill for quality assurance. Full closed-loop QA combining issue discovery and software testing. Triggers on "team quality-assurance", "team qa". -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 Quality Assurance @@ -55,7 +55,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 | @@ -86,6 +87,8 @@ Coordinator spawns workers using this template: ``` spawn_agent({ agent_type: "team_worker", + task_name: "", + fork_context: false, items: [ { type: "text", text: `## Role Assignment role: @@ -109,7 +112,30 @@ 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 | +|------|-------|-------------------|-----------| +| Scout (SCOUT-*) | (default) | medium | Issue discovery scanning, less reasoning needed | +| Strategist (QASTRAT-*) | (default) | high | Test strategy design requires deep analysis | +| Generator (QAGEN-*) | (default) | high | Test code generation needs precision | +| Executor (QARUN-*) | (default) | medium | Running tests and collecting results | +| Analyst (QAANA-*) | (default) | high | Quality analysis and coverage assessment | + +Override model/reasoning_effort in spawn_agent when cost optimization is needed: +``` +spawn_agent({ + agent_type: "team_worker", + task_name: "", + fork_context: false, + model: "", + reasoning_effort: "", + items: [...] +}) +``` ## User Commands @@ -121,6 +147,37 @@ After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect | `--mode=testing` | Force testing mode | | `--mode=full` | Force full QA mode | +## v4 Agent Coordination + +### Message Semantics + +| Intent | API | Example | +|--------|-----|---------| +| Send scout findings to running strategist | `send_message` | Queue issue scan results to QASTRAT-* | +| 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 | + +### Pipeline Pattern + +Sequential pipeline with GC loops: scout -> strategist -> generator -> executor -> analyst. The executor/generator may loop via GC fix tasks when coverage is below target (max 3 rounds). + +### 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 +``` + +### Named Agent Targeting + +Workers are spawned with `task_name: ""` enabling direct addressing: +- `send_message({ target: "QASTRAT-001", items: [...] })` -- queue scout findings to running strategist +- `close_agent({ target: "SCOUT-001" })` -- cleanup by name after completion + ## Completion Action When pipeline completes, coordinator presents: diff --git a/.codex/skills/team-quality-assurance/roles/coordinator/commands/monitor.md b/.codex/skills/team-quality-assurance/roles/coordinator/commands/monitor.md index e148f6b9..7ea6451d 100644 --- a/.codex/skills/team-quality-assurance/roles/coordinator/commands/monitor.md +++ b/.codex/skills/team-quality-assurance/roles/coordinator/commands/monitor.md @@ -95,6 +95,16 @@ Then STOP. ## 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 +``` + 1. No active workers -> handleSpawnNext 2. Has active -> check each status - completed -> mark done (update tasks.json) @@ -132,6 +142,7 @@ Find ready tasks, spawn workers, STOP. ``` spawn_agent({ agent_type: "team_worker", + task_name: taskId, // e.g., "SCOUT-001" — enables named targeting items: [{ description: "Spawn worker for ", team_name: "quality-assurance", @@ -157,10 +168,33 @@ Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 f. Add to active_workers 5. Update session, output summary, STOP -6. Use `wait_agent({ ids: [] })` to wait for callbacks. Workers use `report_agent_job_result()` to send results back. +6. Use `wait_agent({ targets: [], timeout_ms: 900000 })` to wait for callbacks. If `result.timed_out`, mark tasks as `timed_out` and close agents. Use `close_agent({ target: taskId })` with task_name for cleanup. Workers use `report_agent_job_result()` to send results back. + +**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 scout results to running strategist +send_message({ + target: "", + 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. ## 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 done. Generate report and completion action. 1. Verify all tasks (including GC fix/recheck tasks) have status "completed" or "deleted" in tasks.json diff --git a/.codex/skills/team-quality-assurance/roles/coordinator/role.md b/.codex/skills/team-quality-assurance/roles/coordinator/role.md index dbdb0598..225fa10b 100644 --- a/.codex/skills/team-quality-assurance/roles/coordinator/role.md +++ b/.codex/skills/team-quality-assurance/roles/coordinator/role.md @@ -6,7 +6,7 @@ Orchestrate team-quality-assurance: analyze -> dispatch -> spawn -> monitor -> r **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 +- `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): @@ -36,6 +36,8 @@ WRONG: Bash("npm test"), Bash("tsc"), etc. — worker work - Handle GC loop (generator-executor coverage cycles) - Execute completion action when pipeline finishes - **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 - Read source code or explore codebase (delegate to workers) @@ -151,6 +153,16 @@ Delegate to @commands/monitor.md#handleSpawnNext: - auto_archive -> Archive & Clean - auto_keep -> Keep Active +## 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: ""` can be addressed by name in send_message, assign_task, and close_agent calls. + ## Error Handling | Error | Resolution | diff --git a/.codex/skills/team-review/SKILL.md b/.codex/skills/team-review/SKILL.md index 4fd168ae..b52d746a 100644 --- a/.codex/skills/team-review/SKILL.md +++ b/.codex/skills/team-review/SKILL.md @@ -1,7 +1,7 @@ --- name: team-review description: "Unified team skill for code review. 3-role pipeline: scanner, reviewer, fixer. Triggers on team-review." -allowed-tools: spawn_agent(*), wait_agent(*), send_input(*), close_agent(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__ace-tool__search_context(*) +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(*), mcp__ace-tool__search_context(*) --- # Team Review @@ -53,7 +53,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 | @@ -84,6 +85,8 @@ Coordinator spawns workers using this template: ``` spawn_agent({ agent_type: "team_worker", + task_name: "", + fork_context: false, items: [ { type: "text", text: `## Role Assignment role: @@ -107,7 +110,28 @@ 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 | +|------|-------|-------------------|-----------| +| Scanner (SCAN-*) | (default) | medium | Toolchain scanning + pattern matching, less reasoning | +| Reviewer (REV-*) | (default) | high | Deep root cause analysis requires full reasoning | +| Fixer (FIX-*) | (default) | high | Code modification needs precision | + +Override model/reasoning_effort in spawn_agent when cost optimization is needed: +``` +spawn_agent({ + agent_type: "team_worker", + task_name: "", + fork_context: false, + model: "", + reasoning_effort: "", + items: [...] +}) +``` ## User Commands @@ -121,6 +145,37 @@ After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect | `--dimensions=sec,cor,prf,mnt` | Custom dimensions | | `-y` / `--yes` | Skip confirmations | +## v4 Agent Coordination + +### Message Semantics + +| Intent | API | Example | +|--------|-----|---------| +| Send scan findings to running reviewer | `send_message` | Queue scan results to REV-* as supplementary context | +| Not used in this skill | `assign_task` | No resident agents -- sequential 3-stage pipeline | +| Check running agents | `list_agents` | Verify agent health during resume | + +### Pipeline Pattern + +This is a **sequential 3-stage pipeline** (scan -> review -> fix). No parallel phases. Each stage completes before the next starts. The coordinator may skip stages (0 findings -> skip review+fix; user declines fix -> skip fix). + +### 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 +``` + +### Named Agent Targeting + +Workers are spawned with `task_name: ""` enabling direct addressing: +- `send_message({ target: "REV-001", items: [...] })` -- queue scan findings to running reviewer +- `close_agent({ target: "SCAN-001" })` -- cleanup by name after completion + ## Completion Action When pipeline completes, coordinator presents: diff --git a/.codex/skills/team-review/roles/coordinator/commands/monitor.md b/.codex/skills/team-review/roles/coordinator/commands/monitor.md index b52630f8..ffdf500c 100644 --- a/.codex/skills/team-review/roles/coordinator/commands/monitor.md +++ b/.codex/skills/team-review/roles/coordinator/commands/monitor.md @@ -54,6 +54,16 @@ Then STOP. ## 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 +``` + 1. Read tasks.json, check active_agents 2. No active agents -> handleSpawnNext 3. Has active agents -> check each status @@ -88,6 +98,7 @@ state.tasks[taskId].status = 'in_progress' // 2) Spawn worker const agentId = spawn_agent({ agent_type: "team_worker", + task_name: taskId, // e.g., "SCAN-001" — enables named targeting items: [ { type: "text", text: `## Role Assignment role: ${role} @@ -109,12 +120,18 @@ Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 // 3) Track agent state.active_agents[taskId] = { agentId, role, started_at: now } -// 4) Wait for completion -wait_agent({ ids: [agentId] }) - -// 5) Collect results -state.tasks[taskId].status = 'completed' -delete state.active_agents[taskId] +// 4) Wait for completion — use task_name for stable targeting (v4) +const waitResult = wait_agent({ targets: [taskId], timeout_ms: 900000 }) +if (waitResult.timed_out) { + state.tasks[taskId].status = 'timed_out' + close_agent({ target: taskId }) + delete state.active_agents[taskId] +} else { + // 5) Collect results + state.tasks[taskId].status = 'completed' + close_agent({ target: taskId }) // Use task_name, not agentId + delete state.active_agents[taskId] +} ``` e. Check for checkpoints after worker completes: @@ -136,8 +153,31 @@ delete state.active_agents[taskId] 5. Update tasks.json, 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 scan results to running reviewer +send_message({ + target: "", + 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. + ## 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 done. Generate report and completion action. 1. All tasks completed or deleted (no pending, no in_progress) diff --git a/.codex/skills/team-review/roles/coordinator/role.md b/.codex/skills/team-review/roles/coordinator/role.md index 2a6fcb8a..0e2ccc57 100644 --- a/.codex/skills/team-review/roles/coordinator/role.md +++ b/.codex/skills/team-review/roles/coordinator/role.md @@ -6,7 +6,7 @@ Orchestrate team-review: parse target -> detect mode -> dispatch task chain -> m **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 +- `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): @@ -36,6 +36,8 @@ WRONG: Edit/Write on project source files — worker work - Maintain session state (tasks.json) - Execute completion action when pipeline finishes - **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 - Run analysis tools directly (semgrep, eslint, tsc, etc.) @@ -151,6 +153,16 @@ Delegate to @commands/monitor.md#handleSpawnNext: - auto_archive -> Archive & Clean - auto_keep -> Keep Active +## 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: ""` can be addressed by name in send_message, assign_task, and close_agent calls. + ## Error Handling | Error | Resolution | diff --git a/.codex/skills/team-roadmap-dev/SKILL.md b/.codex/skills/team-roadmap-dev/SKILL.md index 544cedd1..03d23434 100644 --- a/.codex/skills/team-roadmap-dev/SKILL.md +++ b/.codex/skills/team-roadmap-dev/SKILL.md @@ -1,7 +1,7 @@ --- name: team-roadmap-dev description: Unified team skill for roadmap-driven development workflow. Coordinator discusses roadmap with user, then dispatches phased execution pipeline (plan -> execute -> verify). All roles invoke this skill with --role arg. Triggers on "team roadmap-dev". -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 Roadmap Dev @@ -59,7 +59,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 | @@ -90,6 +91,8 @@ Coordinator spawns workers using this template: ``` spawn_agent({ agent_type: "team_worker", + task_name: "", + fork_context: false, items: [ { type: "text", text: `## Role Assignment role: @@ -113,10 +116,23 @@ 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. **All worker roles** (planner, executor, verifier): Set `inner_loop: true`. + +### Model Selection Guide + +Roadmap development is context-heavy with multi-phase execution. All roles use inner_loop and need high reasoning for complex planning/execution. + +| Role | reasoning_effort | Rationale | +|------|-------------------|-----------| +| planner | high | Phase planning requires understanding full roadmap context | +| executor | high | Implementation must align with phase plan precisely | +| verifier | high | Gap detection requires thorough verification against plan | + +All roles are inner_loop=true, enabling coordinator to send additional context via `assign_task` as phases progress. + ## User Commands | Command | Action | @@ -150,6 +166,42 @@ After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect +-- meta.json # Session metadata + shared state ``` +## v4 Agent Coordination + +### Message Semantics + +| Intent | API | Example | +|--------|-----|---------| +| Queue supplementary info (don't interrupt) | `send_message` | Send phase context to running executor | +| Assign phase work / gap closure | `assign_task` | Assign gap closure iteration to executor after verify | +| Check running agents | `list_agents` | Verify agent health during resume | + +### Agent Health Check + +Use `list_agents({})` in handleResume and handleComplete: + +``` +// Reconcile session state with actual running agents +const running = list_agents({}) +// Compare with state.md and config.json active tasks +// Reset orphaned tasks (in_progress but agent gone) to pending +``` + +### Named Agent Targeting + +Workers are spawned with `task_name: ""` enabling direct addressing: +- `send_message({ target: "EXEC-N01", items: [...] })` -- send supplementary context to executor +- `assign_task({ target: "PLAN-N01", items: [...] })` -- assign next phase planning +- `close_agent({ target: "VERIFY-N01" })` -- cleanup after verification + +### Multi-Phase Context Accumulation + +Each phase builds on previous phase results. Coordinator accumulates context across phases: +- Phase N planner receives: roadmap.md + state.md + all previous phase summaries +- Phase N executor receives: phase plan + previous phase implementation context +- Phase N verifier receives: phase plan + executor results + success criteria from roadmap +- On gap closure: verifier findings are sent back to executor via `assign_task` (max 3 iterations) + ## Completion Action When the pipeline completes: diff --git a/.codex/skills/team-roadmap-dev/roles/coordinator/commands/monitor.md b/.codex/skills/team-roadmap-dev/roles/coordinator/commands/monitor.md index 806497a8..0f6d838f 100644 --- a/.codex/skills/team-roadmap-dev/roles/coordinator/commands/monitor.md +++ b/.codex/skills/team-roadmap-dev/roles/coordinator/commands/monitor.md @@ -261,6 +261,7 @@ Ready tasks found? ``` spawn_agent({ agent_type: "team_worker", + task_name: taskId, // e.g., "PLAN-101" — enables named targeting items: [{ description: "Spawn worker for ", team_name: "roadmap-dev", @@ -286,7 +287,22 @@ Execute built-in Phase 1 -> role-spec Phase 2-4 -> built-in Phase 5.` }) ``` -Workers report results via `report_agent_job_result()`. Coordinator receives results via `wait_agent({ ids })`. +Workers report results via `report_agent_job_result()`. Coordinator receives results via `wait_agent({ targets: [taskId], timeout_ms: 900000 })`. If `result.timed_out`, mark tasks as `timed_out` and close agents. Use `close_agent({ target: taskId })` with task_name for cleanup. + +**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 planning results to running executor +send_message({ + target: "", + 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. --- @@ -330,6 +346,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. Also handles resume from paused state. ``` @@ -354,6 +380,14 @@ Check coordinates.status: ### 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 +``` + All phases done. Generate final project summary and finalize session. ``` diff --git a/.codex/skills/team-roadmap-dev/roles/coordinator/role.md b/.codex/skills/team-roadmap-dev/roles/coordinator/role.md index 2b114ec4..9ab76a4e 100644 --- a/.codex/skills/team-roadmap-dev/roles/coordinator/role.md +++ b/.codex/skills/team-roadmap-dev/roles/coordinator/role.md @@ -6,7 +6,7 @@ Orchestrate the roadmap-driven development workflow: init prerequisites -> roadm **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 +- `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): @@ -41,6 +41,8 @@ WRONG: Edit/Write on project source files — worker work - Monitor progress via worker callbacks and route messages - Maintain session state persistence - **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 @@ -135,6 +137,7 @@ For callback/check/resume/complete: load `@commands/monitor.md` and execute matc | `report_agent_job_result` | Worker communication | workers | Report results to coordinator | | `mcp__ccw-tools__team_msg` | Message bus | coordinator | Log all communications | | `Read/Write` | File operations | coordinator | Session state management | +| `list_agents` | System | coordinator | Runtime agent discovery and health check | --- @@ -262,7 +265,7 @@ mcp__ccw-tools__team_msg({ **Design**: Spawn-and-Stop + Callback pattern. - Spawn workers with `spawn_agent()` -> immediately return -- Worker completes -> report_agent_job_result() -> coordinator receives via wait_agent() -> auto-advance +- Worker completes -> report_agent_job_result() -> coordinator receives via wait_agent({ timeout_ms: 900000 }) -> auto-advance - User can use "check" / "resume" to manually advance - Coordinator does one operation per invocation, then STOPS @@ -304,6 +307,16 @@ Delegate to `@commands/monitor.md`: --- +## 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: ""` can be addressed by name in send_message, assign_task, and close_agent calls. + ## Error Handling | Scenario | Resolution | diff --git a/.codex/skills/team-tech-debt/SKILL.md b/.codex/skills/team-tech-debt/SKILL.md index b15c40f0..e5427ed9 100644 --- a/.codex/skills/team-tech-debt/SKILL.md +++ b/.codex/skills/team-tech-debt/SKILL.md @@ -1,7 +1,7 @@ --- name: team-tech-debt description: Unified team skill for tech debt identification and remediation. Scans codebase for tech debt, assesses severity, plans and executes fixes with validation. Uses team-worker agent architecture with roles/ for domain logic. Coordinator orchestrates pipeline, workers are team-worker agents. Triggers on "team tech debt". -allowed-tools: spawn_agent(*), wait_agent(*), send_input(*), close_agent(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__ace-tool__search_context(*), mcp__ccw-tools__read_file(*), mcp__ccw-tools__write_file(*), mcp__ccw-tools__edit_file(*), mcp__ccw-tools__team_msg(*) +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(*), mcp__ace-tool__search_context(*), mcp__ccw-tools__read_file(*), mcp__ccw-tools__write_file(*), mcp__ccw-tools__edit_file(*), mcp__ccw-tools__team_msg(*) --- # Team Tech Debt @@ -55,7 +55,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 | @@ -86,6 +87,8 @@ Coordinator spawns workers using this template: ``` spawn_agent({ agent_type: "team_worker", + task_name: "", + fork_context: false, items: [ { type: "text", text: `## Role Assignment role: @@ -109,7 +112,29 @@ 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 + +Tech debt follows a discovery-to-fix pipeline. Scanner is broad/fast, later stages need deeper reasoning. + +| Role | reasoning_effort | Rationale | +|------|-------------------|-----------| +| scanner | medium | Broad codebase scan, pattern matching over deep analysis | +| assessor | high | Severity assessment requires understanding impact and risk | +| planner | high | Remediation planning must prioritize and sequence fixes | +| executor | high | Code fixes must preserve behavior while removing debt | +| validator | medium | Validation follows defined acceptance criteria | + +### Pipeline Pattern: Scanner Results Inform Downstream + +Scanner discoveries flow through the pipeline — each stage narrows and refines: +1. TDSCAN produces broad debt inventory +2. TDEVAL assesses and prioritizes (filters low-impact items) +3. TDPLAN creates sequenced fix plan from assessed items +4. TDFIX implements fixes per plan +5. TDVAL validates fixes against original debt findings ## User Commands @@ -141,6 +166,34 @@ After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect └── wisdom/ # Cross-task knowledge ``` +## v4 Agent Coordination + +### Message Semantics + +| Intent | API | Example | +|--------|-----|---------| +| Queue supplementary info (don't interrupt) | `send_message` | Send scan findings to running assessor | +| Assign fix from remediation plan | `assign_task` | Assign TDFIX task from planner output | +| Check running agents | `list_agents` | Verify agent health during resume | + +### Agent Health Check + +Use `list_agents({})` in handleResume and handleComplete: + +``` +// Reconcile session state with actual running agents +const running = list_agents({}) +// Compare with meta.json active tasks +// Reset orphaned tasks (in_progress but agent gone) to pending +``` + +### Named Agent Targeting + +Workers are spawned with `task_name: ""` enabling direct addressing: +- `send_message({ target: "TDSCAN-001", items: [...] })` -- send additional scan scope to scanner +- `assign_task({ target: "TDFIX-001", items: [...] })` -- assign fix task from planner output +- `close_agent({ target: "TDVAL-001" })` -- cleanup after validation + ## Error Handling | Scenario | Resolution | diff --git a/.codex/skills/team-tech-debt/roles/coordinator/commands/monitor.md b/.codex/skills/team-tech-debt/roles/coordinator/commands/monitor.md index 0ed94772..9e08be93 100644 --- a/.codex/skills/team-tech-debt/roles/coordinator/commands/monitor.md +++ b/.codex/skills/team-tech-debt/roles/coordinator/commands/monitor.md @@ -43,6 +43,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 +``` + 1. Read tasks.json, check active_agents 2. Tasks stuck in "in_progress" -> reset to "pending" 3. Tasks with completed deps but still "pending" -> include in spawn list @@ -72,6 +82,7 @@ state.tasks[taskId].status = 'in_progress' // 2) Spawn worker const agentId = spawn_agent({ agent_type: "team_worker", + task_name: taskId, // e.g., "TDSCAN-001" — enables named targeting items: [ { type: "text", text: `## Role Assignment role: ${task.role} @@ -112,15 +123,22 @@ Stage-to-role mapping: 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, timeout_ms: 900000 }) - -// 5) Collect results -for (const [taskId, agent] of Object.entries(state.active_agents)) { - state.tasks[taskId].status = 'completed' - close_agent({ id: agent.agentId }) - 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 + 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] + } } ``` @@ -188,6 +206,21 @@ After task completion, check for checkpoints: } ``` +**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 scan results to running assessor +send_message({ + target: "", + 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. + ### Persist and Loop After processing all results: @@ -199,6 +232,14 @@ After processing all results: ## 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 done. Generate report and completion action. 1. Verify all tasks (including fix-verify tasks) have status "completed" diff --git a/.codex/skills/team-tech-debt/roles/coordinator/role.md b/.codex/skills/team-tech-debt/roles/coordinator/role.md index ba4b88e5..7e0225ca 100644 --- a/.codex/skills/team-tech-debt/roles/coordinator/role.md +++ b/.codex/skills/team-tech-debt/roles/coordinator/role.md @@ -6,7 +6,7 @@ **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 +- `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): @@ -33,6 +33,8 @@ WRONG: Edit/Write on project source files — worker work - Monitor worker progress via spawn_agent/wait_agent and route messages - Maintain session state persistence (tasks.json) - **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 - Execute tech debt work directly (delegate to workers) @@ -147,6 +149,16 @@ Delegate to @commands/monitor.md#handleSpawnNext: 5. Output with [coordinator] prefix 6. Execute completion action (request_user_input: 新目标 / 深度修复 / 关闭团队) +## 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: ""` can be addressed by name in send_message, assign_task, and close_agent calls. + ## Error Handling | Error | Resolution | diff --git a/.codex/skills/team-testing/SKILL.md b/.codex/skills/team-testing/SKILL.md index 69bee280..6655d810 100644 --- a/.codex/skills/team-testing/SKILL.md +++ b/.codex/skills/team-testing/SKILL.md @@ -1,7 +1,7 @@ --- name: team-testing description: Unified team skill for testing team. Progressive test coverage through Generator-Critic loops, shared memory, and dynamic layer selection. Triggers on "team testing". -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 Testing @@ -54,7 +54,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 | @@ -85,6 +86,8 @@ Coordinator spawns workers using this template: ``` spawn_agent({ agent_type: "team_worker", + task_name: "", + fork_context: false, items: [ { type: "text", text: `## Role Assignment role: @@ -108,7 +111,29 @@ 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 | +|------|-------|-------------------|-----------| +| Strategist (STRATEGY-*) | (default) | high | Test strategy requires deep code understanding | +| Generator (TESTGEN-*) | (default) | high | Test code generation needs precision | +| Executor (TESTRUN-*) | (default) | medium | Running tests and collecting results, less reasoning | +| Analyst (TESTANA-*) | (default) | high | Coverage analysis and quality assessment | + +Override model/reasoning_effort in spawn_agent when cost optimization is needed: +``` +spawn_agent({ + agent_type: "team_worker", + task_name: "", + fork_context: false, + model: "", + reasoning_effort: "", + items: [...] +}) +``` ## User Commands @@ -119,6 +144,50 @@ After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect | `revise ` | Revise specific task | | `feedback ` | Inject feedback for revision | +## v4 Agent Coordination + +### Message Semantics + +| Intent | API | Example | +|--------|-----|---------| +| Send strategy to running generators | `send_message` | Queue test strategy findings to TESTGEN-* workers | +| Not used in this skill | `assign_task` | No resident agents -- all workers are one-shot | +| Check running agents | `list_agents` | Verify parallel generator/executor health | + +### Parallel Test Generation + +Comprehensive pipeline spawns multiple generators (per layer) and executors in parallel: + +``` +// Spawn parallel generators for L1 and L2 +const genNames = ["TESTGEN-001", "TESTGEN-002"] +for (const name of genNames) { + spawn_agent({ agent_type: "team_worker", task_name: name, ... }) +} +wait_agent({ targets: genNames, timeout_ms: 900000 }) +``` + +### GC Loop Coordination + +Generator-Critic loops create dynamic TESTGEN-fix and TESTRUN-fix tasks. The coordinator tracks `gc_rounds[layer]` and creates fix tasks dynamically when coverage is below target. + +### 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 +``` + +### Named Agent Targeting + +Workers are spawned with `task_name: ""` enabling direct addressing: +- `send_message({ target: "TESTGEN-001", items: [...] })` -- queue strategy context to running generator +- `close_agent({ target: "TESTRUN-001" })` -- cleanup by name after wait_agent returns + ## Completion Action When pipeline completes, coordinator presents: diff --git a/.codex/skills/team-testing/roles/coordinator/commands/monitor.md b/.codex/skills/team-testing/roles/coordinator/commands/monitor.md index f777de48..530fbcad 100644 --- a/.codex/skills/team-testing/roles/coordinator/commands/monitor.md +++ b/.codex/skills/team-testing/roles/coordinator/commands/monitor.md @@ -59,6 +59,16 @@ Then STOP. ## 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 +``` + 1. Read tasks.json, check active_agents 2. No active agents -> handleSpawnNext 3. Has active agents -> check each status @@ -96,6 +106,7 @@ state.tasks[taskId].status = 'in_progress' // 2) Spawn worker const agentId = spawn_agent({ agent_type: "team_worker", + task_name: taskId, // e.g., "STRATEGY-001" — enables named targeting items: [ { type: "text", text: `## Role Assignment role: ${task.role} @@ -135,15 +146,22 @@ state.active_agents[taskId] = { agentId, role: task.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, timeout_ms: 900000 }) - -// 5) Collect results -for (const [taskId, agent] of Object.entries(state.active_agents)) { - state.tasks[taskId].status = 'completed' - close_agent({ id: agent.agentId }) - 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 + 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] + } } ``` @@ -182,6 +200,21 @@ Add to tasks.json: ``` Update tasks.json gc_rounds[layer]++ +**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 strategy results to running generators +send_message({ + target: "", + 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. + ### Persist and Loop After processing all results: @@ -193,6 +226,14 @@ After processing all results: ## 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 done. Generate report and completion action. 1. Verify all tasks (including any GC fix tasks) have status "completed" or "failed" diff --git a/.codex/skills/team-testing/roles/coordinator/role.md b/.codex/skills/team-testing/roles/coordinator/role.md index 4d1e29bc..ecfb568e 100644 --- a/.codex/skills/team-testing/roles/coordinator/role.md +++ b/.codex/skills/team-testing/roles/coordinator/role.md @@ -6,7 +6,7 @@ Orchestrate team-testing: analyze -> dispatch -> spawn -> monitor -> report. **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 +- `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): @@ -34,6 +34,8 @@ WRONG: Edit/Write on test or source files — worker work - Handle Generator-Critic cycles with max 3 iterations per layer - 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 (test generation, execution, analysis) -- workers handle this @@ -160,6 +162,16 @@ Delegate to @commands/monitor.md#handleSpawnNext: - auto_archive -> Archive & Clean (rm -rf session folder) - auto_keep -> Keep Active +## 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: ""` can be addressed by name in send_message, assign_task, and close_agent calls. + ## Error Handling | Error | Resolution | diff --git a/.codex/skills/team-uidesign/SKILL.md b/.codex/skills/team-uidesign/SKILL.md index 2221cefe..16a14671 100644 --- a/.codex/skills/team-uidesign/SKILL.md +++ b/.codex/skills/team-uidesign/SKILL.md @@ -1,7 +1,7 @@ --- name: team-uidesign description: Unified team skill for UI design team. Research -> design tokens -> audit -> implementation. Uses team-worker agent architecture with roles/ for domain logic. Coordinator orchestrates dual-track pipeline with GC loops and sync points. Triggers on "team ui design", "ui design team". -allowed-tools: spawn_agent(*), wait_agent(*), send_input(*), close_agent(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__ace-tool__search_context(*), mcp__ccw-tools__read_file(*), mcp__ccw-tools__write_file(*), mcp__ccw-tools__edit_file(*), mcp__ccw-tools__team_msg(*) +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(*), mcp__ace-tool__search_context(*), mcp__ccw-tools__read_file(*), mcp__ccw-tools__write_file(*), mcp__ccw-tools__edit_file(*), mcp__ccw-tools__team_msg(*) --- # Team UI Design @@ -54,7 +54,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 | @@ -85,6 +86,8 @@ Coordinator spawns workers using this template: ``` spawn_agent({ agent_type: "team_worker", + task_name: "", + fork_context: false, items: [ { type: "text", text: `## Role Assignment role: @@ -108,7 +111,38 @@ 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 + +UI design is a creative pipeline where research findings inform design decisions. Researcher needs thorough analysis, designer needs creative reasoning. + +| Role | reasoning_effort | Rationale | +|------|-------------------|-----------| +| researcher | high | Deep analysis of existing design systems and patterns | +| designer | high | Creative design token/component spec generation | +| reviewer | high | Design audit must catch consistency and accessibility issues | +| implementer | medium | Implementation follows defined design specs | + +### Research-to-Design Context Flow + +Researcher findings must reach designer via coordinator's upstream context: +``` +// After RESEARCH-001 completes, coordinator sends findings to designer +spawn_agent({ + agent_type: "team_worker", + task_name: "DESIGN-001", + fork_context: false, + items: [ + ..., + { type: "text", text: `## Upstream Context +Research findings: /research/design-intelligence.json +Component inventory: /research/component-inventory.json +Accessibility audit: /research/accessibility-audit.json` } + ] +}) +``` ## User Commands @@ -145,6 +179,34 @@ After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect └── wisdom/ # Cross-task knowledge ``` +## v4 Agent Coordination + +### Message Semantics + +| Intent | API | Example | +|--------|-----|---------| +| Queue supplementary info (don't interrupt) | `send_message` | Send research findings to running designer | +| Assign build from reviewed specs | `assign_task` | Assign BUILD task after audit passes | +| Check running agents | `list_agents` | Verify agent health during resume | + +### Agent Health Check + +Use `list_agents({})` in handleResume and handleComplete: + +``` +// Reconcile session state with actual running agents +const running = list_agents({}) +// Compare with meta.json active tasks +// Reset orphaned tasks (in_progress but agent gone) to pending +``` + +### Named Agent Targeting + +Workers are spawned with `task_name: ""` enabling direct addressing: +- `send_message({ target: "DESIGN-001", items: [...] })` -- send additional research findings to designer +- `assign_task({ target: "BUILD-001", items: [...] })` -- assign implementation from reviewed design specs +- `close_agent({ target: "AUDIT-001" })` -- cleanup after design audit + ## Error Handling | Scenario | Resolution | diff --git a/.codex/skills/team-uidesign/roles/coordinator/commands/monitor.md b/.codex/skills/team-uidesign/roles/coordinator/commands/monitor.md index 423d4238..4f07b8b4 100644 --- a/.codex/skills/team-uidesign/roles/coordinator/commands/monitor.md +++ b/.codex/skills/team-uidesign/roles/coordinator/commands/monitor.md @@ -99,6 +99,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 +``` + 1. Audit tasks.json for inconsistencies: - Tasks stuck in "in_progress" -> reset to "pending" - Tasks with completed deps but still "pending" -> include in spawn list @@ -124,6 +134,7 @@ state.tasks[taskId].status = 'in_progress' // 2) Spawn worker const agentId = spawn_agent({ agent_type: "team_worker", + task_name: taskId, // e.g., "DESIGN-001" — enables named targeting items: [ { type: "text", text: `## Role Assignment role: ${role} @@ -141,12 +152,18 @@ Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 // 3) Track agent state.active_agents[taskId] = { agentId, role, started_at: now } -// 4) Wait for completion -wait_agent({ ids: [agentId] }) - -// 5) Collect results and update tasks.json -state.tasks[taskId].status = 'completed' -delete state.active_agents[taskId] +// 4) Wait for completion — use task_name for stable targeting (v4) +const waitResult = wait_agent({ targets: [taskId], timeout_ms: 900000 }) +if (waitResult.timed_out) { + state.tasks[taskId].status = 'timed_out' + close_agent({ target: taskId }) + delete state.active_agents[taskId] +} else { + // 5) Collect results and update tasks.json + state.tasks[taskId].status = 'completed' + close_agent({ target: taskId }) // Use task_name, not agentId + delete state.active_agents[taskId] +} ``` **Parallel spawn rules by mode**: @@ -159,10 +176,33 @@ delete state.active_agents[taskId] | full-system | After Sync Point 1 | Spawn DESIGN-002 + BUILD-001 in parallel, wait_agent for both | | full-system | After BUILD-002 | Spawn AUDIT-003 | +**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 design results to running implementer +send_message({ + target: "", + 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. Update tasks.json, output summary, STOP ## 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 done. Generate report and completion action. **Completion check by mode**: diff --git a/.codex/skills/team-uidesign/roles/coordinator/role.md b/.codex/skills/team-uidesign/roles/coordinator/role.md index 1d0375a8..49159555 100644 --- a/.codex/skills/team-uidesign/roles/coordinator/role.md +++ b/.codex/skills/team-uidesign/roles/coordinator/role.md @@ -6,7 +6,7 @@ UI Design Team coordinator. Orchestrate pipeline: analyze -> dispatch -> spawn - **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 +- `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): @@ -34,6 +34,8 @@ WRONG: Edit/Write on project source files — worker work - Handle Generator-Critic loops with max 2 iterations - Maintain session state persistence (tasks.json) - **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 (researching, designing, auditing, building) -- workers handle this @@ -187,6 +189,16 @@ Delegate to `@commands/monitor.md#handleSpawnNext`: }) ``` +## 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: ""` can be addressed by name in send_message, assign_task, and close_agent calls. + ## Error Handling | Error | Resolution | diff --git a/.codex/skills/team-ultra-analyze/SKILL.md b/.codex/skills/team-ultra-analyze/SKILL.md index 7643134d..69e2e404 100644 --- a/.codex/skills/team-ultra-analyze/SKILL.md +++ b/.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: "", + fork_context: false, items: [ { type: "text", text: `## Role Assignment role: @@ -116,7 +119,29 @@ 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: "", + fork_context: false, + model: "", + reasoning_effort: "", + 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: ""` 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: diff --git a/.codex/skills/team-ultra-analyze/roles/coordinator/commands/monitor.md b/.codex/skills/team-ultra-analyze/roles/coordinator/commands/monitor.md index 132afecd..40f70c72 100644 --- a/.codex/skills/team-ultra-analyze/roles/coordinator/commands/monitor.md +++ b/.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: "", + 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**: diff --git a/.codex/skills/team-ultra-analyze/roles/coordinator/role.md b/.codex/skills/team-ultra-analyze/roles/coordinator/role.md index e17828c2..09095739 100644 --- a/.codex/skills/team-ultra-analyze/roles/coordinator/role.md +++ b/.codex/skills/team-ultra-analyze/roles/coordinator/role.md @@ -10,7 +10,7 @@ Orchestrates the analysis pipeline: topic clarification, pipeline mode selection **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 +- `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): @@ -35,6 +35,8 @@ WRONG: Edit/Write on project source files — worker work - 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 @@ -232,6 +234,16 @@ request_user_input({ --- +## 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: ""` can be addressed by name in send_message, assign_task, and close_agent calls. + ## Error Handling | Scenario | Resolution | diff --git a/.codex/skills/team-ux-improve/SKILL.md b/.codex/skills/team-ux-improve/SKILL.md index b860f962..6dfa0b27 100644 --- a/.codex/skills/team-ux-improve/SKILL.md +++ b/.codex/skills/team-ux-improve/SKILL.md @@ -1,7 +1,7 @@ --- name: team-ux-improve description: Unified team skill for UX improvement. Systematically discovers and fixes UI/UX interaction issues including unresponsive buttons, missing feedback, and state refresh problems. Uses team-worker agent architecture with roles/ for domain logic. Coordinator orchestrates pipeline, workers are team-worker agents. Triggers on "team ux improve". -allowed-tools: spawn_agent(*), wait_agent(*), send_input(*), close_agent(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__ace-tool__search_context(*), mcp__ccw-tools__read_file(*), mcp__ccw-tools__write_file(*), mcp__ccw-tools__edit_file(*), mcp__ccw-tools__team_msg(*) +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(*), mcp__ace-tool__search_context(*), mcp__ccw-tools__read_file(*), mcp__ccw-tools__write_file(*), mcp__ccw-tools__edit_file(*), mcp__ccw-tools__team_msg(*) --- # Team UX Improve @@ -63,7 +63,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 | @@ -94,6 +95,8 @@ Coordinator spawns workers using this template: ``` spawn_agent({ agent_type: "team_worker", + task_name: "", + fork_context: false, items: [ { type: "text", text: `## Role Assignment role: @@ -117,7 +120,21 @@ 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 + +UX improvement has an explorer utility member and a scan-diagnose-design-implement-test pipeline. + +| Role | reasoning_effort | Rationale | +|------|-------------------|-----------| +| explorer | low | File reading and pattern summarization only (utility member) | +| scanner | medium | Broad UI/UX issue scanning, pattern-based detection | +| diagnoser | high | Root cause diagnosis of UX issues requires deep analysis | +| designer | high | UX improvement design needs careful user experience reasoning | +| implementer | high | UI code changes must preserve existing behavior | +| tester | medium | Test execution follows defined UX verification criteria | ## User Commands @@ -152,6 +169,50 @@ After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect └── anti-patterns/ ``` +## v4 Agent Coordination + +### Message Semantics + +| Intent | API | Example | +|--------|-----|---------| +| Queue supplementary info (don't interrupt) | `send_message` | Send explorer findings to running scanner | +| Assign implementation from design | `assign_task` | Assign IMPL task from designer output | +| Check running agents | `list_agents` | Verify agent health during resume | + +### Agent Health Check + +Use `list_agents({})` in handleResume and handleComplete: + +``` +// Reconcile session state with actual running agents +const running = list_agents({}) +// Compare with meta.json active tasks +// Reset orphaned tasks (in_progress but agent gone) to pending +``` + +### Named Agent Targeting + +Workers are spawned with `task_name: ""` enabling direct addressing: +- `send_message({ target: "SCAN-001", items: [...] })` -- send explorer findings to scanner +- `assign_task({ target: "IMPL-001", items: [...] })` -- assign UX fix from designer output +- `close_agent({ target: "TEST-001" })` -- cleanup after UX testing + +### Explorer-Assisted Scanning + +Coordinator spawns explorer (utility member) early to gather codebase context, then sends findings to scanner via upstream context: +``` +// Explorer results inform scanner's scope +send_message({ + target: "SCAN-001", + items: [ + { type: "text", text: `## Explorer Findings +component_patterns: +framework: +ui_library: ` } + ] +}) +``` + ## Error Handling | Scenario | Resolution | diff --git a/.codex/skills/team-ux-improve/roles/coordinator/commands/monitor.md b/.codex/skills/team-ux-improve/roles/coordinator/commands/monitor.md index 257a7c0a..8894eac4 100644 --- a/.codex/skills/team-ux-improve/roles/coordinator/commands/monitor.md +++ b/.codex/skills/team-ux-improve/roles/coordinator/commands/monitor.md @@ -79,6 +79,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 +``` + 1. Audit task list for inconsistencies: - Tasks stuck in "in_progress" -> reset to "pending" - Tasks with completed blockers but still "pending" -> include in spawn list @@ -101,6 +111,7 @@ Find ready tasks, spawn workers, STOP. ``` spawn_agent({ agent_type: "team_worker", + task_name: taskId, // e.g., "SCAN-001" — enables named targeting items: [{ description: "Spawn worker for ", team_name: "ux-improve", @@ -133,9 +144,33 @@ Inner loop roles: implementer (inner_loop: true) Single-task roles: scanner, diagnoser, designer, tester (inner_loop: false) 5. Add to active_workers, update session, output summary, STOP +6. Use `wait_agent({ targets: [], timeout_ms: 900000 })` to wait for callbacks. If `result.timed_out`, mark tasks as `timed_out` and close agents. Use `close_agent({ target: taskId })` with task_name for cleanup. + +**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 scan results to running diagnoser +send_message({ + target: "", + 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. ## 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 done. Generate report and completion action. 1. Verify all tasks (including any fix-verify iterations) have status "completed" diff --git a/.codex/skills/team-ux-improve/roles/coordinator/role.md b/.codex/skills/team-ux-improve/roles/coordinator/role.md index cef032a4..25dc6188 100644 --- a/.codex/skills/team-ux-improve/roles/coordinator/role.md +++ b/.codex/skills/team-ux-improve/roles/coordinator/role.md @@ -6,7 +6,7 @@ UX Improvement Team coordinator. Orchestrate pipeline: analyze -> dispatch -> sp **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 +- `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): @@ -35,6 +35,8 @@ WRONG: Edit/Write on project source files — worker work - Handle wisdom initialization and consolidation - Maintain session state persistence - **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 - Execute worker domain logic directly (scanning, diagnosing, designing, implementing, testing) @@ -144,6 +146,16 @@ Delegate to `@commands/monitor.md#handleSpawnNext`: }) ``` +## 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: ""` can be addressed by name in send_message, assign_task, and close_agent calls. + ## Error Handling | Error | Resolution |