maestro-flow 0.3.8 → 0.3.10

package/dist/src/utils/get-version.js

@@ -12,10 +12,21 @@ let cached = null;
 export function getPackageVersion() {
     if (cached)
         return cached;
-    // Compiled JS lives at dist/src/utils/get-version.js → 4 levels up to project root
-    const pkgRoot = resolve(fileURLToPath(import.meta.url), '..', '..', '..', '..');
-    const pkg = JSON.parse(readFileSync(resolve(pkgRoot, 'package.json'), 'utf-8'));
-    cached = pkg.version ?? '0.0.0';
+    // Walk up from this file until we find a package.json with "maestro" in it
+    let dir = resolve(fileURLToPath(import.meta.url), '..');
+    for (let i = 0; i < 8; i++) {
+        const pkgPath = resolve(dir, 'package.json');
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+            if (pkg.name === 'maestro-flow' || pkg.name === 'maestro') {
+                cached = pkg.version ?? '0.0.0';
+                return cached;
+            }
+        }
+        catch { /* not found, keep going up */ }
+        dir = resolve(dir, '..');
+    }
+    cached = '0.0.0';
     return cached;
 }
 //# sourceMappingURL=get-version.js.map

package/dist/src/utils/get-version.js.map

@@ -1 +1 @@
-{"version":3,"file":"get-version.js","sourceRoot":"","sources":["../../../src/utils/get-version.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,0EAA0E;AAC1E,8EAA8E;AAE9E,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,IAAI,MAAM,GAAkB,IAAI,CAAC;AAEjC;;;GAGG;AACH,MAAM,UAAU,iBAAiB;IAC/B,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAC1B,mFAAmF;IACnF,MAAM,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAChF,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC,OAAO,EAAE,cAAc,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;IAChF,MAAM,GAAI,GAAG,CAAC,OAAkB,IAAI,OAAO,CAAC;IAC5C,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"get-version.js","sourceRoot":"","sources":["../../../src/utils/get-version.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,0EAA0E;AAC1E,8EAA8E;AAE9E,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,IAAI,MAAM,GAAkB,IAAI,CAAC;AAEjC;;;GAGG;AACH,MAAM,UAAU,iBAAiB;IAC/B,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAC1B,2EAA2E;IAC3E,IAAI,GAAG,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC;IACxD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;QAC7C,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;YACvD,IAAI,GAAG,CAAC,IAAI,KAAK,cAAc,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBAC1D,MAAM,GAAI,GAAG,CAAC,OAAkB,IAAI,OAAO,CAAC;gBAC5C,OAAO,MAAM,CAAC;YAChB,CAAC;QACH,CAAC;QAAC,MAAM,CAAC,CAAC,8BAA8B,CAAC,CAAC;QAC1C,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAC3B,CAAC;IACD,MAAM,GAAG,OAAO,CAAC;IACjB,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maestro-flow",
-  "version": "0.3.8",
+  "version": "0.3.10",
   "description": "Workflow orchestration CLI with MCP endpoint support and extensible architecture",
   "type": "module",
   "imports": {

package/templates/cli/prompts/workflow-skill-conflict-patterns.txt

@@ -66,18 +66,18 @@ Document recurring conflict patterns across workflow sessions with resolutions.
 - Context packages: `.workflow/.archives/{session_id}/.process/context-package.json` (reference only)
 - Session lessons: `manifest.json` -> `archives[].lessons.challenges`
 
-## Conflict Identification (Use maestro cli)
+## Conflict Identification (Use maestro delegate)
 
 **Command Pattern**:
 ```bash
-maestro cli -p "
+maestro delegate "
 PURPOSE: Identify conflict patterns from workflow sessions
 TASK: • Extract conflicts from IMPL_PLAN and lessons • Group by type (architecture/dependencies/testing/performance) • Identify recurring patterns (same conflict in different sessions) • Link resolutions to specific sessions
 MODE: analysis
 CONTEXT: @.workflow/.archives/*/IMPL_PLAN.md @.workflow/.archives/manifest.json
 EXPECTED: Conflict patterns with frequency and resolution
 CONSTRAINTS: analysis=READ-ONLY
-" --tool gemini --mode analysis --rule workflow-skill-aggregation --cd .workflow/.archives
+" --to gemini --mode analysis --rule workflow-skill-aggregation --cd .workflow/.archives
 ```
 
 **Pattern Grouping**:

package/templates/cli/prompts/workflow-skill-lessons-learned.txt

@@ -62,18 +62,18 @@ Aggregate lessons learned from workflow sessions, categorized by functional doma
 - Lessons: `manifest.json` -> `archives[].lessons.{successes|challenges|watch_patterns}`
 - Session metadata: `.workflow/.archives/{session_id}/workflow-session.json`
 
-## Aggregation Rules (Use maestro cli)
+## Aggregation Rules (Use maestro delegate)
 
 **Command Pattern**:
 ```bash
-maestro cli -p "
+maestro delegate "
 PURPOSE: Aggregate workflow lessons from session data
 TASK: • Group successes by functional domain • Categorize challenges by severity (HIGH/MEDIUM/LOW) • Identify watch patterns with frequency >= 2 • Mark CRITICAL patterns (3+ sessions)
 MODE: analysis
 CONTEXT: @.workflow/.archives/manifest.json
 EXPECTED: Aggregated lessons with frequency counts
 CONSTRAINTS: analysis=READ-ONLY
-" --tool gemini --mode analysis --rule workflow-skill-aggregation --cd .workflow/.archives
+" --to gemini --mode analysis --rule workflow-skill-aggregation --cd .workflow/.archives
 ```
 
 **Severity Classification**:

package/templates/config.json

@@ -49,5 +49,12 @@
     "doc_index": true,
     "auto_sync_after_execute": true,
     "action_log": true
+  },
+
+  "worktree": {
+    "enabled": true,
+    "root": ".worktrees",
+    "branch_prefix": "milestone/",
+    "auto_cleanup": true
   }
 }

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/templates/worktree-scope.json

@@ -0,0 +1,10 @@
+{
+  "worktree": true,
+  "milestone_num": "{{MILESTONE_NUMBER}}",
+  "milestone": "{{MILESTONE_NAME}}",
+  "owned_phases": [],
+  "main_worktree": "{{MAIN_WORKTREE_PATH}}",
+  "branch": "milestone/{{MILESTONE_SLUG}}",
+  "base_commit": "{{BASE_COMMIT}}",
+  "created_at": "{{TIMESTAMP}}"
+}

package/templates/worktrees.json

@@ -0,0 +1,27 @@
+{
+  "version": "1.0",
+  "worktrees": [
+    {
+      "milestone_num": "{{MILESTONE_NUMBER}}",
+      "milestone": "{{MILESTONE_NAME}}",
+      "slug": "{{MILESTONE_SLUG}}",
+      "branch": "milestone/{{MILESTONE_SLUG}}",
+      "path": "{{WORKTREE_ROOT}}/m{{MILESTONE_NUMBER}}-{{MILESTONE_SLUG}}",
+      "base_commit": "{{BASE_COMMIT}}",
+      "status": "active",
+      "created_at": "{{TIMESTAMP}}",
+      "owned_phases": [],
+      "fork_session": "{{FORK_SESSION_ID}}"
+    }
+  ],
+  "fork_sessions": [
+    {
+      "session_id": "fork-{{TIMESTAMP_SHORT}}",
+      "created_at": "{{TIMESTAMP}}",
+      "milestone_num": "{{MILESTONE_NUMBER}}",
+      "milestone": "{{MILESTONE_NAME}}",
+      "base_branch": "{{BASE_BRANCH}}",
+      "base_commit": "{{BASE_COMMIT}}"
+    }
+  ]
+}

package/workflows/analyze.md

@@ -41,29 +41,60 @@ Quick mode (-q):
 ## Arguments
 
 ```
-$ARGUMENTS: "<phase|topic> [-y] [-c] [-q]"
+$ARGUMENTS: "[phase|topic] [-y] [-c] [-q]"
 
-<phase>     -- Phase number (phase mode, operates within phase directory)
-<topic>     -- Topic text (scratch mode, creates scratch directory)
+(no args)   -- Milestone-wide analysis (requires init + roadmap)
+<phase>     -- Phase number (phase-scoped, requires init + roadmap)
+<topic>     -- Topic text (adhoc if milestone exists, standalone if not)
 -y / --yes  -- Auto mode, skip interactive scoping, auto-deepen
 -c / --continue -- Resume from existing session
 -q / --quick -- Quick mode, skip exploration + scoring, go straight to decision extraction
 ```
 
-## Dual-Mode Routing
-
-```
-IF $ARGUMENTS matches /^\d+$/
-  → Phase mode
-  → Resolve phase dir from state.json + roadmap
-  → Set OUTPUT_DIR = .workflow/phases/{NN}-{slug}/
-  → Update index.json: status → "exploring"
-
-ELSE
-  → Scratch mode
-  → Slugify topic (lowercase, hyphens, max 40 chars)
-  → Set OUTPUT_DIR = .workflow/scratch/analyze-{slug}-{date}/
-  → Create directory + index.json from scratch-index template (type="analyze")
+## Scope Routing
+
+```
+// Worktree scope check
+IF file_exists(".workflow/worktree-scope.json"):
+  scope = read(".workflow/worktree-scope.json")
+  IF $ARGUMENTS matches /^\d+$/ AND parseInt($ARGUMENTS) NOT IN scope.owned_phases:
+    ERROR "Phase {$ARGUMENTS} not owned by this worktree. Owned: {scope.owned_phases}"
+    EXIT
+
+// Auto-bootstrap state.json if missing
+IF NOT file_exists(".workflow/state.json"):
+  mkdir -p .workflow/scratch/
+  Write minimal state.json: { project: null, status: "active", current_milestone: null,
+    current_task_id: null, milestones: [], artifacts: [], last_updated: now() }
+
+// Scope determination
+IF $ARGUMENTS is empty:
+  IF state.json.current_milestone is non-null AND roadmap.md exists:
+    → scope = "milestone"
+    → milestone_slug = slugify(current_milestone name)
+    → Set OUTPUT_DIR = .workflow/scratch/analyze-{milestone_slug}-{date}/
+  ELSE:
+    → ERROR E001 "No args and no roadmap — provide topic text or create roadmap first"
+
+ELSE IF $ARGUMENTS matches /^\d+$/:
+  IF state.json.current_milestone is non-null AND roadmap.md exists:
+    → scope = "phase"
+    → phase_num = parsed number
+    → phase_slug = resolve from roadmap.md
+    → Set OUTPUT_DIR = .workflow/scratch/analyze-{phase_slug}-{date}/
+  ELSE:
+    → ERROR "Phase number requires init + roadmap"
+
+ELSE (text argument):
+  → topic_slug = slugify(text, max 40 chars)
+  IF state.json.current_milestone is non-null:
+    → scope = "adhoc"
+  ELSE:
+    → scope = "standalone"
+  → Set OUTPUT_DIR = .workflow/scratch/analyze-{topic_slug}-{date}/
+
+// Create output directory
+mkdir -p {OUTPUT_DIR}
 ```
 
 ## Output Structure
@@ -89,31 +120,23 @@ Parse $ARGUMENTS to determine mode and flags:
 - `-c` present: locate existing session folder (discussion.md exists), resume from last round
 - `-y` present: set AUTO_MODE=true
 - `-q` present: set QUICK_MODE=true (skip Steps 2-7, jump to Step 8: Decision Extraction)
-- Number (e.g., "3") = phase mode: resolve `.workflow/phases/{NN}-*/`, verify phase exists in roadmap
-- Text (e.g., "microservices vs monolith") = scratch mode: slugify topic, prepare scratch directory path
-- Missing/empty = error E001
+- Number (e.g., "3") = phase scope: resolve phase slug from roadmap, output to scratch/analyze-{phase-slug}-{date}/
+- Text (e.g., "microservices vs monolith") = adhoc/standalone scope: output to scratch/analyze-{slug}-{date}/
+- Missing/empty = milestone scope (if roadmap exists) or error E001
 
 **Session initialization:**
 - Session ID: `ANL-{slug}-{YYYY-MM-DD}`
-- Phase mode output: phase directory
-- Scratch mode output: `.workflow/scratch/analyze-{slug}-{date}/`
+- Output: `OUTPUT_DIR` (always under `.workflow/scratch/`)
 
-**Load prior context** (phase mode):
+**Load prior context** (milestone/phase scope):
 1. Read `.workflow/project.md` — project vision, constraints, Validated requirements (already shipped), Active requirements (current scope)
 2. Read `.workflow/roadmap.md` — phase structure and dependencies
-3. Read index.json in phase dir — goal, success_criteria
-4. Read `.brainstorming/guidance-specification.md` in phase dir (if exists) — detailed requirements, constraints, RFC 2119 decisions from brainstorm. Skip areas marked as MUST/MUST NOT (already locked).
-5. Read `.brainstorming/feature-index.json` in phase dir (if exists) — feature decomposition
-6. Read `brainstorm.md` in phase dir (if exists, legacy fallback, skip if guidance-specification.md loaded)
-7. Read `analysis.md` in phase dir (if exists, for continuation)
-8. Read `conclusions.json` in phase dir (if exists, for continuation)
-9. Read prior phases' `context.md` files — skip already-decided areas
-10. Read existing `context.md` in this phase (if exists, for continuation)
-11. Load project specs: `specs_content = maestro spec load --category planning`
-    Ensures analysis decisions don't conflict with existing architecture constraints.
-12. Read `.workflow/state.json` → `accumulated_context` (key_decisions, deferred items, blockers)
-
-**Load prior context** (scratch mode):
+3. Read `.workflow/state.json` → `current_milestone`, `artifacts[]`, `accumulated_context` (key_decisions, deferred items, blockers)
+4. Find prior analyze artifacts from `state.json.artifacts[]` where type=analyze and same milestone → load their `context.md` to skip already-decided areas
+5. Find brainstorm artifacts from `state.json.artifacts[]` where type=brainstorm and same milestone → load `guidance-specification.md` if exists
+6. Load project specs: `specs_content = maestro spec load --category planning`
+
+**Load prior context** (adhoc/standalone scope):
 1. Read `.workflow/project.md` (if exists) — project vision, Validated requirements, Active requirements, Key Decisions
 2. Read `.workflow/state.json` (if exists) → `accumulated_context` (key_decisions, deferred, blockers)
 3. Load project specs: `specs_content = maestro spec load --category planning`
@@ -571,6 +594,33 @@ IF deferred_items.length > 0:
   Print: "Created {deferred_items.length} deferred issues for tracking"
 ```
 
+### Step 8.8: Register Artifact
+
+```
+// Register in state.json artifact registry
+Read .workflow/state.json
+next_id = max(artifacts.filter(a => a.type == "analyze").map(a => parseInt(a.id.replace("ANL-","")))) + 1
+  // If no analyze artifacts exist: next_id = 1
+
+artifact = {
+  id: "ANL-{next_id padded to 3}",
+  type: "analyze",
+  milestone: state.json.current_milestone,  // null if standalone
+  phase: phase_num,                          // null if milestone/adhoc/standalone
+  scope: scope,                              // "milestone"|"phase"|"adhoc"|"standalone"
+  path: OUTPUT_DIR relative to .workflow/,   // e.g. "scratch/analyze-auth-2026-04-20"
+  status: "completed",
+  depends_on: null,
+  harvested: false,
+  created_at: session_start_time,
+  completed_at: now()
+}
+
+state.json.artifacts.push(artifact)
+state.json.last_updated = now()
+Write state.json (atomic: write tmp + rename)
+```
+
 ### Step 9: Report & Next Step
 
 Display summary:

package/workflows/brainstorm.md

@@ -47,8 +47,8 @@ Phase 3: Single Role Analysis → Detection → Context → Agent → Validation
 ## Input
 
 - `$ARGUMENTS`: topic text (auto mode) or role name (single role mode)
-- Phase mode: operates within `.workflow/phases/{NN}-{slug}/`
-- Scratch mode: creates `.workflow/scratch/brainstorm-{slug}-{date}/`
+- All output goes to `.workflow/scratch/brainstorm-{slug}-{date}/`
+- Registers artifact (type=brainstorm) in state.json on completion
 
 ### Parameters
 
@@ -80,32 +80,21 @@ Phase 3: Single Role Analysis → Detection → Context → Agent → Validation
 
 ### Directory Structure
 
-**Phase mode**:
-```
-.workflow/phases/{NN}-{slug}/
-├── brainstorm.md                        # Legacy simple output (if no session)
-├── index.json                           # Updated timestamps
-└── .brainstorming/                      # Full brainstorm session
-    ├── guidance-specification.md         # Phase 2 output
-    ├── feature-index.json               # Phase 4 output
-    ├── synthesis-changelog.md            # Phase 4 audit trail
-    ├── feature-specs/                   # Phase 4 feature specs
-    │   ├── F-001-{slug}.md
-    │   └── F-00N-{slug}.md
-    ├── {role}/                          # Phase 3 role analyses (immutable)
-    │   ├── {role}-context.md
-    │   ├── analysis.md
-    │   ├── analysis-cross-cutting.md
-    │   └── analysis-F-{id}-{slug}.md
-    └── synthesis-specification.md       # Non-feature mode fallback
-```
-
-**Scratch mode**:
+All brainstorm output goes to scratch:
 ```
 .workflow/scratch/brainstorm-{slug}-{date}/
-├── index.json                           # scratch-index template
-└── .brainstorming/                      # Same structure as phase mode
-    └── ...
+├── guidance-specification.md         # Phase 2 output
+├── feature-index.json               # Phase 4 output
+├── synthesis-changelog.md            # Phase 4 audit trail
+├── feature-specs/                   # Phase 4 feature specs
+│   ├── F-001-{slug}.md
+│   └── F-00N-{slug}.md
+├── {role}/                          # Phase 3 role analyses (immutable)
+│   ├── {role}-context.md
+│   ├── analysis.md
+│   ├── analysis-cross-cutting.md
+│   └── analysis-F-{id}-{slug}.md
+└── synthesis-specification.md       # Non-feature mode fallback
 ```
 
 ---
@@ -138,17 +127,8 @@ Parse $ARGUMENTS to determine execution mode:
 
 **Output Directory Resolution**:
 - Phase mode (number): `.workflow/phases/{NN}-{slug}/.brainstorming/`
-- Scratch mode (text): `.workflow/scratch/brainstorm-{slug}-{date}/.brainstorming/`
-- Existing session: use session's `.brainstorming/` directory
-
-**Archive previous brainstorming session** (Phase mode only, skip if `--session` or `--update`):
-```
-PARENT_DIR = parent of output directory (e.g., .workflow/phases/{NN}-{slug}/)
-IF directory exists "${PARENT_DIR}/.brainstorming" AND NOT --session AND NOT --update:
-  mkdir -p "${PARENT_DIR}/.history"
-  TIMESTAMP = current timestamp formatted as "YYYY-MM-DDTHH-mm-ss"
-  mv "${PARENT_DIR}/.brainstorming" "${PARENT_DIR}/.history/.brainstorming-${TIMESTAMP}"
-```
+- All output: `.workflow/scratch/brainstorm-{slug}-{date}/`
+- Existing session: use existing session directory
 
 ---
 

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