claude-code-workflow 7.2.23 → 7.2.25

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

@@ -1,209 +1,243 @@
-# Monitor Pipeline
-
-Event-driven pipeline coordination. Beat model: coordinator wake -> process -> spawn -> STOP.
-
-## Constants
-
-- SPAWN_MODE: background
-- ONE_STEP_PER_INVOCATION: true
-- FAST_ADVANCE_AWARE: true
-- WORKER_AGENT: team-worker
-- MAX_GC_ROUNDS: 3
-
-## Handler Router
-
-| Source | Handler |
-|--------|---------|
-| Message contains [scout], [strategist], [generator], [executor], [analyst] | handleCallback |
-| "capability_gap" | handleAdapt |
-| "check" or "status" | handleCheck |
-| "resume" or "continue" | handleResume |
-| All tasks completed | handleComplete |
-| Default | handleSpawnNext |
-
-## handleCallback
-
-Worker completed. Process and advance.
-
-1. Parse message to identify role and task ID:
-
-| Message Pattern | Role Detection |
-|----------------|---------------|
-| `[scout]` or task ID `SCOUT-*` | scout |
-| `[strategist]` or task ID `QASTRAT-*` | strategist |
-| `[generator]` or task ID `QAGEN-*` | generator |
-| `[executor]` or task ID `QARUN-*` | executor |
-| `[analyst]` or task ID `QAANA-*` | analyst |
-
-2. Check if progress update (inner loop) or final completion
-3. Progress -> update session state, STOP
-4. Completion -> mark task done (read `<session>/tasks.json`, set status to "completed", write back), remove from active_workers
-5. Check for checkpoints:
-   - QARUN-* completes -> read meta.json for coverage:
-     - coverage >= target OR gc_rounds >= MAX_GC_ROUNDS -> proceed to handleSpawnNext
-     - coverage < target AND gc_rounds < MAX_GC_ROUNDS -> create GC fix tasks, increment gc_rounds
-
-**GC Fix Task Creation** (when coverage below target) -- add new entries to `<session>/tasks.json`:
-```json
-{
-  "id": "QAGEN-fix-<round>",
-  "subject": "QAGEN-fix-<round>: Fix tests for <layer> (GC #<round>)",
-  "description": "PURPOSE: Fix failing tests and improve coverage | Success: Coverage meets target\nTASK:\n  - Load execution results and failing test details\n  - Fix broken tests and add missing coverage\nCONTEXT:\n  - Session: <session-folder>\n  - Layer: <layer>\n  - Previous results: <session>/results/run-<layer>.json\nEXPECTED: Fixed test files | Improved coverage\nCONSTRAINTS: Only modify test files | No source changes\n---\nInnerLoop: false\nRoleSpec: ~  or <project>/.codex/skills/team-quality-assurance/roles/generator/role.md",
-  "status": "pending",
-  "owner": "generator",
-  "blockedBy": []
-}
-```
-
-```json
-{
-  "id": "QARUN-gc-<round>",
-  "subject": "QARUN-gc-<round>: Re-execute <layer> (GC #<round>)",
-  "description": "PURPOSE: Re-execute tests after fixes | Success: Coverage >= target\nTASK: Execute test suite, measure coverage, report results\nCONTEXT:\n  - Session: <session-folder>\n  - Layer: <layer>\nEXPECTED: <session>/results/run-<layer>-gc-<round>.json\nCONSTRAINTS: Read-only execution\n---\nInnerLoop: false\nRoleSpec: ~  or <project>/.codex/skills/team-quality-assurance/roles/executor/role.md",
-  "status": "pending",
-  "owner": "executor",
-  "blockedBy": ["QAGEN-fix-<round>"]
-}
-```
-
-6. -> handleSpawnNext
-
-## handleCheck
-
-Read-only status report, then STOP.
-
-Output:
-```
-[coordinator] QA Pipeline Status
-[coordinator] Mode: <pipeline_mode>
-[coordinator] Progress: <done>/<total> (<pct>%)
-[coordinator] GC Rounds: <gc_rounds>/3
-
-[coordinator] Pipeline Graph:
-  SCOUT-001:   <done|run|wait> <summary>
-  QASTRAT-001: <done|run|wait> <summary>
-  QAGEN-001:   <done|run|wait> <summary>
-  QARUN-001:   <done|run|wait> <summary>
-  QAANA-001:   <done|run|wait> <summary>
-
-[coordinator] Active Workers: <list with elapsed time>
-[coordinator] Ready: <pending tasks with resolved deps>
-[coordinator] Commands: 'resume' to advance | 'check' to refresh
-```
-
-Then STOP.
-
-## handleResume
-
-1. No active workers -> handleSpawnNext
-2. Has active -> check each status
-   - completed -> mark done (update tasks.json)
-   - in_progress -> still running
-3. Some completed -> handleSpawnNext
-4. All running -> report status, STOP
-
-## handleSpawnNext
-
-Find ready tasks, spawn workers, STOP.
-
-1. Collect from `<session>/tasks.json`:
-   - completedSubjects: status = completed
-   - inProgressSubjects: status = in_progress
-   - readySubjects: status = pending AND all blockedBy in completedSubjects
-
-2. No ready + work in progress -> report waiting, STOP
-3. No ready + nothing in progress -> handleComplete
-4. Has ready -> for each:
-   a. Determine role from task prefix:
-
-| Prefix | Role | inner_loop |
-|--------|------|------------|
-| SCOUT-* | scout | false |
-| QASTRAT-* | strategist | false |
-| QAGEN-* | generator | false |
-| QARUN-* | executor | true |
-| QAANA-* | analyst | false |
-
-   b. Check if inner loop role with active worker -> skip (worker picks up next task)
-   c. Update task status to "in_progress" in tasks.json
-   d. team_msg log -> task_unblocked
-   e. Spawn team-worker:
-
-```
-spawn_agent({
-  agent_type: "team_worker",
-  items: [{
-    description: "Spawn <role> worker for <subject>",
-    team_name: "quality-assurance",
-    name: "<role>",
-    prompt: `## Role Assignment
-role: <role>
-role_spec: ~  or <project>/.codex/skills/team-quality-assurance/roles/<role>/role.md
-session: <session-folder>
-session_id: <session-id>
-team_name: quality-assurance
-requirement: <task-description>
-inner_loop: <true|false>
-
-## Current Task
-- Task ID: <task-id>
-- Task: <subject>
-
-Read role_spec file to load Phase 2-4 domain instructions.
-Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
-  }]
-})
-```
-
-   f. Add to active_workers
-5. Update session, output summary, STOP
-6. Use `wait_agent({ ids: [<spawned-agent-ids>] })` to wait for callbacks. Workers use `report_agent_job_result()` to send results back.
-
-## handleComplete
-
-Pipeline done. Generate report and completion action.
-
-1. Verify all tasks (including GC fix/recheck tasks) have status "completed" or "deleted" in tasks.json
-2. If any tasks incomplete -> return to handleSpawnNext
-3. If all complete:
-   - Read final state from meta.json (quality_score, coverage, gc_rounds)
-   - Generate summary (deliverables, stats, discussions)
-4. Read session.completion_action:
-   - interactive -> request_user_input (Archive/Keep/Export)
-   - auto_archive -> Archive & Clean (status=completed, remove/archive session folder)
-   - auto_keep -> Keep Active (status=paused)
-
-## handleAdapt
-
-Capability gap reported mid-pipeline.
-
-1. Parse gap description
-2. Check if existing role covers it -> redirect
-3. Role count < 6 -> generate dynamic role-spec in <session>/role-specs/
-4. Add new task entry to tasks.json, spawn worker
-5. Role count >= 6 -> merge or pause
-
-## Fast-Advance Reconciliation
-
-On every coordinator wake:
-1. Read team_msg entries with type="fast_advance"
-2. Sync active_workers with spawned successors
-3. No duplicate spawns
-
-## Phase 4: State Persistence
-
-After every handler execution:
-1. Reconcile active_workers with actual tasks.json states
-2. Remove entries for completed/deleted tasks
-3. Write updated meta.json
-4. STOP (wait for next callback)
-
-## Error Handling
-
-| Scenario | Resolution |
-|----------|------------|
-| Session file not found | Error, suggest re-initialization |
-| Worker callback from unknown role | Log info, scan for other completions |
-| Pipeline stall (no ready, no running, has pending) | Check blockedBy chains, report to user |
-| GC loop exceeded | Accept current coverage with warning, proceed |
-| Scout finds 0 issues | Skip to testing mode, proceed to QASTRAT |
+# Monitor Pipeline
+
+Event-driven pipeline coordination. Beat model: coordinator wake -> process -> spawn -> STOP.
+
+## Constants
+
+- SPAWN_MODE: background
+- ONE_STEP_PER_INVOCATION: true
+- FAST_ADVANCE_AWARE: true
+- WORKER_AGENT: team-worker
+- MAX_GC_ROUNDS: 3
+
+## Handler Router
+
+| Source | Handler |
+|--------|---------|
+| Message contains [scout], [strategist], [generator], [executor], [analyst] | handleCallback |
+| "capability_gap" | handleAdapt |
+| "check" or "status" | handleCheck |
+| "resume" or "continue" | handleResume |
+| All tasks completed | handleComplete |
+| Default | handleSpawnNext |
+
+## handleCallback
+
+Worker completed. Process and advance.
+
+1. Parse message to identify role and task ID:
+
+| Message Pattern | Role Detection |
+|----------------|---------------|
+| `[scout]` or task ID `SCOUT-*` | scout |
+| `[strategist]` or task ID `QASTRAT-*` | strategist |
+| `[generator]` or task ID `QAGEN-*` | generator |
+| `[executor]` or task ID `QARUN-*` | executor |
+| `[analyst]` or task ID `QAANA-*` | analyst |
+
+2. Check if progress update (inner loop) or final completion
+3. Progress -> update session state, STOP
+4. Completion -> mark task done (read `<session>/tasks.json`, set status to "completed", write back), remove from active_workers
+5. Check for checkpoints:
+   - QARUN-* completes -> read meta.json for coverage:
+     - coverage >= target OR gc_rounds >= MAX_GC_ROUNDS -> proceed to handleSpawnNext
+     - coverage < target AND gc_rounds < MAX_GC_ROUNDS -> create GC fix tasks, increment gc_rounds
+
+**GC Fix Task Creation** (when coverage below target) -- add new entries to `<session>/tasks.json`:
+```json
+{
+  "id": "QAGEN-fix-<round>",
+  "subject": "QAGEN-fix-<round>: Fix tests for <layer> (GC #<round>)",
+  "description": "PURPOSE: Fix failing tests and improve coverage | Success: Coverage meets target\nTASK:\n  - Load execution results and failing test details\n  - Fix broken tests and add missing coverage\nCONTEXT:\n  - Session: <session-folder>\n  - Layer: <layer>\n  - Previous results: <session>/results/run-<layer>.json\nEXPECTED: Fixed test files | Improved coverage\nCONSTRAINTS: Only modify test files | No source changes\n---\nInnerLoop: false\nRoleSpec: ~  or <project>/.codex/skills/team-quality-assurance/roles/generator/role.md",
+  "status": "pending",
+  "owner": "generator",
+  "blockedBy": []
+}
+```
+
+```json
+{
+  "id": "QARUN-gc-<round>",
+  "subject": "QARUN-gc-<round>: Re-execute <layer> (GC #<round>)",
+  "description": "PURPOSE: Re-execute tests after fixes | Success: Coverage >= target\nTASK: Execute test suite, measure coverage, report results\nCONTEXT:\n  - Session: <session-folder>\n  - Layer: <layer>\nEXPECTED: <session>/results/run-<layer>-gc-<round>.json\nCONSTRAINTS: Read-only execution\n---\nInnerLoop: false\nRoleSpec: ~  or <project>/.codex/skills/team-quality-assurance/roles/executor/role.md",
+  "status": "pending",
+  "owner": "executor",
+  "blockedBy": ["QAGEN-fix-<round>"]
+}
+```
+
+6. -> handleSpawnNext
+
+## handleCheck
+
+Read-only status report, then STOP.
+
+Output:
+```
+[coordinator] QA Pipeline Status
+[coordinator] Mode: <pipeline_mode>
+[coordinator] Progress: <done>/<total> (<pct>%)
+[coordinator] GC Rounds: <gc_rounds>/3
+
+[coordinator] Pipeline Graph:
+  SCOUT-001:   <done|run|wait> <summary>
+  QASTRAT-001: <done|run|wait> <summary>
+  QAGEN-001:   <done|run|wait> <summary>
+  QARUN-001:   <done|run|wait> <summary>
+  QAANA-001:   <done|run|wait> <summary>
+
+[coordinator] Active Workers: <list with elapsed time>
+[coordinator] Ready: <pending tasks with resolved deps>
+[coordinator] Commands: 'resume' to advance | 'check' to refresh
+```
+
+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)
+   - in_progress -> still running
+3. Some completed -> handleSpawnNext
+4. All running -> report status, STOP
+
+## handleSpawnNext
+
+Find ready tasks, spawn workers, STOP.
+
+1. Collect from `<session>/tasks.json`:
+   - completedSubjects: status = completed
+   - inProgressSubjects: status = in_progress
+   - readySubjects: status = pending AND all blockedBy in completedSubjects
+
+2. No ready + work in progress -> report waiting, STOP
+3. No ready + nothing in progress -> handleComplete
+4. Has ready -> for each:
+   a. Determine role from task prefix:
+
+| Prefix | Role | inner_loop |
+|--------|------|------------|
+| SCOUT-* | scout | false |
+| QASTRAT-* | strategist | false |
+| QAGEN-* | generator | false |
+| QARUN-* | executor | true |
+| QAANA-* | analyst | false |
+
+   b. Check if inner loop role with active worker -> skip (worker picks up next task)
+   c. Update task status to "in_progress" in tasks.json
+   d. team_msg log -> task_unblocked
+   e. Spawn team-worker:
+
+```
+spawn_agent({
+  agent_type: "team_worker",
+  task_name: taskId,  // e.g., "SCOUT-001" — enables named targeting
+  items: [{
+    description: "Spawn <role> worker for <subject>",
+    team_name: "quality-assurance",
+    name: "<role>",
+    prompt: `## Role Assignment
+role: <role>
+role_spec: ~  or <project>/.codex/skills/team-quality-assurance/roles/<role>/role.md
+session: <session-folder>
+session_id: <session-id>
+team_name: quality-assurance
+requirement: <task-description>
+inner_loop: <true|false>
+
+## Current Task
+- Task ID: <task-id>
+- Task: <subject>
+
+Read role_spec file to load Phase 2-4 domain instructions.
+Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
+  }]
+})
+```
+
+   f. Add to active_workers
+5. Update session, output summary, STOP
+6. Use `wait_agent({ targets: [<spawned-task-names>], 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: "<running-agent-task-name>",
+  items: [{ type: "text", text: `## Supplementary Context\n${upstreamFindings}` }]
+})
+// Note: send_message queues info without interrupting the agent's current work
+```
+
+Use `send_message` (not `assign_task`) for supplementary info that enriches but doesn't redirect the agent's current task.
+
+## 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
+2. If any tasks incomplete -> return to handleSpawnNext
+3. If all complete:
+   - Read final state from meta.json (quality_score, coverage, gc_rounds)
+   - Generate summary (deliverables, stats, discussions)
+4. Read session.completion_action:
+   - interactive -> request_user_input (Archive/Keep/Export)
+   - auto_archive -> Archive & Clean (status=completed, remove/archive session folder)
+   - auto_keep -> Keep Active (status=paused)
+
+## handleAdapt
+
+Capability gap reported mid-pipeline.
+
+1. Parse gap description
+2. Check if existing role covers it -> redirect
+3. Role count < 6 -> generate dynamic role-spec in <session>/role-specs/
+4. Add new task entry to tasks.json, spawn worker
+5. Role count >= 6 -> merge or pause
+
+## Fast-Advance Reconciliation
+
+On every coordinator wake:
+1. Read team_msg entries with type="fast_advance"
+2. Sync active_workers with spawned successors
+3. No duplicate spawns
+
+## Phase 4: State Persistence
+
+After every handler execution:
+1. Reconcile active_workers with actual tasks.json states
+2. Remove entries for completed/deleted tasks
+3. Write updated meta.json
+4. STOP (wait for next callback)
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Session file not found | Error, suggest re-initialization |
+| Worker callback from unknown role | Log info, scan for other completions |
+| Pipeline stall (no ready, no running, has pending) | Check blockedBy chains, report to user |
+| GC loop exceeded | Accept current coverage with warning, proceed |
+| Scout finds 0 issues | Skip to testing mode, proceed to QASTRAT |