maestro-flow 0.3.14 → 0.3.16

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

@@ -43,28 +43,9 @@ Worker completed. Process and advance.
      - 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>"]
-}
-```
+**GC Fix Task Creation** (when coverage below target) -- add paired tasks to `<session>/tasks.json`:
+- `QAGEN-fix-<round>` (owner: generator) -- fix failing tests and improve coverage using previous results
+- `QARUN-gc-<round>` (owner: executor, blockedBy: [QAGEN-fix-<round>]) -- re-execute tests after fixes, measure coverage
 
 6. -> handleSpawnNext
 
@@ -72,78 +53,51 @@ Worker completed. Process and advance.
 
 Read-only status report, then STOP.
 
-```javascript
-// Read progress and blocker messages from message bus
-const progressMsgs = mcp__maestro-tools__team_msg({
-  operation: "list", session_id: sessionId, type: "progress", last: 50
-})
-const blockerMsgs = mcp__maestro-tools__team_msg({
-  operation: "list", session_id: sessionId, type: "blocker", last: 10
-})
-```
+Read team_msg (type="progress", last=50) + team_msg (type="blocker", last=10). Aggregate per-worker milestones.
 
-Output:
+**Output format**:
 ```
-[coordinator] QA Pipeline Status
-[coordinator] Mode: <pipeline_mode>
-[coordinator] Progress: <done>/<total> (<pct>%)
+[coordinator] QA Pipeline Status — Mode: <pipeline_mode> — 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:
-  <task_id>  <role>  <milestone_phase>  <pct>%  "<summary>"  <time_ago>
-
-[coordinator] Blockers:
-  <task_id>  <role>  "<blocker_summary>"  <time_ago>
-  (omit section if no blockers)
-
+[coordinator] Pipeline Graph: <task_id>: <done|run|wait> <summary> (per task)
+[coordinator] Active Workers: <task_id> <role> <milestone_phase> <pct>% "<summary>" <time_ago>
+[coordinator] Blockers: <task_id> <role> "<blocker_summary>" <time_ago> (omit if none)
 [coordinator] Ready: <pending tasks with resolved deps>
 [coordinator] Commands: 'resume' to advance | 'check' to refresh
-
-**CLI monitoring** (works while coordinator is blocked):
-maestro agent-msg list -s "<session_id>" --type progress --last 10
 ```
 
+**CLI monitoring**: `maestro agent-msg list -s "<session_id>" --type progress --last 10`
+
 Then STOP.
 
 ## handleResume
 
-**Agent Health Check** (v4):
+**Agent Health Check** (v4): Cross-check `list_agents()` against active_workers. Missing agents -> reset task to pending.
+
 ```
-// 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 -> route:
+  none -> handleSpawnNext
+  has workers -> classify each: completed | in_progress
+    some completed -> handleSpawnNext
+    all running -> report status -> STOP
 ```
 
-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:
+```
+Classify tasks: completed | in_progress | ready (pending + all blockedBy completed)
+
+Ready tasks -> route:
+  none + in_progress exists -> report waiting, STOP
+  none + nothing in_progress -> handleComplete
+  has ready -> for each:
+    determine role from prefix (see prefix-role map below)
+    skip if inner loop role already has active worker
+    else: set status="in_progress", log task_unblocked, spawn team_worker, add to active_workers
+  Update session, output summary, STOP
+```
 
 | Prefix | Role | inner_loop |
 |--------|------|------------|
@@ -153,119 +107,32 @@ Find ready tasks, spawn workers, STOP.
 | 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 worker message template**:
 ```
-spawn_agent({
-  agent_type: "team_worker",
-  task_name: taskId,  // e.g., "SCOUT-001" — enables named targeting
-  message: `## 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>
-
+## Role Assignment
+role: <role> | role_spec: <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).
-
+task_id: <task-id> | subject: <subject>
+Read role_spec for Phase 2-4 instructions. Execute Phase 1 -> role Phase 2-4 -> Phase 5 (report).
 ## Progress Milestones
-session_id: ${sessionId}
-Report progress via team_msg at natural phase boundaries.
-Report blockers immediately via team_msg type="blocker".
-Report completion via team_msg type="task_complete" after report_agent_job_result.`
-})
+Report progress via team_msg at phase boundaries. Blockers via type="blocker". Completion via type="task_complete" after report_agent_job_result.
 ```
 
-   f. Add to active_workers
-5. Update session, output summary, STOP
-6. Use `wait_agent({ timeout_ms: 1800000 })` to wait for callbacks (30 min). If `result.timed_out`, send STATUS_CHECK via followup_task (wait 3 min), then FINALIZE with interrupt (wait 3 min), then mark timed_out and close agents. Workers use `report_agent_job_result()` to send results back.
-
-### Post-Wait Processing
-
-After `wait_agent` returns:
-
-```javascript
-// Drain progress from message bus
-const progressMsgs = mcp__maestro-tools__team_msg({
-  operation: "list", session_id: sessionId, type: "progress", last: 100
-})
-for (const msg of (progressMsgs.result?.messages || [])) {
-  console.log(`[coordinator] trace: ${msg.summary}`)
-}
-
-if (waitResult.timed_out) {
-  for (const taskId of Object.keys(state.active_workers)) {
-    // Status probe before closing
-    followup_task({ target: taskId, message: "STATUS_CHECK: Report current progress, findings so far, and estimated remaining work." })
-    const status = wait_agent({ timeout_ms: 180000 })  // 3 min
-    if (status.timed_out) {
-      followup_task({ target: taskId, message: "FINALIZE: Output all current findings immediately. Time limit reached.", interrupt: true })
-      const forced = wait_agent({ timeout_ms: 180000 })  // 3 min
-      if (forced.timed_out) {
-        const lastProgress = (progressMsgs.result?.messages || [])
-          .filter(m => m.data?.task_id === taskId).pop()
-        state.tasks[taskId].status = 'timed_out'
-        state.tasks[taskId].error = lastProgress
-          ? `Timed out at ${lastProgress.data.phase} (${lastProgress.data.progress_pct}%)`
-          : 'Timed out with no progress reported'
-        close_agent({ target: taskId })
-        delete state.active_workers[taskId]
-      }
-      // else: forced output received, process result
-    }
-    // else: status received, continue processing
-  }
-} else {
-  // Collect results, mark completed, close agents
-}
-```
+**Result collection**: `wait_agent({ timeout_ms: 1800000 })` (30 min), drain progress from team_msg.
 
-**Cross-Agent Supplementary Context** (v4):
+**Timeout escalation**: STATUS_CHECK (3 min) -> FINALIZE with interrupt (3 min) -> mark timed_out with last progress context, close_agent.
 
-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>",
-  message: `## Supplementary Context\n${upstreamFindings}`
-})
-// Note: send_message queues info without interrupting the agent's current work
-```
-
-Use `send_message` (not `followup_task`) for supplementary info that enriches but doesn't redirect the agent's current task.
+**Cross-Agent Supplementary Context** (v4): Use `send_message` (not `followup_task`) to deliver upstream results to running downstream workers as non-interrupting supplementary context.
 
 ## 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
-```
+**Cleanup Verification** (v4): `list_agents()` -> close any still-running team agents.
 
-Pipeline done. Generate report and completion action.
+Pipeline done. Verify all tasks (including GC fix/recheck) completed/deleted. Incomplete -> handleSpawnNext. All complete -> read meta.json (quality_score, coverage, gc_rounds), generate summary.
 
-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)
+Route by completion_action: interactive (Archive/Keep/Export) | auto_archive | auto_keep.
 
 ## handleAdapt
 
@@ -279,18 +146,11 @@ Capability gap reported mid-pipeline.
 
 ## 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
+On every wake: sync `fast_advance` messages from team_msg into active_workers. 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)
+After every handler: reconcile active_workers with tasks.json, remove completed/deleted entries, write meta.json, STOP.
 
 ## Error Handling
 

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

@@ -77,55 +77,17 @@ Before calling ANY tool, apply this check:
 
 ### Worker Spawn Template
 
-Coordinator spawns workers using this template:
-
-```
-spawn_agent({
-  agent_type: "team_worker",
-  task_name: "<task-id>",
-  fork_turns: "none",
-  message: `## Role Assignment
-role: <role>
-role_spec: <skill_root>/roles/<role>/role.md
-session: <session-folder>
-session_id: <session-id>
-requirement: <task-description>
-inner_loop: <true|false>
-
-Read role_spec file (<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.
-
-## Task Context
-task_id: <task-id>
-title: <task-title>
-description: <task-description>
-pipeline_phase: <pipeline-phase>
-
-## Upstream Context
-<prev_context>`
-})
-```
-
-After spawning, use `wait_agent({ timeout_ms: 1800000 })` to collect results (30 min). If `result.timed_out`, send STATUS_CHECK via followup_task (wait 3 min), then FINALIZE with interrupt (wait 3 min), then mark timed_out and close agents. Use `close_agent({ target })` each worker.
+Spawn via `team-worker` agent. Message includes: role, role_spec path, session folder/id, requirement, inner_loop flag, task context, upstream context. After spawning: `wait_agent` (30 min). Timeout: STATUS_CHECK (3 min) -> FINALIZE (3 min) -> close.
 
 ### 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 |
+| Role | reasoning_effort |
+|------|-------------------|
+| Scanner (SCAN-*) | medium |
+| Reviewer (REV-*) | high |
+| Fixer (FIX-*) | high |
 
-Override model/reasoning_effort in spawn_agent when cost optimization is needed:
-```
-spawn_agent({
-  agent_type: "team_worker",
-  task_name: "<task-id>",
-  fork_turns: "none",
-  model: "<model-override>",
-  reasoning_effort: "<effort-level>",
-  message: "..."
-})
-```
+Override via `model`/`reasoning_effort` params in spawn_agent for cost optimization.
 
 ### User Commands
 
@@ -141,53 +103,17 @@ spawn_agent({
 
 ### 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 | `followup_task` | No resident agents -- sequential 3-stage pipeline |
-| Check running agents | `list_agents` | Verify agent health during resume |
-
-#### Pipeline Pattern
+**Message Semantics**: `send_message` to queue scan findings to reviewer. `list_agents` for health checks. `followup_task` not used (sequential pipeline).
 
-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).
+**Pipeline Pattern**: Sequential 3-stage (scan -> review -> fix). May skip stages: 0 findings skips review+fix; user declines fix skips fix.
 
-#### Agent Health Check
+**Agent Health Check**: Reconcile `tasks.json` with `list_agents({})`. Reset orphaned tasks to pending.
 
-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: "<task-id>"` enabling direct addressing:
-- `send_message({ target: "REV-001", message: "..." })` -- queue scan findings to running reviewer
-- `close_agent({ target: "SCAN-001" })` -- cleanup by name after completion
+**Named Targeting**: `send_message({ target: "REV-001" })`, `close_agent({ target: "SCAN-001" })`.
 
 ### Completion Action
 
-When pipeline completes, coordinator presents:
-
-```
-request_user_input({
-  questions: [{
-    question: "Review pipeline complete. What would you like to do?",
-    header: "Completion",
-    multiSelect: false,
-    options: [
-      { label: "Archive & Clean (Recommended)", description: "Archive session, clean up" },
-      { label: "Keep Active", description: "Keep session for follow-up work" },
-      { label: "Export Results", description: "Export deliverables to target directory" }
-    ]
-  }]
-})
-```
+Present choice: **Archive & Clean** (recommended), **Keep Active**, **Export Results**.
 
 ### Session Directory