maestro-flow 0.3.38 → 0.3.40

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

@@ -1,115 +1,116 @@
----
-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(*), followup_task(*), close_agent(*), list_agents(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__maestro-tools__team_msg(*)
----
-
-<purpose>
-Lightweight session execution skill: load session -> reconcile state -> spawn team-worker agents -> execute -> deliver. **No analysis, no role generation** -- only executes existing team-coordinate sessions.
-
-```
-Skill(skill="team-executor")
-  args="--session=<path>" [REQUIRED]
-         |
-  Session Validation
-         |
-  +-- valid? --+-- NO --> Error immediately
-               +-- YES -> Orchestration Mode -> executor
-                              |
-              +-------+-------+-------+
-              v       v       v       v
-           [team-worker agents loaded from session role-specs]
-```
-</purpose>
-
-<context>
-$ARGUMENTS — session path (required).
-
-**Parse:** `--session=<path>` — Path to team-coordinate session folder (REQUIRED)
-
-**Validation Steps:**
-1. Check `--session` provided
-2. Directory exists at path
-3. `team-session.json` exists and valid JSON
-4. `task-analysis.json` exists and valid JSON
-5. `role-specs/` directory has at least one `.md` file
-6. Each role in `team-session.json#roles` has corresponding `.md` in `role-specs/`
-
-**Dispatch:**
-| Scenario | Action |
-|----------|--------|
-| No `--session` | ERROR immediately |
-| `--session` invalid | ERROR with specific reason |
-| Valid session | Orchestration Mode -> executor |
-
-**User Commands** (wake paused executor):
-| Command | Action |
-|---------|--------|
-| `check` / `status` | Output execution status graph, no advancement |
-| `resume` / `continue` | Check worker states, advance next step |
-
-**Role Registry:**
-| Role | File | Type |
-|------|------|------|
-| executor | [roles/executor/role.md](roles/executor/role.md) | built-in orchestrator |
-| (dynamic) | `<session>/role-specs/<role-name>.md` | loaded from session |
-
-**Integration with team-coordinate:**
-| Scenario | Skill |
-|----------|-------|
-| New task, no session | team-coordinate |
-| Existing session, resume execution | **team-executor** |
-| Session needs new roles | team-coordinate (with resume) |
-| Pure execution, no analysis | **team-executor** |
-</context>
-
-<execution>
-
-### Orchestration Lifecycle
-
-Validate session -> Phase 0 (reconcile state, reset interrupted tasks, detect orphans) -> Phase 1 (spawn first batch workers, STOP) -> callback loop (advance next step) -> Phase 2 (report + completion action).
-
-### Worker Spawn Template
-
-Spawn via `team-worker` agent with role-spec path from session. Message includes: role, role_spec, 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) -> mark timed_out, close.
-
-### Model Selection
-
-Implementation/fix roles: `reasoning_effort: "high"`. Verification/test: `"medium"`. Default: `"high"`.
-
-### State Reconciliation
-
-On resume: compare `list_agents({})` with task-analysis.json. Reset orphaned tasks to pending.
-
-### Worker Communication
-
-`send_message` (supplementary context), `followup_task` (assign work to inner_loop worker), `close_agent` (cleanup).
-
-### Completion Action
-
-Present choice: **Archive & Clean** (mark completed, output summary), **Keep Active** (mark paused, output resume command), **Export Results** (prompt path, copy, archive).
-</execution>
-
-<error_codes>
-| Scenario | Resolution |
-|----------|------------|
-| No --session provided | ERROR immediately with usage message |
-| Session directory not found | ERROR with path, suggest checking path |
-| team-session.json missing | ERROR, session incomplete, suggest re-run team-coordinate |
-| task-analysis.json missing | ERROR, session incomplete, suggest re-run team-coordinate |
-| No role-specs in session | ERROR, session incomplete, suggest re-run team-coordinate |
-| Role-spec file not found | ERROR with expected path |
-| capability_gap reported | Warn only, cannot generate new role-specs |
-| Fast-advance spawns wrong task | Executor reconciles on next callback |
-| Completion action fails | Default to Keep Active, log warning |
-</error_codes>
-
-<success_criteria>
-- [ ] Session validated (all required files present)
-- [ ] State reconciled on resume (orphaned tasks reset)
-- [ ] Team-worker agents spawned with correct role-specs
-- [ ] Workers complete or timeout handled gracefully
-- [ ] Pipeline advances step-by-step through all tasks
-- [ ] Completion action presented and executed
-- [ ] Session state updated throughout lifecycle
-</success_criteria>
+---
+name: team-executor
+description: Resume team-coordinate sessions for pure execution
+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(*)
+---
+
+<purpose>
+Lightweight session execution skill: load session -> reconcile state -> spawn team-worker agents -> execute -> deliver. **No analysis, no role generation** -- only executes existing team-coordinate sessions.
+
+```
+Skill(skill="team-executor")
+  args="--session=<path>" [REQUIRED]
+         |
+  Session Validation
+         |
+  +-- valid? --+-- NO --> Error immediately
+               +-- YES -> Orchestration Mode -> executor
+                              |
+              +-------+-------+-------+
+              v       v       v       v
+           [team-worker agents loaded from session role-specs]
+```
+
+</purpose>
+
+<context>
+$ARGUMENTS — session path (required).
+
+**Parse:** `--session=<path>` — Path to team-coordinate session folder (REQUIRED)
+
+**Validation Steps:**
+1. Check `--session` provided
+2. Directory exists at path
+3. `team-session.json` exists and valid JSON
+4. `task-analysis.json` exists and valid JSON
+5. `role-specs/` directory has at least one `.md` file
+6. Each role in `team-session.json#roles` has corresponding `.md` in `role-specs/`
+
+**Dispatch:**
+| Scenario | Action |
+|----------|--------|
+| No `--session` | ERROR immediately |
+| `--session` invalid | ERROR with specific reason |
+| Valid session | Orchestration Mode -> executor |
+
+**User Commands** (wake paused executor):
+| Command | Action |
+|---------|--------|
+| `check` / `status` | Output execution status graph, no advancement |
+| `resume` / `continue` | Check worker states, advance next step |
+
+**Role Registry:**
+| Role | File | Type |
+|------|------|------|
+| executor | [roles/executor/role.md](roles/executor/role.md) | built-in orchestrator |
+| (dynamic) | `<session>/role-specs/<role-name>.md` | loaded from session |
+
+**Integration with team-coordinate:**
+| Scenario | Skill |
+|----------|-------|
+| New task, no session | team-coordinate |
+| Existing session, resume execution | **team-executor** |
+| Session needs new roles | team-coordinate (with resume) |
+| Pure execution, no analysis | **team-executor** |
+</context>
+
+<execution>
+
+### Orchestration Lifecycle
+
+Validate session -> Phase 0 (reconcile state, reset interrupted tasks, detect orphans) -> Phase 1 (spawn first batch workers, STOP) -> callback loop (advance next step) -> Phase 2 (report + completion action).
+
+### Worker Spawn Template
+
+Spawn via `team-worker` agent with role-spec path from session. Message includes: role, role_spec, 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) -> mark timed_out, close.
+
+### Model Selection
+
+Implementation/fix roles: `reasoning_effort: "high"`. Verification/test: `"medium"`. Default: `"high"`.
+
+### State Reconciliation
+
+On resume: compare `list_agents({})` with task-analysis.json. Reset orphaned tasks to pending.
+
+### Worker Communication
+
+`send_message` (supplementary context), `followup_task` (assign work to inner_loop worker), `close_agent` (cleanup).
+
+### Completion Action
+
+Present choice: **Archive & Clean** (mark completed, output summary), **Keep Active** (mark paused, output resume command), **Export Results** (prompt path, copy, archive).
+</execution>
+
+<error_codes>
+| Scenario | Resolution |
+|----------|------------|
+| No --session provided | ERROR immediately with usage message |
+| Session directory not found | ERROR with path, suggest checking path |
+| team-session.json missing | ERROR, session incomplete, suggest re-run team-coordinate |
+| task-analysis.json missing | ERROR, session incomplete, suggest re-run team-coordinate |
+| No role-specs in session | ERROR, session incomplete, suggest re-run team-coordinate |
+| Role-spec file not found | ERROR with expected path |
+| capability_gap reported | Warn only, cannot generate new role-specs |
+| Fast-advance spawns wrong task | Executor reconciles on next callback |
+| Completion action fails | Default to Keep Active, log warning |
+</error_codes>
+
+<success_criteria>
+- [ ] Session validated (all required files present)
+- [ ] State reconciled on resume (orphaned tasks reset)
+- [ ] Team-worker agents spawned with correct role-specs
+- [ ] Workers complete or timeout handled gracefully
+- [ ] Pipeline advances step-by-step through all tasks
+- [ ] Completion action presented and executed
+- [ ] Session state updated throughout lifecycle
+</success_criteria>

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

@@ -1,6 +1,6 @@
 ---
 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".
+description: Full lifecycle team -- plan, develop, test, review
 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(*)
 ---
 
@@ -32,6 +32,7 @@ Skill(skill="team-lifecycle-v4", args="task description")
                               |
                          collect results
 ```
+
 </purpose>
 
 <context>

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

@@ -26,12 +26,16 @@ This instruction is loaded by team-worker agents when spawned with roles: `analy
    ```
 
 2. **Explore domain** (use CLI analysis tools):
-   ```bash
-   maestro delegate "PURPOSE: Research domain for {requirement}
+   ```
+   exec_command({
+     cmd: `maestro delegate "PURPOSE: Research domain for {requirement}
    TASK: • Identify problem statement • Define target users • Extract constraints • Map integration points
    CONTEXT: @**/* | Memory: {requirement}
    EXPECTED: Structured research context with problem/users/domain/constraints
-   CONSTRAINTS: Read-only analysis" --tool gemini --mode analysis --rule analysis-trace-code-execution
+   CONSTRAINTS: Read-only analysis" --role analyze --mode analysis --rule analysis-trace-code-execution`,
+     yield_time_ms: 30000, max_output_tokens: 6000
+   })
+   // ⚠️ If session_id returned → poll write_stdin until completion (see @~/.maestro/workflows/delegate-protocol.codex.md)
    ```
 
 3. **Extract structured context**:
@@ -293,12 +297,16 @@ This instruction is loaded by team-worker agents when spawned with roles: `analy
    ```
 
 2. **Explore codebase** (use CLI analysis tools):
-   ```bash
-   maestro delegate "PURPOSE: Explore codebase for {requirement}
+   ```
+   exec_command({
+     cmd: `maestro delegate "PURPOSE: Explore codebase for {requirement}
    TASK: • Identify relevant files • Find existing patterns • Locate integration points
    CONTEXT: @**/* | Memory: {requirement}
    EXPECTED: Exploration findings with file paths and patterns
-   CONSTRAINTS: Read-only analysis" --tool gemini --mode analysis --rule analysis-trace-code-execution
+   CONSTRAINTS: Read-only analysis" --role explore --mode analysis --rule analysis-trace-code-execution`,
+     yield_time_ms: 30000, max_output_tokens: 6000
+   })
+   // ⚠️ If session_id returned → poll write_stdin until completion (see @~/.maestro/workflows/delegate-protocol.codex.md)
    ```
 
 3. **Generate implementation plan**:

package/.codex/skills/team-lifecycle-v4/roles/analyst/role.md

@@ -36,12 +36,18 @@ Research and codebase exploration for context gathering.
 4. If topic references file (@path or .md/.txt) -> read it
 5. CLI seed analysis:
    ```
-   Bash({ command: `maestro delegate "PURPOSE: Analyze topic, extract structured seed info.
+   exec_command({
+     cmd: `maestro delegate "PURPOSE: Analyze topic, extract structured seed info.
    TASK: * Extract problem statement * Identify target users * Determine domain
    * List constraints * Identify 3-5 exploration dimensions
    TOPIC: <topic-content>
    MODE: analysis
-   EXPECTED: JSON with: problem_statement, target_users[], domain, constraints[], exploration_dimensions[]" --tool gemini --mode analysis`)
+   EXPECTED: JSON with: problem_statement, target_users[], domain, constraints[], exploration_dimensions[]" --role analyze --mode analysis`,
+     yield_time_ms: 30000,
+     max_output_tokens: 6000
+   })
+   // ⚠️ If session_id returned → poll write_stdin until completion (see @~/.maestro/workflows/delegate-protocol.codex.md)
+   // NEVER skip — seed analysis result is required for context packaging
    ```
 6. Parse result JSON
 
@@ -54,11 +60,17 @@ Research and codebase exploration for context gathering.
 
 When project detected:
 ```
-Bash({ command: `maestro delegate "PURPOSE: Explore codebase for context
+exec_command({
+  cmd: `maestro delegate "PURPOSE: Explore codebase for context
 TASK: * Identify tech stack * Map architecture patterns * Document conventions * List integration points
 MODE: analysis
 CONTEXT: @**/*
-EXPECTED: JSON with: tech_stack[], architecture_patterns[], conventions[], integration_points[]" --tool gemini --mode analysis`)
+EXPECTED: JSON with: tech_stack[], architecture_patterns[], conventions[], integration_points[]" --role explore --mode analysis`,
+  yield_time_ms: 30000,
+  max_output_tokens: 6000
+})
+// ⚠️ If session_id returned → poll write_stdin until completion (see @~/.maestro/workflows/delegate-protocol.codex.md)
+// NEVER skip — codebase context is required for downstream roles
 ```
 
 ## Phase 4: Context Packaging

package/.codex/skills/team-lifecycle-v4/roles/executor/commands/implement.md

@@ -51,7 +51,13 @@ CONSTRAINTS: Only modify listed files | Follow existing patterns
 
 CLI call:
 ```
-Bash(`maestro delegate "<prompt>" --to <tool> --mode write --rule development-implement-feature`)
+exec_command({
+  cmd: `maestro delegate "<prompt>" --role implement --mode write --rule development-implement-feature`,
+  yield_time_ms: 30000,
+  max_output_tokens: 6000
+})
+// ⚠️ If session_id returned → poll write_stdin until completion (see @~/.maestro/workflows/delegate-protocol.codex.md)
+// NEVER skip — implementation must complete before convergence check
 ```
 
 Resume strategy:

package/.codex/skills/team-lifecycle-v4/roles/planner/role.md

@@ -36,11 +36,17 @@ Codebase-informed implementation planning with complexity assessment.
 3. Check <session>/explorations/cache-index.json for cached explorations
 4. Explore codebase (cache-aware):
    ```
-   Bash({ command: `maestro delegate "PURPOSE: Explore codebase to inform planning
+   exec_command({
+     cmd: `maestro delegate "PURPOSE: Explore codebase to inform planning
    TASK: * Search for relevant patterns * Identify files to modify * Document integration points
    MODE: analysis
    CONTEXT: @**/*
-   EXPECTED: JSON with: relevant_files[], patterns[], integration_points[], recommendations[]" --tool gemini --mode analysis`)
+   EXPECTED: JSON with: relevant_files[], patterns[], integration_points[], recommendations[]" --role explore --mode analysis`,
+     yield_time_ms: 30000,
+     max_output_tokens: 6000
+   })
+   // ⚠️ If session_id returned → poll write_stdin until completion (see @~/.maestro/workflows/delegate-protocol.codex.md)
+   // NEVER skip — delegate result is required for plan generation
    ```
 5. Store results in <session>/explorations/
 
@@ -48,12 +54,18 @@ Codebase-informed implementation planning with complexity assessment.
 
 Generate plan.json + .task/TASK-*.json:
 ```
-Bash({ command: `maestro delegate "PURPOSE: Generate implementation plan from exploration results
+exec_command({
+  cmd: `maestro delegate "PURPOSE: Generate implementation plan from exploration results
 TASK: * Create plan.json overview * Generate TASK-*.json files (2-7 tasks) * Define dependencies * Set convergence criteria
 MODE: write
 CONTEXT: @<session>/explorations/*.json
 EXPECTED: Files: plan.json + .task/TASK-*.json
-CONSTRAINTS: 2-7 tasks, include id/title/files[]/convergence.criteria/depends_on" --tool gemini --mode write`)
+CONSTRAINTS: 2-7 tasks, include id/title/files[]/convergence.criteria/depends_on" --role implement --mode write`,
+  yield_time_ms: 30000,
+  max_output_tokens: 6000
+})
+// ⚠️ If session_id returned → poll write_stdin until completion (see @~/.maestro/workflows/delegate-protocol.codex.md)
+// NEVER skip — must wait for plan files to be written
 ```
 
 Output files:

package/.codex/skills/team-lifecycle-v4/roles/writer/role.md

@@ -61,12 +61,18 @@ Template-driven document generation with progressive dependency loading.
 
 CLI generation:
 ```
-Bash({ command: `maestro delegate "PURPOSE: Generate <doc-type> document following template
+exec_command({
+  cmd: `maestro delegate "PURPOSE: Generate <doc-type> document following template
 TASK: * Load template * Apply spec config and discovery context * Integrate prior feedback * Generate all sections
 MODE: write
 CONTEXT: @<session>/spec/*.json @<template-path>
 EXPECTED: Document at <output-path> with YAML frontmatter, all sections, cross-references
-CONSTRAINTS: Follow document standards" --tool gemini --mode write --cd <session>`)
+CONSTRAINTS: Follow document standards" --role implement --mode write --cd <session>`,
+  yield_time_ms: 30000,
+  max_output_tokens: 6000
+})
+// ⚠️ If session_id returned → poll write_stdin until completion (see @~/.maestro/workflows/delegate-protocol.codex.md)
+// NEVER skip — document must be fully written before validation
 ```
 
 ## Phase 4: Validation

package/.codex/skills/team-quality-assurance/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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".
+description: Team QA combining issue discovery and testing
 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(*)
 ---
 
@@ -26,6 +26,7 @@ Skill(skill="team-quality-assurance", args="task description")
                  [scout] [strat] [gen] [exec] [analyst]
                  team-worker agents, each loads roles/<role>/role.md
 ```
+
 </purpose>
 
 <context>

package/.codex/skills/team-quality-assurance/roles/scout/role.md

@@ -41,7 +41,7 @@ Scan codebase from multiple perspectives (bug, security, test-coverage, code-qua
 
 **Medium/High complexity**: CLI fan-out -- one `maestro delegate --mode analysis` per perspective:
 
-For each active perspective, build prompt:
+For each active perspective, build prompt and execute:
 ```
 PURPOSE: Scan code from <perspective> perspective to discover potential issues
 TASK: Analyze code patterns for <perspective> problems, identify anti-patterns, check for common issues
@@ -50,7 +50,14 @@ CONTEXT: @<scan-scope>
 EXPECTED: List of findings with severity (critical/high/medium/low), file:line references, description
 CONSTRAINTS: Focus on actionable findings only
 ```
-Execute via: `maestro delegate "<prompt>" --role analyze --mode analysis`
+```
+exec_command({
+  cmd: `maestro delegate "<prompt>" --role analyze --mode analysis`,
+  yield_time_ms: 30000, max_output_tokens: 6000
+})
+// ⚠️ If session_id returned → poll write_stdin until completion (see @~/.maestro/workflows/delegate-protocol.codex.md)
+// NEVER skip — each perspective's findings are required for aggregation
+```
 
 After all perspectives complete:
 - Parse CLI outputs into structured findings

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

@@ -1,6 +1,6 @@
 ---
 name: team-review
-description: "Unified team skill for code review. 3-role pipeline: scanner, reviewer, fixer. Triggers on team-review."
+description: Team code review -- scan, review, fix pipeline
 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__ace-tool__search_context(*), mcp__maestro-tools__team_msg(*)
 ---
 
@@ -26,6 +26,7 @@ Skill(skill="team-review", args="task description")
                 [scan]  [review]  [fix]
                 team-worker agents, each loads roles/<role>/role.md
 ```
+
 </purpose>
 
 <context>

package/.codex/skills/team-review/roles/reviewer/role.md

@@ -52,7 +52,16 @@ Build prompt per group requesting 6 enrichment fields per finding:
 - `fix_complexity`: low / medium / high
 - `fix_dependencies`: finding IDs that must be fixed first
 
-Execute via `maestro delegate --role review --mode analysis --rule analysis-diagnose-bug-root-cause`. Parse JSON array responses, merge with originals (CLI-enriched replace originals, unenriched get defaults). Write `<session>/review/enriched-findings.json`.
+Execute via:
+```
+exec_command({
+  cmd: `maestro delegate "<prompt>" --role review --mode analysis --rule analysis-diagnose-bug-root-cause`,
+  yield_time_ms: 30000, max_output_tokens: 6000
+})
+// ⚠️ If session_id returned → poll write_stdin until completion (see @~/.maestro/workflows/delegate-protocol.codex.md)
+// NEVER skip — enrichment results are required for report generation
+```
+Parse JSON array responses, merge with originals (CLI-enriched replace originals, unenriched get defaults). Write `<session>/review/enriched-findings.json`.
 
 ## Phase 4: Report Generation
 

package/.codex/skills/team-review/roles/scanner/role.md

@@ -59,7 +59,16 @@ Build prompt with target file patterns, toolchain dedup summary, and per-dimensi
 - PRF: Algorithm complexity, N+1 queries, unnecessary sync, memory leaks, missing caching
 - MNT: Architectural coupling, abstraction leaks, convention violations, dead code
 
-Execute via `maestro delegate --role review --mode analysis --rule analysis-review-code-quality`. Parse JSON array response, validate required fields (dimension, title, location.file), enforce per-dimension limit (max 5 each), filter minimum severity (medium+). Write `<session>/scan/semantic-findings.json`.
+Execute via:
+```
+exec_command({
+  cmd: `maestro delegate "<prompt>" --role review --mode analysis --rule analysis-review-code-quality`,
+  yield_time_ms: 30000, max_output_tokens: 6000
+})
+// ⚠️ If session_id returned → poll write_stdin until completion (see @~/.maestro/workflows/delegate-protocol.codex.md)
+// NEVER skip — semantic findings are required for aggregation
+```
+Parse JSON array response, validate required fields (dimension, title, location.file), enforce per-dimension limit (max 5 each), filter minimum severity (medium+). Write `<session>/scan/semantic-findings.json`.
 
 ## Phase 4: Aggregate & Output