maestro-flow 0.3.5 → 0.3.6

package/.claude/commands/maestro-brainstorm.md

@@ -22,6 +22,7 @@ Unified brainstorming combining interactive framework generation, multi-role par
 <deferred_reading>
 - [scratch-index.json](~/.maestro/templates/scratch-index.json) — read when operating in scratch mode
 - [index.json](~/.maestro/templates/index.json) — read when operating in phase mode
+- [brainstorm-visualize.md](~/.maestro/workflows/brainstorm-visualize.md) — read when html-prototypes/ produced and user wants to browse them
 </deferred_reading>
 
 <context>
@@ -54,6 +55,7 @@ Auto mode:
 - Project initialized, need spec package → Skill({ skill: "maestro-spec-generate", args: "--from-brainstorm {session_id}" })
 - Project initialized, quick roadmap → Skill({ skill: "maestro-roadmap", args: "--from-brainstorm {session_id}" })
 - Need deeper analysis first → Skill({ skill: "maestro-analyze", args: "{topic}" })
+- `html-prototypes/` produced with 2+ files and user wants to browse → load `~/.maestro/workflows/brainstorm-visualize.md` and launch visualizer server (optional, user-triggered)
 
 Single role mode:
 - More roles needed → Skill({ skill: "maestro-brainstorm", args: "{next_role} --session {session_id}" })
@@ -76,9 +78,16 @@ Single role mode:
 <success_criteria>
 **Auto mode**:
 - [ ] guidance-specification.md with RFC 2119 keywords, terminology, non-goals, feature decomposition
-- [ ] Role analysis files for each selected role in `.brainstorming/{role}/`
+- [ ] design-research.md persisted when Step 1.7 external research ran (fail-soft: absence not a failure)
+- [ ] Spec Review Gate passed (Step 3.5) or `--yes` bypassed
+- [ ] Role analysis files for each selected NON-UI role in `.brainstorming/{role}/`
+- [ ] If `ui-designer` in selected_roles: `ui-designer/analysis.md` exists AND exactly one of `html-prototypes/` / `ascii-mockups/` / `api-sketches/` exists with `README.md` + ≥1 prototype file
+- [ ] ui-designer/analysis.md references each prototype via `@-notation`
+- [ ] HTML prototypes are self-contained (no external `<link>`/`<script src>` URLs — warn only)
 - [ ] Feature specs in `.brainstorming/feature-specs/` (or synthesis-specification.md)
+- [ ] UI-bearing feature specs reference the corresponding prototype in Section 3 (Interface Contract)
 - [ ] feature-index.json and synthesis-changelog.md
+- [ ] Final Output Gate passed (Step 5.5) or `--yes` bypassed
 - [ ] All user decisions captured with Decision Recording Protocol
 - [ ] Session metadata updated with completion status
 

package/.claude/commands/maestro-milestone-audit.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-milestone-audit
 description: Audit current milestone for cross-phase integration gaps
-argument-hint: "[milestone, e.g., 'v1.0']"
+argument-hint: "[<milestone>]"
 allowed-tools:
   - Read
   - Write

package/.claude/commands/maestro-milestone-complete.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-milestone-complete
 description: Archive completed milestone and prepare for next
-argument-hint: "[milestone, e.g., 'v1.0']"
+argument-hint: "[<milestone>]"
 allowed-tools:
   - Read
   - Write
@@ -35,6 +35,7 @@ Milestone: $ARGUMENTS (optional -- defaults to current_milestone from state.json
 Follow '~/.maestro/workflows/milestone-complete.md' completely.
 
 **Next-step routing on completion:**
+- Cut a release for this milestone → Skill({ skill: "maestro-milestone-release" })
 - Next milestone has phases → Skill({ skill: "maestro-plan", args: "{next_milestone_first_phase}" })
 - Need to capture learnings → Skill({ skill: "manage-memory-capture", args: "compact" })
 - View updated project state → Skill({ skill: "manage-status" })

package/.claude/commands/maestro-milestone-release.md

@@ -0,0 +1,96 @@
+---
+name: maestro-milestone-release
+description: Version bump, changelog generation, and git tag for a completed milestone
+argument-hint: "[<version>] [--bump patch|minor|major] [--dry-run] [--no-tag] [--no-push]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+
+<purpose>
+Package a completed milestone into a releasable version. Bumps the project version (e.g. `package.json`, `pyproject.toml`, or language-specific manifest), generates or appends a changelog entry from phase/milestone summaries and git log, creates an annotated git tag, and optionally pushes to the remote. Runs after Skill({ skill: "maestro-milestone-complete" }) has archived the milestone; serves as the final delivery step in the SDLC loop.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/milestone-release.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- optional explicit version string and flags.
+
+**Flags:**
+- `<version>` -- explicit version (e.g. `1.2.0`). If omitted, version is derived from `--bump` or prompted.
+- `--bump patch|minor|major` -- semver bump relative to the current version (default: `minor`)
+- `--dry-run` -- compute the next version, changelog diff, and tag name without writing files or creating tags
+- `--no-tag` -- skip git tag creation (version bump + changelog only)
+- `--no-push` -- skip `git push --follow-tags` after tagging
+
+**State files:**
+- `.workflow/state.json` -- current_milestone, previous release version
+- `.workflow/milestones/{milestone}/summary.md` -- milestone summary (from `maestro-milestone-complete`)
+- `.workflow/milestones/{milestone}/audit-report.md` -- audit verdict (must be PASS)
+- `CHANGELOG.md` -- release notes file (created if missing)
+- Version manifest -- `package.json` / `pyproject.toml` / `Cargo.toml` / etc. (auto-detected)
+
+**Preconditions:**
+- Current milestone must be completed (audit PASS + Skill({ skill: "maestro-milestone-complete" }) run)
+- Working tree must be clean (no uncommitted changes) unless `--dry-run`
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/release.md' completely.
+
+**High-level flow:**
+1. Validate preconditions (milestone completed, clean tree, audit PASS)
+2. Resolve target version from `<version>` or `--bump` against current manifest
+3. Collect changes since last release tag: milestone summary + phase summaries + git log between tags
+4. Generate `CHANGELOG.md` entry (grouped by phase / change type)
+5. Write version to manifest file(s) + commit with message `chore(release): v{version}`
+6. Create annotated git tag `v{version}` with release notes body (unless `--no-tag`)
+7. Push commit + tag to remote (unless `--no-push`)
+
+**Report format on completion:**
+```
+=== RELEASE COMPLETE ===
+Version:   v{previous} → v{new}
+Milestone: {milestone_name}
+Tag:       v{new} {pushed|local-only}
+Changelog: {N} entries written to CHANGELOG.md
+Manifest:  {file_path} updated
+
+Next steps:
+  Skill({ skill: "maestro-plan", args: "{next_phase}" })  -- Start next milestone's first phase
+  Skill({ skill: "manage-status" })                        -- View project dashboard
+```
+
+For `--dry-run`, print the computed version, changelog diff, and tag name without side effects.
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Current milestone not completed (no milestone-complete run) | Run Skill({ skill: "maestro-milestone-complete" }) first |
+| E002 | error | Audit verdict not PASS | Re-run Skill({ skill: "maestro-milestone-audit" }) and resolve findings |
+| E003 | error | Working tree not clean (uncommitted changes) | Commit or stash changes, then retry |
+| E004 | error | Version manifest not found / unsupported | Add supported manifest or pass `<version>` explicitly with `--no-tag` |
+| E005 | error | Target version not greater than current (would break semver monotonicity) | Choose a higher version or run with explicit `<version>` |
+| W001 | warning | No changes detected since last release tag | Confirm whether release is still desired |
+| W002 | warning | Remote push failed (network / auth) | Retry manually with `git push --follow-tags` |
+</error_codes>
+
+<success_criteria>
+- [ ] Preconditions validated (milestone complete, audit PASS, clean tree)
+- [ ] Target version computed and greater than previous
+- [ ] Version manifest(s) updated with new version
+- [ ] CHANGELOG.md contains new entry with milestone summary + grouped changes
+- [ ] Release commit created with conventional message
+- [ ] Annotated git tag created (unless `--no-tag`)
+- [ ] Commit + tag pushed to remote (unless `--no-push` or push failed → W002)
+- [ ] state.json updated with last_release_version + last_release_at timestamp
+</success_criteria>

package/.claude/commands/maestro-phase-add.md

@@ -2,7 +2,15 @@
 name: maestro-phase-add
 description: Add or insert a new phase into the project roadmap with automatic renumbering
 argument-hint: "<slug> <title> [--after N]"
-allowed-tools: [Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion]
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
 ---
 
 <purpose>

package/.claude/commands/maestro-phase-transition.md

@@ -2,7 +2,15 @@
 name: maestro-phase-transition
 description: Mark current or specified phase as complete, extract learnings, advance to next phase
 argument-hint: "[phase-number] [--force]"
-allowed-tools: [Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion]
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
 ---
 
 <purpose>

package/.claude/commands/maestro.md

@@ -75,6 +75,12 @@ In auto mode, maestro also:
 - Skips chain confirmation (Step 5d)
 - Auto-skips on step errors (retry once, then skip and continue)
 
+**Context window reminder:**
+
+Before each Step 7 Skill() call, if context usage is near the window limit:
+- `-y` active → print one-line warning and continue.
+- Otherwise → stop before the next step and ask the user (Continue / Pause to resume with `-c` / Abort). Wait for explicit choice.
+
 **Report format on completion:**
 
 ```

package/.claude/commands/manage-codebase-rebuild.md

@@ -1,50 +1,76 @@
----
-name: manage-codebase-rebuild
-description: Full rebuild of codebase documentation - scans project, builds doc-index.json, generates all tech-registry and feature-maps
-argument-hint: "[--force] [--skip-commit]"
-allowed-tools: [Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion]
----
-
-<purpose>
-Perform a full rebuild of the .workflow/codebase/ documentation system from scratch. Scans the entire project source to identify components, features, requirements, and ADRs, then spawns parallel workflow-codebase-mapper agents to generate all documentation artifacts. This is a destructive operation that overwrites existing codebase docs.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/codebase-rebuild.md
-</required_reading>
-
-<context>
-$ARGUMENTS -- optional flags.
-
-**Flags:**
-- `--force` -- Skip confirmation prompt and proceed directly
-- `--skip-commit` -- Do not auto-commit after rebuild
-
-**State files:**
-- `.workflow/` -- must be initialized (project.md, state.json exist)
-- `.workflow/codebase/` -- target directory (will be cleared and rebuilt)
-- `.workflow/codebase/doc-index.json` -- generated documentation index
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/codebase-rebuild.md' completely.
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | .workflow/ not initialized | Run maestro-init first to create .workflow/ |
-| W001 | warning | A mapper agent failed (partial results) | Retry failed mapper or accept partial results |
-</error_codes>
-
-<success_criteria>
-- [ ] User confirmed rebuild (or --force used)
-- [ ] .workflow/codebase/ cleared and rebuilt from scratch
-- [ ] All 4 mapper agents spawned (failures logged as W001)
-- [ ] doc-index.json generated and valid
-- [ ] All documentation files regenerated
-- [ ] state.json updated with rebuild timestamp
-- [ ] project-tech.json refreshed with detected tech stack
-- [ ] project.md Tech Stack section updated if changes detected
-- [ ] Next step routing: Skill({ skill: "manage-status" }) or Skill({ skill: "manage-codebase-refresh" }) for incremental updates later
-</success_criteria>
+---
+name: manage-codebase-rebuild
+description: Full rebuild of codebase documentation - scans project, builds doc-index.json, generates all tech-registry and feature-maps
+argument-hint: "[--focus <area>] [--force] [--skip-commit]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+
+<purpose>
+Perform a full rebuild of the .workflow/codebase/ documentation system from scratch. Scans the entire project source to identify components, features, requirements, and ADRs, then spawns parallel workflow-codebase-mapper agents to generate all documentation artifacts. This is a destructive operation that overwrites existing codebase docs.
+
+Can run before or after Skill({ skill: "maestro-init" }) -- works on any codebase with source files. Also serves the previous `spec-map` use case via `--focus <area>` for scoped dimension analysis.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/codebase-rebuild.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- optional flags.
+
+**Flags:**
+- `--focus <area>` -- Scope mapper agents to a single domain (e.g., `auth`, `api`, `database`). When omitted, all 4 mappers run on the full codebase.
+- `--force` -- Skip confirmation prompt and proceed directly
+- `--skip-commit` -- Do not auto-commit after rebuild
+
+**Mapper agent assignments (when `--focus` omitted):**
+| Agent | Focus | Output file |
+|-------|-------|-------------|
+| Mapper 1 | **Tech stack** -- languages, frameworks, dependencies, build system | `tech-stack.md` |
+| Mapper 2 | **Architecture** -- layers, module boundaries, data flow, entry points | `architecture.md` |
+| Mapper 3 | **Features** -- capabilities, API surface, user-facing functionality | `features.md` |
+| Mapper 4 | **Cross-cutting concerns** -- error handling, logging, auth, config, testing | `concerns.md` |
+
+**State files:**
+- `.workflow/` -- must be initialized (project.md, state.json exist)
+- `.workflow/codebase/` -- target directory (will be cleared and rebuilt)
+- `.workflow/codebase/doc-index.json` -- generated documentation index
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/codebase-rebuild.md' completely.
+
+**When `--focus <area>` is set:** pass the area string to each mapper agent as scoping context; only regenerate the docs relevant to that scope (leave others untouched unless missing).
+
+**Next-step routing on completion:**
+- View updated project state → Skill({ skill: "manage-status" })
+- Incremental updates later → Skill({ skill: "manage-codebase-refresh" })
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | .workflow/ not initialized | Run maestro-init first to create .workflow/ |
+| W001 | warning | A mapper agent failed (partial results) | Retry failed mapper or accept partial results |
+| W002 | warning | `.workflow/codebase/` already exists -- user prompted for rebuild/skip | check_existing |
+</error_codes>
+
+<success_criteria>
+- [ ] User confirmed rebuild (or --force used)
+- [ ] .workflow/codebase/ cleared and rebuilt from scratch (or scoped subset when --focus set)
+- [ ] All 4 mapper agents spawned (failures logged as W001)
+- [ ] doc-index.json generated and valid
+- [ ] All documentation files regenerated
+- [ ] state.json updated with rebuild timestamp
+- [ ] project-tech.json refreshed with detected tech stack
+- [ ] project.md Tech Stack section updated if changes detected
+- [ ] Next step routing: Skill({ skill: "manage-status" }) or Skill({ skill: "manage-codebase-refresh" }) for incremental updates later
+</success_criteria>

package/.claude/commands/manage-codebase-refresh.md

@@ -2,7 +2,15 @@
 name: manage-codebase-refresh
 description: Incremental refresh of codebase docs based on recent changes
 argument-hint: "[--since <date>] [--deep]"
-allowed-tools: [Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion]
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
 ---
 
 <purpose>

package/.claude/commands/quality-refactor.md

@@ -1,7 +1,7 @@
 ---
 name: quality-refactor
 description: Tech debt reduction with reflection-driven iteration
-argument-hint: "[scope: module path, feature area, or 'all']"
+argument-hint: "[<scope>]"
 allowed-tools:
   - Read
   - Write

package/.claude/commands/quality-sync.md

@@ -2,7 +2,15 @@
 name: quality-sync
 description: Sync codebase docs after code changes - traces git diff through component/feature/requirement impact chain
 argument-hint: "[--full] [--since <commit|HEAD~N>] [--dry-run]"
-allowed-tools: [Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion]
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
 ---
 <purpose>
 Synchronize project state after manual code changes or to refresh codebase documentation. Detects changes via git diff, traces impact through doc-index.json (file -> component -> feature -> requirement), updates state.json and index.json, and refreshes affected `.workflow/codebase/` documentation. Use --full flag for a complete resync of all tracked files regardless of git diff.

package/.claude/commands/spec-setup.md

@@ -51,7 +51,7 @@ Follow '~/.maestro/workflows/specs-setup.md' completely.
 - [ ] `learnings.md` initialized with format instructions
 - [ ] `project-tech.json` written with detected tech stack
 - [ ] Report displayed with summary and next steps:
-  - Build codebase docs → Skill({ skill: "spec-map" })
+  - Build codebase docs → Skill({ skill: "manage-codebase-rebuild" })
   - Load specs for task → Skill({ skill: "spec-load" })
   - Add new knowledge → Skill({ skill: "spec-add", args: "<type> <content>" })
 </success_criteria>

package/.codex/skills/maestro-coordinate/SKILL.md

@@ -164,11 +164,25 @@ for (const step of state.steps.filter(s => s.status === 'pending')) {
   // Spawn step agent
   const agent = spawn_agent({ message: stepPrompt })
 
-  // Wait — with timeout urge
-  let result = wait_agent({ timeout_ms: 600000 })
+  // Wait — initial spawn: 30 min
+  let result = wait_agent({ timeout_ms: 1800000 })
   if (result.timed_out) {
-    send_message({ target: agent, message: "Please wrap up and output your findings JSON now." })
-    result = wait_agent({ timeout_ms: 600000 })
+    // Step 1: Status probe (non-interrupting, 3 min)
+    followup_task({ target: agent, message: "STATUS_CHECK: Report current progress, findings so far, and estimated remaining work." })
+    const status = wait_agent({ timeout_ms: 180000 })
+    if (status.timed_out) {
+      // Step 2: Force finalize (interrupt, 3 min)
+      followup_task({ target: agent, message: "FINALIZE: Output all current findings immediately. Time limit reached.", interrupt: true })
+      const forced = wait_agent({ timeout_ms: 180000 })
+      if (forced.timed_out) {
+        // Step 3: Abort
+        close_agent({ target: agent })
+      } else {
+        result = forced
+      }
+    } else {
+      result = status
+    }
   }
 
   // Parse structured output from agent
@@ -290,7 +304,7 @@ Resume: $maestro-coordinate --continue
 |------|----------|-----------|----------|
 | E001 | error | Intent unclassifiable after clarification | Default to `feature` chain; note in state.json |
 | E002 | error | `--chain` value not in chain map | List valid chains, abort |
-| E003 | error | Step agent timeout (both waits) | Mark step `failed`; skip remaining steps; suggest `--continue` |
+| E003 | error | Step agent timeout (4-step cascade exhausted) | Mark step `failed`; skip remaining steps; suggest `--continue` |
 | E004 | error | Step agent failed (non-JSON output) | Mark step `failed`; preserve raw output in `findings`; skip remaining |
 | E005 | error | `--continue`: no session found | Glob `.workflow/.maestro-coordinate/MCC-*/`, list sessions, prompt |
 | W001 | warning | Step output JSON missing `hints_for_next` | Continue with empty hints; next step still gets `findings` |
@@ -306,5 +320,5 @@ Resume: $maestro-coordinate --continue
 5. **Skip on Failure**: Step failure immediately marks all remaining steps `skipped` and aborts the loop
 6. **Close before spawn**: Always `close_agent` the current step agent before spawning the next
 7. **Dry-run is read-only**: Stop after displaying the chain plan — never spawn agents
-8. **Timeout handling**: One urge via `send_message`; if still timed out → mark `failed`
+8. **Timeout handling**: 4-step cascade — status probe → force finalize → abort; if all timed out → mark `failed`
 9. **No CLI fallback**: All execution is agent-native — no `exec_command("maestro delegate ...")`

package/.codex/skills/manage-issue-analyze/SKILL.md

@@ -87,7 +87,7 @@ Identify: affected locations (file:line), caller/callee chains, data flow, exist
 EXPECTED: JSON with: affected_files [{file, line, snippet, relevance}], related_modules, error_handling_gaps, test_coverage_gaps.
 `
 })
-const ctxResult = wait_agent({ timeout_ms: 600000 })
+const ctxResult = wait_agent({ timeout_ms: 1800000 })  // initial spawn: 30 min
 close_agent({ target: "ctx-explore" })
 ```
 

package/.codex/skills/quality-retrospective/SKILL.md

@@ -199,7 +199,7 @@ EXPECTED: Comprehensive artifact summary covering:
 - Key metrics: lines changed, test coverage, time taken
 `
 })
-wait_agent({ timeout_ms: 600000 })
+wait_agent({ timeout_ms: 1800000 })  // initial spawn: 30 min
 ```
 
 **Step 4b: Fork 4 lens agents** (only active lenses based on `--lens` flag; default: all 4)
@@ -285,7 +285,7 @@ EXPECTED: Same JSON array schema as technical lens.
 })
 
 const lensResults = wait_agent({
-  timeout_ms: 600000
+  timeout_ms: 1800000  // initial spawn: 30 min
 })
 
 // Close lenses first
@@ -323,7 +323,7 @@ EXPECTED: JSON with:
 `
 })
 
-const synthResult = wait_agent({ timeout_ms: 600000 })
+const synthResult = wait_agent({ timeout_ms: 1800000 })  // initial spawn: 30 min
 close_agent({ target: "synthesizer" })
 ```
 

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

@@ -160,7 +160,7 @@ pipeline_phase: <pipeline-phase>
 })
 ```
 
-After spawning, use `wait_agent({ timeout_ms: 900000 })` to collect results, then `close_agent({ target: <name> })` each worker.
+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: <name> })` each worker.
 
 **Inner Loop roles** (role has 2+ serial same-prefix tasks): Set `inner_loop: true`. The team-worker agent handles the loop internally.
 

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

@@ -226,7 +226,7 @@ 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({ timeout_ms: 900000 })
+const result = wait_agent({ timeout_ms: 1800000 })  // 30 min
 
 // Drain progress from message bus (before processing results)
 const progressMsgs = mcp__maestro-tools__team_msg({
@@ -237,15 +237,24 @@ for (const msg of (progressMsgs.result?.messages || [])) {
 }
 
 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
+  // 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 })
+    }
+    // else: forced output received, process result
+  }
+  // else: status received, continue processing
 } else {
   // Process result, update tasks.json
   close_agent({ target: taskId })  // Use task_name, not agentId

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({ timeout_ms: 900000 })     — monitoring
+OK: wait_agent({ timeout_ms: 1800000 })     — monitoring (30 min)
 ```
 
 **Self-check gate**: After Phase 1 analysis, before ANY other action, ask yourself:
@@ -380,7 +380,7 @@ 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.
-- **followup_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, and status probing on timeout (STATUS_CHECK / FINALIZE cascade before closing timed-out agents).
 
 ### 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.

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

@@ -132,7 +132,7 @@ pipeline_phase: <pipeline-phase>
 })
 ```
 
-After spawning, use `wait_agent({ timeout_ms: 900000 })` to collect results, then `close_agent({ target: <name> })` each worker.
+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: <name> })` each worker.
 
 ---
 

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

@@ -189,7 +189,7 @@ After spawning all ready tasks:
 const agentIds = Object.values(state.active_agents)
   .filter(a => !a.resident)
   .map(a => a.agentId)
-const waitResult = wait_agent({ timeout_ms: 900000 })
+const waitResult = wait_agent({ timeout_ms: 1800000 })  // 30 min
 
 // Drain progress from message bus
 const progressMsgs = mcp__maestro-tools__team_msg({
@@ -202,14 +202,25 @@ for (const msg of (progressMsgs.result?.messages || [])) {
 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]
+    // 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: agent.agentId })
+        delete state.active_agents[taskId]
+      }
+      // else: forced output received, process result
+    }
+    // else: status received, continue processing
   }
 } else {
   // Collect results from discoveries/{task_id}.json

package/.codex/skills/team-lifecycle-v4/SKILL.md

@@ -153,7 +153,7 @@ task_id: <CHECKPOINT-NNN>
 scope: [<upstream-task-ids>]
 pipeline_progress: <done>/<total> tasks completed`
 })
-wait_agent({ timeout_ms: 600000 })
+wait_agent({ timeout_ms: 1800000 })  // 30 min
 ```
 
 ### Shutdown (pipeline complete)
@@ -196,7 +196,7 @@ 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", message: "..." })`, collect agent IDs
-6. **Wait** -- `wait_agent({ timeout_ms: 900000 })`
+6. **Wait** -- `wait_agent({ timeout_ms: 1800000 })` (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.
 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, `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