maestro-flow 0.2.1 → 0.3.0

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

@@ -4,8 +4,8 @@ Synchronous pipeline coordination using spawn_agent + wait_agent.
 
 ## Constants
 
-- WORKER_AGENT: tlv4_worker
-- SUPERVISOR_AGENT: tlv4_supervisor (resident, woken via assign_task)
+- WORKER_AGENT: team_worker
+- SUPERVISOR_AGENT: team_supervisor (resident, woken via followup_task)
 
 ## Handler Router
 
@@ -19,20 +19,58 @@ Synchronous pipeline coordination using spawn_agent + wait_agent.
 
 ## handleCheck
 
-Read-only status report from tasks.json, then STOP.
+Read-only status report from tasks.json + team_msg progress, then STOP.
 
 1. Read tasks.json
 2. Count tasks by status (pending, in_progress, completed, failed, skipped)
+3. Read worker progress from message bus:
+   ```javascript
+   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
+   })
+   // Aggregate latest milestone per task
+   const taskProgress = {}
+   for (const msg of progressMsgs.result.messages) {
+     const tid = msg.data?.task_id
+     if (tid && (!taskProgress[tid] || msg.ts > taskProgress[tid].ts)) {
+       taskProgress[tid] = { phase: msg.data.phase, pct: msg.data.progress_pct, ts: msg.ts, summary: msg.summary }
+     }
+   }
+   ```
+
+4. Output enhanced status:
 
-Output:
 ```
 [coordinator] Pipeline Status
 [coordinator] Progress: <done>/<total> (<pct>%)
-[coordinator] Active agents: <list from active_agents>
-[coordinator] Ready: <pending tasks with resolved deps>
+[coordinator]
+[coordinator] Active Workers:
+[coordinator]   <task_id>  <role>  <milestone_phase>  <pct>%  "<summary>"  <time_ago>
+[coordinator]   ...
+[coordinator]
+[coordinator] Blockers: <count> (or "none")
+[coordinator]   <task_id>: <blocker_detail>    ← only if blockers exist
+[coordinator]
+[coordinator] Completed: <list>
+[coordinator] Ready: <pending with resolved deps>
 [coordinator] Commands: 'resume' to advance | 'check' to refresh
 ```
 
+**CLI equivalent for human monitoring** (no coordinator needed):
+```bash
+maestro msg list -s "<session_id>" --type progress --last 10
+maestro msg list -s "<session_id>" --type blocker
+```
+
 ## handleResume
 
 **Agent Health Check** (v4):
@@ -49,7 +87,7 @@ const runningAgents = list_agents({})
 2. No active agents -> handleSpawnNext
 3. Has active agents -> check each:
    - If supervisor with `resident: true` + no CHECKPOINT in_progress + pending CHECKPOINT exists
-     -> supervisor may have crashed. Respawn via spawn_agent({ agent_type: "tlv4_supervisor" }) with recovery: true
+     -> supervisor may have crashed. Respawn via spawn_agent({ agent_type: "team_supervisor" }) with recovery: true
 4. Proceed to handleSpawnNext
 
 ## handleSpawnNext
@@ -72,28 +110,34 @@ state.tasks[task.id].status = 'in_progress'
 
 // 2) Spawn worker
 const agentId = spawn_agent({
-  agent_type: "tlv4_worker",
+  agent_type: "team_worker",
   task_name: task.id,  // e.g., "PLAN-001" — enables named targeting
-  items: [
-    { type: "text", text: `## Role Assignment
+  message: `## Role Assignment
 role: ${task.role}
 role_spec: ${skillRoot}/roles/${task.role}/role.md
 session: ${sessionFolder}
 session_id: ${sessionId}
 requirement: ${requirement}
-inner_loop: ${hasInnerLoop(task.role)}` },
+inner_loop: ${hasInnerLoop(task.role)}
 
-    { type: "text", text: `Read role_spec file (${skillRoot}/roles/${task.role}/role.md) to load Phase 2-4 domain instructions.
-Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).` },
+Read role_spec file (${skillRoot}/roles/${task.role}/role.md) to load Phase 2-4 domain instructions.
+Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).
 
-    { type: "text", text: `## Task Context
+## Task Context
 task_id: ${task.id}
 title: ${task.title}
 description: ${task.description}
-pipeline_phase: ${task.pipeline_phase}` },
+pipeline_phase: ${task.pipeline_phase}
+
+## Upstream Context
+${prevContext}
 
-    { type: "text", text: `## Upstream Context\n${prevContext}` }
-  ]
+## Progress Milestones
+session_id: ${sessionId}
+Report progress via team_msg at natural phase boundaries (context loaded → core work done → verification).
+Report blockers immediately via team_msg type="blocker".
+Report completion via team_msg type="task_complete" after report_agent_job_result.
+See agent-instruction.md "Progress Milestone Protocol" for format.`
 })
 
 // 3) Track agent
@@ -107,10 +151,35 @@ After spawning all ready regular tasks:
 const taskNames = Object.entries(state.active_agents)
   .filter(([_, a]) => !a.resident)
   .map(([taskId]) => taskId)
-const waitResult = wait_agent({ targets: taskNames, timeout_ms: 900000 })
+const waitResult = wait_agent({ timeout_ms: 900000 })
+// 4a) Drain progress from message bus (before collecting discoveries)
+const progressMsgs = mcp__maestro-tools__team_msg({
+  operation: "list", session_id: sessionId, type: "progress", last: 100
+})
+const blockerMsgs = mcp__maestro-tools__team_msg({
+  operation: "list", session_id: sessionId, type: "blocker", last: 20
+})
+// Log execution trace
+for (const msg of (progressMsgs.result?.messages || [])) {
+  console.log(`[coordinator] trace: ${msg.summary}`)
+}
+if (blockerMsgs.result?.messages?.length > 0) {
+  console.log(`[coordinator] WARNING: ${blockerMsgs.result.messages.length} blocker(s) reported during execution`)
+  for (const b of blockerMsgs.result.messages) {
+    console.log(`[coordinator]   ${b.data?.task_id}: ${b.data?.blocker_detail}`)
+  }
+}
+
 if (waitResult.timed_out) {
+  // Use progress trace to understand where workers got stuck
   for (const taskId of taskNames) {
+    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_agents[taskId]
   }
@@ -142,12 +211,12 @@ When spawning workers in a later pipeline phase, send upstream results as supple
 // Example: Send planning results to running implementers
 send_message({
   target: "<running-agent-task-name>",
-  items: [{ type: "text", text: `## Supplementary Context\n${upstreamFindings}` }]
+  message: `## 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.
+Use `send_message` (not `followup_task`) for supplementary info that enriches but doesn't redirect the agent's current task.
 
 ### Handle CHECKPOINT Tasks
 
@@ -158,16 +227,14 @@ For each ready CHECKPOINT task:
 2. Determine scope: list task IDs that this checkpoint depends on (its deps)
 3. Wake supervisor:
    ```javascript
-   assign_task({
-     id: supervisorId,
-     items: [
-       { type: "text", text: `## Checkpoint Request
+   followup_task({
+     target: supervisorId,
+     message: `## Checkpoint Request
    task_id: ${task.id}
    scope: [${task.deps.join(', ')}]
-   pipeline_progress: ${completedCount}/${totalCount} tasks completed` }
-     ]
+   pipeline_progress: ${completedCount}/${totalCount} tasks completed`
    })
-   const cpResult = wait_agent({ targets: [supervisorId], timeout_ms: 300000 })
+   const cpResult = wait_agent({ timeout_ms: 600000 })
    if (cpResult.timed_out) { /* mark checkpoint timed_out, close supervisor, STOP */ }
    ```
 4. Read checkpoint report from artifacts/${task.id}-report.md

package/.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_message` / `assign_task` calls
+- `spawn_agent` / `wait_agent` / `close_agent` / `send_message` / `followup_task` calls
 - Status reports to the user
 - `request_user_input` prompts
 
@@ -32,20 +32,20 @@ WRONG: Bash("npm test"), Bash("tsc"), etc.           — worker work
 
 ### MUST
 - Parse task description (text-level only, no codebase reading)
-- Create session folder and spawn tlv4_worker agents via spawn_agent
+- Create session folder and spawn team_worker agents via spawn_agent
 - Dispatch tasks with proper dependency chains (tasks.json)
 - Monitor progress via wait_agent and process results
 - 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 `send_message` for supplementary context (non-interrupting) and `followup_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)
 - Execute task work directly (even for single-role low-complexity tasks)
 - Modify task output artifacts
-- Spawn workers with general-purpose agent (MUST use tlv4_worker)
+- Spawn workers with general-purpose agent (MUST use team_worker)
 - Generate more than 5 worker roles
 - Call CLI tools (maestro cli) — only workers use CLI
 
@@ -77,7 +77,7 @@ For check/resume/adapt/complete: load @commands/monitor.md, execute handler, STO
    a. Read tasks.json, reset in_progress -> pending
    b. Rebuild active_agents map
    c. If pipeline has CHECKPOINT tasks AND `supervision !== false`:
-      - Respawn supervisor via `spawn_agent({ agent_type: "tlv4_supervisor" })` with `recovery: true`
+      - Respawn supervisor via `spawn_agent({ agent_type: "team_supervisor" })` with `recovery: true`
       - Supervisor auto-rebuilds context from existing CHECKPOINT-*-report.md files
    d. Kick first ready task via handleSpawnNext
 4. Multiple -> request_user_input for selection
@@ -125,9 +125,8 @@ TEXT-LEVEL ONLY. No source code reading.
    - Use SKILL.md Supervisor Spawn Template:
      ```javascript
      const supervisorId = spawn_agent({
-       agent_type: "tlv4_supervisor",
-       items: [
-         { type: "text", text: `## Role Assignment
+       agent_type: "team_supervisor",
+       message: `## Role Assignment
      role: supervisor
      role_spec: ${skillRoot}/roles/supervisor/role.md
      session: ${sessionFolder}
@@ -135,8 +134,7 @@ TEXT-LEVEL ONLY. No source code reading.
      requirement: ${requirement}
 
      Read role_spec file to load checkpoint definitions.
-     Init: load baseline context, report ready, go idle.` }
-       ]
+     Init: load baseline context, report ready, go idle.`
      })
      ```
    - Record supervisorId in tasks.json active_agents with `resident: true` flag
@@ -155,7 +153,7 @@ Delegate to @commands/dispatch.md:
 
 Delegate to @commands/monitor.md#handleSpawnNext:
 1. Find ready tasks (pending + deps resolved)
-2. Spawn tlv4_worker agents via spawn_agent
+2. Spawn team_worker agents via spawn_agent
 3. Wait for completion via wait_agent
 4. Process results, advance pipeline
 5. Repeat until all waves complete or pipeline blocked
@@ -172,11 +170,11 @@ Delegate to @commands/monitor.md#handleSpawnNext:
 
 ### 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.
+- **followup_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: "<task-id>"` can be addressed by name in send_message, assign_task, and close_agent calls.
+- **Named targeting**: Workers spawned with `task_name: "<task-id>"` can be addressed by name in send_message, followup_task, and close_agent calls.
 
 ## Error Handling
 
@@ -185,6 +183,6 @@ Delegate to @commands/monitor.md#handleSpawnNext:
 | Task too vague | request_user_input for clarification |
 | Session corruption | Attempt recovery, fallback to manual |
 | Worker crash | Reset task to pending in tasks.json, respawn via spawn_agent |
-| Supervisor crash | Respawn via spawn_agent({ agent_type: "tlv4_supervisor" }) with recovery: true |
+| Supervisor crash | Respawn via spawn_agent({ agent_type: "team_supervisor" }) with recovery: true |
 | Dependency cycle | Detect in analysis, halt |
 | Role limit exceeded | Merge overlapping roles |

package/.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 `assign_task` at each checkpoint trigger (not SendMessage)
+- Residency: Spawned once, awakened via `followup_task` at each checkpoint trigger (not SendMessage)
 
 ## Boundaries
 

package/.codex/skills/team-lifecycle-v4/specs/knowledge-transfer.md

@@ -9,6 +9,8 @@
 | Wisdom | Append to `<session>/wisdom/*.md` | Any role | All roles |
 | Context Accumulator | In-memory aggregation | Inner loop only | Current task |
 | Exploration Cache | `<session>/explorations/` | Analyst / researcher | All roles |
+| **Progress Milestones** | `team_msg` type=progress/blocker/task_complete | Worker (all roles) | Coordinator + Human (CLI) |
+| **Cross-Worker Handoff** | `send_message` from coordinator to running worker | Coordinator | Running worker |
 
 ## 2. Context Loading Protocol (Before Task Execution)
 
@@ -126,7 +128,73 @@ Prevents redundant research across tasks.
 - Cache entries never expire within a session
 - Any role can read cached explorations; only the creator updates them
 
-## 6. Platform Mapping Reference
+## 6. Progress Milestone Protocol
+
+Workers report progress during execution via `team_msg`. This provides:
+- **Human CLI monitoring**: `maestro msg list -s <session-id> --type progress` works while coordinator is blocked in `wait_agent`
+- **Coordinator post-wait trace**: Full execution history for forensics and status display
+- **Blocker awareness**: Coordinator knows where worker got stuck on timeout
+
+### Message Types
+
+| Type | When | Purpose |
+|------|------|---------|
+| `progress` | At natural phase boundaries | Report milestone reached + progress % |
+| `blocker` | Immediately on error | Report blocking issue without waiting |
+| `task_complete` | After `report_agent_job_result` | Final status for coordinator trace |
+
+### Progress Message Schema
+
+```javascript
+mcp__maestro-tools__team_msg({
+  operation: "log",
+  session_id: "<session_id>",
+  from: "<task_id>",           // e.g., "IMPL-001"
+  to: "coordinator",
+  type: "progress",            // or "blocker" or "task_complete"
+  summary: "[<task_id>] <phase description> (<pct>%)",
+  data: {
+    task_id: "<task_id>",
+    role: "<role>",
+    status: "in_progress",     // in_progress | blocked | completed
+    progress_pct: 0-100,
+    phase: "<what just completed>",
+    key_info: "<most important finding>"
+  }
+})
+```
+
+### Timing Constraint
+
+`wait_agent` is **blocking** — coordinator cannot read team_msg during wait. Progress is only consumed:
+1. On `handleCheck` (user types "check" while coordinator is idle)
+2. On `handleResume` after `wait_agent` returns (drain bus before collecting discoveries)
+3. By human via `maestro msg list` CLI (works anytime, independent of coordinator)
+
+### Relationship to Discoveries
+
+- **Progress milestones** = lightweight trace during execution (via team_msg)
+- **Discovery files** = authoritative final output (via `discoveries/{task_id}.json`)
+- If team_msg fails, worker continues — discovery file is ground truth
+- Coordinator always reads both: team_msg for trace, discoveries for results
+
+## 7. Cross-Worker Handoff Protocol
+
+When worker A completes and worker B is still running, coordinator pushes A's findings to B via `send_message`:
+
+```javascript
+// In handleSpawnNext, after collecting A's discovery:
+send_message({
+  target: "IMPL-002",        // B's task_name
+  message: `## Supplementary Context from IMPL-001\n${findingsFromA}`
+})
+// Note: send_message queues info without interrupting B's current work
+```
+
+**When to send**: After each wave of discoveries is collected, if any running worker could benefit from the new findings.
+**What to send**: Key findings and decisions from completed tasks, especially those listed in `context_from` deps.
+
+## 8. Platform Mapping Reference
 
 | Claude Code Operation | Codex Equivalent |
 |----------------------|------------------|

package/.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_message(*), assign_task(*), close_agent(*), list_agents(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*)
+allowed-tools: spawn_agent(*), wait_agent(*), send_message(*), followup_task(*), close_agent(*), list_agents(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__maestro-tools__team_msg(*)
 ---
 
 # Team Quality Assurance
@@ -55,7 +55,7 @@ Before calling ANY tool, apply this check:
 
 | Tool Call | Verdict | Reason |
 |-----------|---------|--------|
-| `spawn_agent`, `wait_agent`, `close_agent`, `send_message`, `assign_task` | ALLOWED | Orchestration |
+| `spawn_agent`, `wait_agent`, `close_agent`, `send_message`, `followup_task` | ALLOWED | Orchestration |
 | `list_agents` | ALLOWED | Agent health check |
 | `request_user_input` | ALLOWED | User interaction |
 | `mcp__maestro-tools__team_msg` | ALLOWED | Message bus |
@@ -88,9 +88,8 @@ Coordinator spawns workers using this template:
 spawn_agent({
   agent_type: "team_worker",
   task_name: "<task-id>",
-  fork_context: false,
-  items: [
-    { type: "text", text: `## Role Assignment
+  fork_turns: "none",
+  message: `## Role Assignment
 role: <role>
 role_spec: <skill_root>/roles/<role>/role.md
 session: <session-folder>
@@ -98,21 +97,20 @@ 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.` },
+Read role_spec file (<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.
 
-    { type: "text", text: `## Task Context
+## Task Context
 task_id: <task-id>
 title: <task-title>
 description: <task-description>
-pipeline_phase: <pipeline-phase>` },
+pipeline_phase: <pipeline-phase>
 
-    { type: "text", text: `## Upstream Context
-<prev_context>` }
-  ]
+## Upstream Context
+<prev_context>`
 })
 ```
 
-After spawning, use `wait_agent({ targets: [...], timeout_ms: 900000 })` to collect results, then `close_agent({ target })` each worker.
+After spawning, use `wait_agent({ timeout_ms: 900000 })` to collect results, then `close_agent({ target })` each worker.
 
 
 ### Model Selection Guide
@@ -130,10 +128,10 @@ Override model/reasoning_effort in spawn_agent when cost optimization is needed:
 spawn_agent({
   agent_type: "team_worker",
   task_name: "<task-id>",
-  fork_context: false,
+  fork_turns: "none",
   model: "<model-override>",
   reasoning_effort: "<effort-level>",
-  items: [...]
+  message: "..."
 })
 ```
 
@@ -154,7 +152,7 @@ spawn_agent({
 | 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 |
+| Not used in this skill | `followup_task` | No resident agents -- all workers are one-shot |
 | Check running agents | `list_agents` | Verify agent health during resume |
 
 ### Pipeline Pattern
@@ -175,7 +173,7 @@ const running = list_agents({})
 ### Named Agent Targeting
 
 Workers are spawned with `task_name: "<task-id>"` enabling direct addressing:
-- `send_message({ target: "QASTRAT-001", items: [...] })` -- queue scout findings to running strategist
+- `send_message({ target: "QASTRAT-001", message: "..." })` -- queue scout findings to running strategist
 - `close_agent({ target: "SCOUT-001" })` -- cleanup by name after completion
 
 ## Completion Action

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

@@ -72,6 +72,16 @@ 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
+})
+```
+
 Output:
 ```
 [coordinator] QA Pipeline Status
@@ -86,9 +96,18 @@ Output:
   QARUN-001:   <done|run|wait> <summary>
   QAANA-001:   <done|run|wait> <summary>
 
-[coordinator] Active Workers: <list with elapsed time>
+[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] Ready: <pending tasks with resolved deps>
 [coordinator] Commands: 'resume' to advance | 'check' to refresh
+
+**CLI monitoring** (works while coordinator is blocked):
+maestro msg list -s "<session_id>" --type progress --last 10
 ```
 
 Then STOP.
@@ -143,11 +162,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 <role> worker for <subject>",
-    team_name: "quality-assurance",
-    name: "<role>",
-    prompt: `## Role Assignment
+  message: `## Role Assignment
 role: <role>
 role_spec: ~  or <project>/.codex/skills/team-quality-assurance/roles/<role>/role.md
 session: <session-folder>
@@ -161,14 +176,48 @@ inner_loop: <true|false>
 - 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).`
-  }]
+Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in 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.`
 })
 ```
 
    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.
+6. Use `wait_agent({ timeout_ms: 900000 })` to wait for callbacks. 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)) {
+    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 {
+  // Collect results, mark completed, close agents
+}
+```
 
 **Cross-Agent Supplementary Context** (v4):
 
@@ -178,12 +227,12 @@ When spawning workers in a later pipeline phase, send upstream results as supple
 // Example: Send scout results to running strategist
 send_message({
   target: "<running-agent-task-name>",
-  items: [{ type: "text", text: `## Supplementary Context\n${upstreamFindings}` }]
+  message: `## 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.
+Use `send_message` (not `followup_task`) for supplementary info that enriches but doesn't redirect the agent's current task.
 
 ## handleComplete
 

package/.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_message` / `assign_task` calls
+- `spawn_agent` / `wait_agent` / `close_agent` / `send_message` / `followup_task` calls
 - Status reports to the user / `request_user_input` prompts
 
 **FORBIDDEN** (even if the task seems trivial):
@@ -36,7 +36,7 @@ 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 `send_message` for supplementary context (non-interrupting) and `followup_task` for triggering new work
 - Use `list_agents` for session resume health checks and cleanup verification
 
 ### MUST NOT
@@ -157,11 +157,11 @@ Delegate to @commands/monitor.md#handleSpawnNext:
 
 ### 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.
+- **followup_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: "<task-id>"` can be addressed by name in send_message, assign_task, and close_agent calls.
+- **Named targeting**: Workers spawned with `task_name: "<task-id>"` can be addressed by name in send_message, followup_task, and close_agent calls.
 
 ## Error Handling