maestro-flow 0.2.0 → 0.2.2

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

@@ -88,7 +88,19 @@ Receive result from wait_agent for [<role>]
 
 ### Handler: handleCheck
 
-Read-only status report. No pipeline advancement.
+Read-only status report with progress milestones. No pipeline advancement.
+
+1. Read tasks.json for pipeline state
+2. 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
+   })
+   ```
+3. Aggregate latest milestone per active worker
 
 **Output format**:
 
@@ -102,12 +114,22 @@ Read-only status report. No pipeline advancement.
   done=completed  >>>=running  o=pending  .=not created
 
 [coordinator] Active Workers:
-  > <subject> (<role>) - running <elapsed> [inner-loop: N/M tasks done]
+  > <subject> (<role>) - <milestone_phase> <pct>% - running <elapsed>
+  ...
+
+[coordinator] Blockers: <count or "none">
+  <task_id>: <blocker_detail>    ← only if blockers exist
 
 [coordinator] Ready to spawn: <subjects>
 [coordinator] Commands: 'resume' to advance | 'check' to refresh
 ```
 
+**CLI equivalent for human monitoring** (works while coordinator is blocked):
+```bash
+maestro msg list -s "<session_id>" --type progress --last 10
+maestro msg list -s "<session_id>" --type blocker
+```
+
 Then STOP.
 
 ---
@@ -173,12 +195,12 @@ When spawning workers in a later pipeline phase, send upstream results as supple
 // Example: Send upstream task results to running downstream workers
 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.
 
 **Spawn worker call** (one per ready task):
 
@@ -186,7 +208,7 @@ Use `send_message` (not `assign_task`) for supplementary info that enriches but
 const agentId = spawn_agent({
   agent_type: "team_worker",
   task_name: taskId,  // e.g., "EXPLORE-001" — enables named targeting
-  items: [{ type: "text", text: `## Role Assignment
+  message: `## Role Assignment
 role: <role>
 role_spec: <session-folder>/role-specs/<role>.md
 session: <session-folder>
@@ -195,12 +217,33 @@ team_name: <team-name>
 requirement: <task-description>
 inner_loop: <true|false>
 
-Read role_spec file to load Phase 2-4 domain instructions.` }]
+Read role_spec file to load Phase 2-4 domain instructions.
+
+## 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.`
 })
 // Collect results — use task_name for stable targeting (v4):
-const result = wait_agent({ targets: [taskId], timeout_ms: 900000 })
+const result = wait_agent({ timeout_ms: 900000 })
+
+// Drain progress from message bus (before processing results)
+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 (result.timed_out) {
+  // Use progress trace for timeout forensics
+  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 })
   // Report timeout, STOP — let user decide retry
 } else {

package/.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({ targets: [...], timeout_ms: 900000 })     — monitoring
+OK: wait_agent({ timeout_ms: 900000 })     — monitoring
 ```
 
 **Self-check gate**: After Phase 1 analysis, before ANY other action, ask yourself:
@@ -57,7 +57,7 @@ OK: wait_agent({ targets: [...], timeout_ms: 900000 })     — 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 `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
@@ -380,11 +380,11 @@ Delegate to `@commands/dispatch.md` which creates the full task chain:
 
 ### 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
 

package/.codex/skills/team-coordinate/specs/knowledge-transfer.md

@@ -9,6 +9,8 @@
 | **Wisdom** | Cross-task | Append to `<session>/wisdom/{learnings,decisions,conventions,issues}.md` | Patterns, conventions, risks discovered during execution |
 | **Context Accumulator** | Intra-role (inner loop) | In-memory array, passed to each subsequent task in same-prefix loop | Prior task summaries within same role's inner loop |
 | **Exploration Cache** | Cross-role | `<session>/explorations/cache-index.json` + per-angle JSON | Codebase discovery results, prevents duplicate exploration |
+| **Progress Milestones** | Worker -> Coordinator | `team_msg` type=progress/blocker/task_complete | Live execution trace, blocker alerts, timeout forensics |
+| **Cross-Worker Handoff** | Coordinator -> Worker | `send_message` to running worker with upstream findings | Push new context to running workers when dependencies complete |
 
 ## 2. Context Loading Protocol (Phase 2)
 

package/.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_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 Executor
@@ -110,9 +110,8 @@ When executor spawns workers, use `team-worker` agent with role-spec path:
 spawn_agent({
   agent_type: "team_worker",
   task_name: "<task-id>",
-  fork_context: false,
-  items: [
-    { type: "text", text: `## Role Assignment
+  fork_turns: "none",
+  message: `## Role Assignment
 role: <role>
 role_spec: <session-folder>/role-specs/<role>.md
 session: <session-folder>
@@ -120,21 +119,20 @@ session_id: <session-id>
 requirement: <task-description>
 inner_loop: <true|false>
 
-Read role_spec file to load Phase 2-4 domain instructions.` },
+Read role_spec file 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: <name> })` each worker.
+After spawning, use `wait_agent({ timeout_ms: 900000 })` to collect results, then `close_agent({ target: <name> })` each worker.
 
 ---
 
@@ -159,8 +157,8 @@ const running = list_agents({})
 
 ### Worker Communication
 
-- `send_message({ target: "<task-id>", items: [...] })` -- queue supplementary context
-- `assign_task({ target: "<task-id>", items: [...] })` -- assign new work to inner_loop worker
+- `send_message({ target: "<task-id>", message: "..." })` -- queue supplementary context
+- `followup_task({ target: "<task-id>", message: "..." })` -- assign new work to inner_loop worker
 - `close_agent({ target: "<task-id>" })` -- cleanup completed worker
 
 ## Completion Action

package/.codex/skills/team-executor/roles/executor/commands/monitor.md

@@ -67,6 +67,16 @@ Receive callback from [<role>]
 
 Read-only status report. No pipeline advancement.
 
+```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
+})
+```
+
 ```
 [executor] Pipeline Status
 [executor] Progress: <completed>/<total> (<percent>%)
@@ -76,11 +86,18 @@ Read-only status report. No pipeline advancement.
 
   done=completed  >>>=running  o=pending  .=not created
 
-[executor] Active agents:
-  > <subject> (<role>) - running <elapsed>
+[executor] Active Workers:
+  <task_id>  <role>  <milestone_phase>  <pct>%  "<summary>"  <time_ago>
+
+[executor] Blockers:
+  <task_id>  <role>  "<blocker_summary>"  <time_ago>
+  (omit section if no blockers)
 
 [executor] Ready to spawn: <subjects>
 [executor] Commands: 'resume' to advance | 'check' to refresh
+
+**CLI monitoring** (works while executor is blocked):
+maestro msg list -s "<session_id>" --type progress --last 10
 ```
 
 Then STOP.
@@ -134,25 +151,30 @@ Ready tasks found?
 ```javascript
 const agentId = spawn_agent({
   agent_type: "team_worker",
-  items: [
-    { type: "text", text: `## Role Assignment
+  message: `## Role Assignment
 role: ${task.role}
 role_spec: ${sessionFolder}/role-specs/${task.role}.md
 session: ${sessionFolder}
 session_id: ${sessionId}
 team_name: ${teamName}
 requirement: ${task.description}
-inner_loop: ${hasInnerLoop(task.role)}` },
+inner_loop: ${hasInnerLoop(task.role)}
 
-    { type: "text", text: `Read role_spec file (${sessionFolder}/role-specs/${task.role}.md) to load Phase 2-4 domain instructions.` },
+Read role_spec file (${sessionFolder}/role-specs/${task.role}.md) to load Phase 2-4 domain instructions.
 
-    { type: "text", text: `## Task Context
+## Task Context
 task_id: ${taskId}
 title: ${task.title}
-description: ${task.description}` },
+description: ${task.description}
 
-    { type: "text", text: `## Upstream Context\n${prevContext}` }
-  ]
+## Upstream Context
+${prevContext}
+
+## 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.`
 })
 
 state.active_agents[taskId] = { agentId, role: task.role, started_at: now }
@@ -167,11 +189,25 @@ After spawning all ready tasks:
 const agentIds = Object.values(state.active_agents)
   .filter(a => !a.resident)
   .map(a => a.agentId)
-const waitResult = wait_agent({ targets: agentIds, timeout_ms: 900000 })
+const waitResult = wait_agent({ timeout_ms: 900000 })
+
+// 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(`[executor] trace: ${msg.summary}`)
+}
+
 if (waitResult.timed_out) {
   for (const [taskId, agent] of Object.entries(state.active_agents)) {
     if (agent.resident) continue
+    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: agent.agentId })
     delete state.active_agents[taskId]
   }

package/.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_message(*), assign_task(*), close_agent(*), list_agents(*), report_agent_job_result(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), request_user_input(*)
+allowed-tools: spawn_agent(*), wait_agent(*), send_message(*), followup_task(*), close_agent(*), list_agents(*), report_agent_job_result(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), request_user_input(*), mcp__maestro-tools__team_msg(*)
 ---
 
 # 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            assign_task-driven
+              lifecycle            followup_task-driven
                     |                     |
                     +-- wait_agent --------+
                               |
@@ -63,7 +63,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 |
@@ -96,9 +96,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>
@@ -107,23 +106,22 @@ requirement: <task-description>
 inner_loop: <true|false>
 
 Read role_spec file (<skill_root>/roles/<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).` },
+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: <pipeline-phase>` },
+pipeline_phase: <pipeline-phase>
 
-    { type: "text", text: `## Upstream Context
-<prev_context>` }
-  ]
+## Upstream Context
+<prev_context>`
 })
 ```
 
 ## Supervisor Spawn Template
 
-Supervisor is a **resident agent** (independent from team_worker). Spawned once during session init, woken via assign_task for each CHECKPOINT task.
+Supervisor is a **resident agent** (independent from team_worker). Spawned once during session init, woken via followup_task for each CHECKPOINT task.
 
 ### Spawn (Phase 2 -- once per session)
 
@@ -131,9 +129,8 @@ Supervisor is a **resident agent** (independent from team_worker). Spawned once
 supervisorId = spawn_agent({
   agent_type: "team_supervisor",
   task_name: "supervisor",
-  fork_context: false,
-  items: [
-    { type: "text", text: `## Role Assignment
+  fork_turns: "none",
+  message: `## Role Assignment
 role: supervisor
 role_spec: <skill_root>/roles/supervisor/role.md
 session: <session-folder>
@@ -142,24 +139,21 @@ requirement: <task-description>
 
 Read role_spec file (<skill_root>/roles/supervisor/role.md) to load checkpoint definitions.
 Init: load baseline context, report ready, go idle.
-Wake cycle: orchestrator sends checkpoint requests via assign_task.` }
-  ]
+Wake cycle: orchestrator sends checkpoint requests via followup_task.`
 })
 ```
 
 ### Wake (per CHECKPOINT task)
 
 ```
-assign_task({
+followup_task({
   target: "supervisor",
-  items: [
-    { type: "text", text: `## Checkpoint Request
+  message: `## Checkpoint Request
 task_id: <CHECKPOINT-NNN>
 scope: [<upstream-task-ids>]
-pipeline_progress: <done>/<total> tasks completed` }
-  ]
+pipeline_progress: <done>/<total> tasks completed`
 })
-wait_agent({ targets: ["supervisor"], timeout_ms: 300000 })
+wait_agent({ timeout_ms: 600000 })
 ```
 
 ### Shutdown (pipeline complete)
@@ -186,10 +180,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: "..."
 })
 ```
 
@@ -201,10 +195,10 @@ For each wave in the pipeline:
 2. **Skip failed deps** -- Mark tasks whose dependencies failed/skipped as `skipped`
 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({ targets: [...], timeout_ms: 900000 })`
+5. **Spawn regular tasks** -- For each regular task, call `spawn_agent({ agent_type: "team_worker", message: "..." })`, collect agent IDs
+6. **Wait** -- `wait_agent({ 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
+8. **Execute checkpoints** -- For each CHECKPOINT task, `followup_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 `<session>/tasks.json`
 
@@ -226,11 +220,11 @@ For each wave in the pipeline:
 | 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 |
+| Wake resident supervisor for checkpoint | `followup_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.
+**CRITICAL**: The supervisor is a **resident agent** woken via `followup_task`, NOT `send_message`. Regular workers complete and are closed; the supervisor persists across checkpoints. See "Supervisor Spawn Template" above.
 
 ### Agent Health Check
 
@@ -247,8 +241,8 @@ const running = list_agents({})
 ### Named Agent Targeting
 
 Workers are spawned with `task_name: "<task-id>"` enabling direct addressing:
-- `send_message({ target: "IMPL-001", items: [...] })` -- queue planning context to running implementer
-- `assign_task({ target: "supervisor", items: [...] })` -- wake supervisor for checkpoint
+- `send_message({ target: "IMPL-001", message: "..." })` -- queue planning context to running implementer
+- `followup_task({ target: "supervisor", message: "..." })` -- wake supervisor for checkpoint
 - `close_agent({ target: "IMPL-001" })` -- cleanup regular worker by name
 - `close_agent({ target: "supervisor" })` -- shutdown supervisor at pipeline end
 

package/.codex/skills/team-lifecycle-v4/instructions/agent-instruction.md

@@ -658,6 +658,100 @@ This instruction is loaded by team-worker agents when spawned with roles: `analy
 
 ---
 
+## Progress Milestone Protocol
+
+All roles MUST report progress at milestones during task execution via `team_msg`.
+
+**Why**: Gives coordinator execution trace on resume, enables human CLI monitoring during wait, and provides blocker forensics on timeout.
+
+### Milestone Reporting
+
+When you reach a natural phase boundary (context loaded, core work done, verification complete), report:
+
+```javascript
+mcp__maestro-tools__team_msg({
+  operation: "log",
+  session_id: "<from task assignment>",
+  from: "<task_id>",        // e.g., "IMPL-001"
+  to: "coordinator",
+  type: "progress",
+  summary: "[<task_id>] <brief 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 or decision>"
+  }
+})
+```
+
+### Role-Specific Milestones
+
+| Role | Milestone 1 (~20%) | Milestone 2 (~60%) | Milestone 3 (~90%) |
+|------|--------------------|--------------------|---------------------|
+| analyst | Domain exploration started | Analysis complete | Findings documented |
+| writer | Template & upstream loaded | Draft complete | Self-reviewed |
+| planner | Specs read, codebase explored | Plan generated | Tasks validated |
+| executor | Context loaded, plan read | Core changes implemented | Build/test verified |
+| tester | Test suite identified | Tests executed | Fix iterations done |
+| reviewer | Files loaded for review | Review complete | Report written |
+
+### Blocker Reporting (Immediate)
+
+If you hit a blocker (build fails 3x, missing dependency, ambiguous requirement), report **immediately** — don't wait for next milestone:
+
+```javascript
+mcp__maestro-tools__team_msg({
+  operation: "log",
+  session_id: "<session_id>",
+  from: "<task_id>",
+  to: "coordinator",
+  type: "blocker",
+  summary: "[<task_id>] BLOCKED: <brief description>",
+  data: {
+    task_id: "<task_id>",
+    status: "blocked",
+    blocker_type: "<build_failure|missing_dep|ambiguous_req|test_failure>",
+    blocker_detail: "<specific error or issue>",
+    attempts: <N>,
+    needs: "<what would unblock>"
+  }
+})
+```
+
+After reporting, continue attempting resolution (inner loop). Don't wait for coordinator response.
+
+### Completion Report
+
+After calling `report_agent_job_result`, also log to team_msg for coordinator trace:
+
+```javascript
+mcp__maestro-tools__team_msg({
+  operation: "log",
+  session_id: "<session_id>",
+  from: "<task_id>",
+  to: "coordinator",
+  type: "task_complete",
+  summary: "[<task_id>] DONE: <brief result>",
+  data: {
+    task_id: "<task_id>",
+    status: "completed",
+    progress_pct: 100,
+    files_modified: [],
+    key_findings: [],
+    elapsed: "<estimated time>"
+  }
+})
+```
+
+### Overhead Rule
+
+Milestone reporting is **lightweight** — log and continue. Never block execution to report. If `team_msg` call fails, continue working — the discovery file is the authoritative output.
+
+---
+
 ## Inner Loop Protocol
 
 Roles with `inner_loop: true` support self-repair:

package/.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 assign_task
+- **NOT spawned as team_worker** — coordinator wakes the resident supervisor via followup_task
 - If `supervision: false` in tasks.json, skip creating CHECKPOINT tasks entirely
 - RoleSpec in description: `<project>/.codex/skills/team-lifecycle-v4/roles/supervisor/role.md`