maestro-flow 0.3.9 → 0.3.10

package/templates/search-tools.md

@@ -17,7 +17,7 @@ Semantic Search → Grep (pattern) → Glob (files) → CLI (deep analysis)
 | Find by intent/behavior | Semantic search tool (see above) |
 | Known identifier/regex | `Grep` |
 | Find files by name/ext | `Glob` |
-| Complex cross-file reasoning | `maestro cli --tool gemini --mode analysis` |
+| Complex cross-file reasoning | `maestro delegate --to gemini --mode analysis` |
 | Read identified file | `Read` |
 
 ## Fallback

package/workflows/cli-tools-usage.md

@@ -1,7 +1,7 @@
-# CLI Tools Execution Specification
+# Delegate Execution Specification
 
 <purpose>
-Unified reference for `maestro cli` — runs agent tools (gemini, qwen, codex, claude, opencode) with a shared interface for prompt, mode, model, directory, templates, and session resume.
+Unified reference for `maestro delegate` — synchronous task delegation with broker-managed lifecycle, message injection, and MCP notifications.
 </purpose>
 
 **References**: `~/.maestro/cli-tools.json` (tool config), `~/.maestro/templates/cli/` (protocol + prompt templates)
@@ -15,15 +15,14 @@ Unified reference for `maestro cli` — runs agent tools (gemini, qwen, codex, c
 ### Command Syntax
 
 ```bash
-maestro cli -p "<PROMPT>" [options]
+maestro delegate "<PROMPT>" [options]
 ```
 
 ### Options
 
 | Option | Description | Default |
 |--------|-------------|---------|
-| `-p, --prompt` | **Required**. Prompt text | — |
-| `--tool <name>` | Tool: gemini, qwen, codex, claude, opencode | First enabled in config |
+| `--to <name>` | Tool: gemini, qwen, codex, claude, opencode | First enabled in config |
 | `--mode <mode>` | `analysis` (read-only) or `write` (create/modify/delete) | `analysis` |
 | `--model <model>` | Model override | Tool's `primaryModel` |
 | `--cd <dir>` | Working directory | Current directory |
@@ -31,6 +30,7 @@ maestro cli -p "<PROMPT>" [options]
 | `--rule <template>` | Load protocol + prompt template | — (optional) |
 | `--id <id>` | Execution ID | Auto: `{prefix}-{HHmmss}-{rand4}` |
 | `--resume [id]` | Resume session (last if no id, comma-separated for merge) | — |
+| `--backend <type>` | Adapter backend: `direct` or `terminal` (tmux/wezterm) | `direct` |
 
 ### Mode Definition (Authoritative)
 
@@ -39,7 +39,7 @@ maestro cli -p "<PROMPT>" [options]
 | `analysis` | Read-only | Yes | Review, exploration, diagnosis, architecture analysis |
 | `write` | Create/Modify/Delete | No — requires explicit intent | Implementation, bug fixes, refactoring |
 
-> `--mode` is the **authoritative** permission control for maestro cli. The `MODE:` field inside prompt text is a hint for the agent — both should be consistent, but `--mode` governs actual behavior.
+> `--mode` is the **authoritative** permission control. The `MODE:` field inside prompt text is a hint for the agent — both should be consistent, but `--mode` governs actual behavior.
 </context>
 
 ---
@@ -72,8 +72,8 @@ maestro cli -p "<PROMPT>" [options]
 
 ### Tool Selection
 
-1. Explicit `--tool` specified → use it (validate enabled)
-2. No `--tool` → first enabled tool in config order
+1. Explicit `--to` specified → use it (validate enabled)
+2. No `--to` → first enabled tool in config order
 
 ### Fallback Chain
 
@@ -88,10 +88,10 @@ Primary model fails → `secondaryModel` → next enabled tool → first enabled
 
 ### Assembly Order
 
-`maestro cli` builds the final prompt as:
+`maestro delegate` builds the final prompt as:
 
 1. **Mode protocol** — `~/.maestro/templates/cli/protocols/{mode}-protocol.md`
-2. **User prompt** — the `-p` value
+2. **User prompt** — the positional `"<PROMPT>"` value
 3. **Rule template** — `~/.maestro/templates/cli/prompts/{rule}.txt` (if `--rule` specified)
 
 ### Prompt Template (6 Fields)
@@ -122,7 +122,7 @@ CONSTRAINTS: [scope limits] | [special requirements]
 
 ```bash
 # Cross-directory example
-maestro cli -p "CONTEXT: @**/* @../shared/**/*" --tool gemini --mode analysis \
+maestro delegate "CONTEXT: @**/* @../shared/**/*" --to gemini --mode analysis \
   --cd "src/auth" --includeDirs "../shared"
 ```
 
@@ -148,13 +148,13 @@ Memory: Integration with auth module, using shared error patterns
 ### Complete Example
 
 ```bash
-maestro cli -p "PURPOSE: Identify OWASP Top 10 vulnerabilities in auth module; success = all critical/high documented with remediation
+maestro delegate "PURPOSE: Identify OWASP Top 10 vulnerabilities in auth module; success = all critical/high documented with remediation
 TASK: Scan for injection flaws | Check auth bypass vectors | Evaluate session management | Assess data exposure
 MODE: analysis
 CONTEXT: @src/auth/**/* @src/middleware/auth.ts | Memory: Using bcrypt + JWT
 EXPECTED: Severity matrix, file:line references, remediation snippets, priority ranking
 CONSTRAINTS: Focus on authentication | Ignore test files
-" --tool gemini --mode analysis --rule analysis-assess-security-risks --cd "src/auth"
+" --to gemini --mode analysis --rule analysis-assess-security-risks --cd "src/auth"
 ```
 </context>
 
@@ -164,6 +164,24 @@ CONSTRAINTS: Focus on authentication | Ignore test files
 
 <execution>
 
+### Calling Convention
+
+`maestro delegate` runs synchronously — it blocks until the delegate completes. To avoid blocking the conversation, **always** use `run_in_background: true` on the Bash tool call, then stop output immediately and wait for the background completion callback.
+
+```
+Bash({
+  command: "maestro delegate \"<PROMPT>\" --to gemini --mode analysis",
+  run_in_background: true
+})
+// STOP — do not output anything further
+// Wait for Bash background completion callback to receive results
+```
+
+**Rules:**
+- **Never** use foreground Bash for delegate calls — it blocks the conversation for the entire execution duration
+- After the `Bash(run_in_background: true)` call, **stop immediately** — no follow-up text, no polling, no `delegate status` checks
+- When the background callback arrives, retrieve output with `maestro delegate output <id>`
+
 ### Execution ID
 
 ID prefix: gemini→`gem`, qwen→`qwn`, codex→`cdx`, claude→`cld`, opencode→`opc`
@@ -171,16 +189,16 @@ ID prefix: gemini→`gem`, qwen→`qwn`, codex→`cdx`, claude→`cld`, opencode
 Output to stderr: `[MAESTRO_EXEC_ID=<id>]`
 
 ```bash
-maestro cli -p "<PROMPT>" --tool gemini --mode analysis    # auto-ID: gem-143022-a7f2
-maestro cli -p "<PROMPT>" --tool gemini --mode write --id my-task-1  # custom ID
+maestro delegate "<PROMPT>" --to gemini --mode analysis    # auto-ID: gem-143022-a7f2
+maestro delegate "<PROMPT>" --to gemini --mode write --id my-task-1  # custom ID
 ```
 
 ### Session Resume
 
 ```bash
-maestro cli -p "<PROMPT>" --tool gemini --resume              # last session
-maestro cli -p "<PROMPT>" --tool gemini --mode write --resume <id>  # specific
-maestro cli -p "<PROMPT>" --tool gemini --resume <id1>,<id2>     # merge multiple
+maestro delegate "<PROMPT>" --to gemini --resume              # last session
+maestro delegate "<PROMPT>" --to gemini --mode write --resume <id>  # specific
+maestro delegate "<PROMPT>" --to gemini --resume <id1>,<id2>     # merge multiple
 ```
 
 Resume auto-assembles previous conversation context. Warning emitted when context exceeds 32KB.
@@ -188,14 +206,13 @@ Resume auto-assembles previous conversation context. Warning emitted when contex
 ### Subcommands
 
 ```bash
-maestro cli show                     # recent 20 executions
-maestro cli show --all               # up to 100
-maestro cli output <id>              # assistant output (always shows status header)
-maestro cli output <id> --verbose    # include start/end timestamps
-maestro cli output <id> --tail 20    # last 20 lines of output
-maestro cli output <id> --lines 10   # alias for --tail
-maestro cli watch <id>               # stream output in real-time until completion
-maestro cli watch <id> --timeout 60000  # auto-exit after 60s
+maestro delegate show                     # recent 20 executions
+maestro delegate show --all               # up to 100
+maestro delegate output <id>              # assistant output
+maestro delegate output <id> --verbose    # include start/end timestamps
+maestro delegate status <id>              # broker + history + snapshot preview
+maestro delegate tail <id>                # recent events + history
+maestro delegate cancel <id>              # request cancellation
 ```
 </execution>
 
@@ -205,7 +222,7 @@ maestro cli watch <id> --timeout 60000  # auto-exit after 60s
 
 <execution>
 
-Proactively invoke `maestro cli` when these conditions are met — no user confirmation needed for `analysis` mode:
+Proactively invoke `maestro delegate` when these conditions are met — no user confirmation needed for `analysis` mode:
 
 | Trigger | Suggested Rule |
 |---------|---------------|

package/workflows/delegate-usage.md

@@ -1,7 +1,7 @@
 # Delegate Execution Specification
 
 <purpose>
-Unified reference for `maestro delegate` — synchronous task delegation with broker-managed lifecycle, message injection, and MCP notifications. Superset of `maestro cli` with cancellation and message chaining.
+Unified reference for `maestro delegate` — synchronous task delegation with broker-managed lifecycle, message injection, and MCP notifications.
 </purpose>
 
 **References**: `~/.maestro/cli-tools.json` (tool config), `~/.maestro/templates/cli/` (protocol + prompt templates)
@@ -87,7 +87,7 @@ With MCP connected, all delegate tools are available programmatically.
 
 ### Assembly Order
 
-`maestro delegate` builds the final prompt identically to `maestro cli`:
+`maestro delegate` builds the final prompt as:
 
 1. **Mode protocol** — `~/.maestro/templates/cli/protocols/{mode}-protocol.md`
 2. **User prompt** — the positional `"<PROMPT>"` value
@@ -243,7 +243,7 @@ All subcommands are also available as MCP tools for programmatic access:
 
 ### Snapshot & Preview
 
-`delegate status` includes a `Preview:` field showing the agent's latest output — built from `assistant_message`, `tool_use` completions, and `file_change` events. This serves the same purpose as `maestro cli watch` without requiring real-time streaming.
+`delegate status` includes a `Preview:` field showing the agent's latest output — built from `assistant_message`, `tool_use` completions, and `file_change` events.
 
 ### Job Lifecycle
 

package/workflows/issue-analyze.md

@@ -1,5 +1,9 @@
 # Workflow: Issue Analysis
 
+> **DEPRECATED**: This workflow was used by the deleted `manage-issue-analyze` command.
+> Use `maestro-analyze --gaps [ISS-ID]` instead, which integrates issue root cause analysis
+> into the unified analyze pipeline. See `~/.maestro/workflows/issue-gaps-analyze.md`.
+
 Root cause analysis for a specific issue using CLI exploration and codebase context gathering.
 
 ## Input
@@ -87,7 +91,7 @@ Root cause analysis for a specific issue using CLI exploration and codebase cont
 ```
 1. Build analysis prompt:
 
-   maestro cli -p "PURPOSE: Root cause analysis for issue {ISS-ID}: {ISSUE.title}
+   maestro delegate "PURPOSE: Root cause analysis for issue {ISS-ID}: {ISSUE.title}
    Identify the root cause, assess impact, and suggest an approach.
 
    ISSUE DETAILS:
@@ -116,7 +120,7 @@ Root cause analysis for a specific issue using CLI exploration and codebase cont
      confidence: 'high'|'medium'|'low',
      suggested_approach: string (actionable fix direction)
    CONSTRAINTS: Only cite evidence found in codebase, no speculation
-   " --tool {TOOL} --mode analysis
+   " --to {TOOL} --mode analysis
 
 2. Parse CLI output:
    - Extract JSON object from response

package/workflows/issue-discover.md

@@ -115,7 +115,7 @@ Batch 2: scalability, ux, accessibility, compliance
 
 For each perspective, launch a CLI analysis:
 
-  maestro cli -p "PURPOSE: Discover {PERSPECTIVE} issues in the codebase.
+  maestro delegate "PURPOSE: Discover {PERSPECTIVE} issues in the codebase.
   Focus: {FOCUS_AREA}
   Guiding question: {QUESTION}
 
@@ -130,7 +130,7 @@ For each perspective, launch a CLI analysis:
   EXPECTED: JSON array of findings, each with:
     title, severity, description, location (file:line), fix_direction, affected_components[]
   CONSTRAINTS: Only report real issues with evidence, no speculative findings
-  " --tool gemini --mode analysis
+  " --to gemini --mode analysis
 
 Store results per perspective in:
   .workflow/issues/discoveries/{SESSION_ID}/{PERSPECTIVE}-findings.json
@@ -262,7 +262,7 @@ For each unique finding:
 ```
 Use Gemini CLI to decompose the user prompt into exploration dimensions:
 
-  maestro cli -p "PURPOSE: Decompose this issue discovery prompt into 3-5 specific exploration dimensions.
+  maestro delegate "PURPOSE: Decompose this issue discovery prompt into 3-5 specific exploration dimensions.
 
   User wants to find: {USER_PROMPT}
 
@@ -280,7 +280,7 @@ Use Gemini CLI to decompose the user prompt into exploration dimensions:
       file_patterns: string[],
       finding_criteria: string
     }]
-  " --tool gemini --mode analysis
+  " --to gemini --mode analysis
 
 Store dimensions in:
   .workflow/issues/discoveries/{SESSION_ID}/exploration-plan.json

package/workflows/issue-execute.md

@@ -1,5 +1,8 @@
 # Workflow: Issue Execution
 
+> **DEPRECATED**: This workflow was used by the deleted `manage-issue-execute` command.
+> Use `maestro-execute` instead, which handles wave-based execution with automatic issue status sync.
+
 Execute a planned solution for an issue via dual-mode agent dispatch (server or direct CLI).
 
 ## Input
@@ -182,8 +185,8 @@ If SERVER_UP == false (or server dispatch failed):
        }
    - Rewrite file
 
-3. Execute via CLI:
-   maestro cli -p "{EXEC_PROMPT}" --tool {CLI_TOOL} --mode write
+3. Execute via delegate:
+   maestro delegate "{EXEC_PROMPT}" --to {CLI_TOOL} --mode write
 
 4. Evaluate result:
    - If CLI exits successfully → EXEC_SUCCESS = true
@@ -274,7 +277,7 @@ If execution failed:
 ## Output
 
 - **Updated**: `.workflow/issues/issues.jsonl` -- issue status transitions (open -> in_progress -> resolved/open)
-- **Execution modes**: Server dispatch (POST /api/execution/dispatch) or Direct CLI (maestro cli --mode write)
+- **Execution modes**: Server dispatch (POST /api/execution/dispatch) or Direct delegate (maestro delegate --mode write)
 
 ## Quality Criteria
 

package/workflows/issue-plan.md

@@ -1,5 +1,8 @@
 # Workflow: Issue Planning
 
+> **DEPRECATED**: This workflow was used by the deleted `manage-issue-plan` command.
+> Use `maestro-plan --gaps` instead, which generates TASK files linked to issues via `task_refs`.
+
 Solution planning for a specific issue with codebase-aware step generation and prompt template construction.
 
 ## Input
@@ -91,7 +94,7 @@ Solution planning for a specific issue with codebase-aware step generation and p
 ```
 1. Build planning prompt:
 
-   maestro cli -p "PURPOSE: Generate a step-by-step solution plan for issue {ISS-ID}: {ISSUE.title}
+   maestro delegate "PURPOSE: Generate a step-by-step solution plan for issue {ISS-ID}: {ISSUE.title}
    Produce an actionable, ordered list of implementation steps.
 
    ISSUE DETAILS:
@@ -116,7 +119,7 @@ Solution planning for a specific issue with codebase-aware step generation and p
      context: string (approach summary),
      promptTemplate: string (execution prompt for the agent)
    CONSTRAINTS: Steps must be concrete and file-specific, not vague
-   " --tool {TOOL} --mode analysis
+   " --to {TOOL} --mode analysis
 
 2. Parse CLI output:
    - Extract JSON object from response