maestro-flow 0.3.7 → 0.3.9

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/delegate-usage.md

@@ -1,7 +1,7 @@
 # Delegate Execution Specification
 
 <purpose>
-Unified reference for `maestro delegate` — async task delegation via detached worker processes, with broker-managed lifecycle, message injection, and MCP notifications. Superset of `maestro cli` with async execution, cancellation, and message chaining.
+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.
 </purpose>
 
 **References**: `~/.maestro/cli-tools.json` (tool config), `~/.maestro/templates/cli/` (protocol + prompt templates)
@@ -30,9 +30,7 @@ maestro delegate "<PROMPT>" [options]
 | `--id <id>` | Execution ID | Auto: `{prefix}-{HHmmss}-{rand4}` |
 | `--resume [id]` | Resume previous session (last if no id) | — |
 | `--includeDirs <dirs>` | Additional directories (comma-separated) | — |
-| `--session <id>` | MCP session ID for completion notifications | Auto-detected |
 | `--backend <type>` | Adapter backend: `direct` or `terminal` (tmux/wezterm) | `direct` |
-| `--async` | Run in background and return immediately | foreground |
 
 ### Mode Definition (Authoritative)
 
@@ -154,7 +152,7 @@ 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
-" --to gemini --mode analysis --rule analysis-assess-security-risks --cd "src/auth" --async
+" --to gemini --mode analysis --rule analysis-assess-security-risks --cd "src/auth"
 ```
 </context>
 
@@ -164,6 +162,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`
@@ -173,7 +189,7 @@ Format: `{prefix}-{HHmmss}-{rand4}` (e.g. `gem-143022-a7f2`)
 Output to stderr: `[MAESTRO_EXEC_ID=<id>]`
 
 ```bash
-maestro delegate "analyze code" --to gemini --async         # auto-ID: gem-143022-a7f2
+maestro delegate "analyze code" --to gemini                        # auto-ID: gem-143022-a7f2
 maestro delegate "fix bug" --to gemini --mode write --id my-task-1  # custom ID
 ```
 
@@ -246,14 +262,6 @@ queued → running → completed
 | `inject` | Routes to running worker stdin; non-interactive adapters auto cancel + relaunch | Supplementary context, course correction |
 | `after_complete` | Queues message; relaunches delegate with queued message on completion | Chained tasks, post-processing |
 
-### Notification Channels
-
-Delegate completion notifies the caller through dual channels:
-
-1. **MCP channel** (primary) — push notification with structured meta (exec_id, event_type, status)
-2. **Hook fallback** — JSONL file read by `delegate-monitor` PostToolUse hook
-
-Throttling: `status_update` at 10s, `snapshot` at 15s.
 </execution>
 
 ---
@@ -275,11 +283,10 @@ Proactively invoke `maestro delegate` when these conditions are met — no user
 ### Principles
 
 - Default `--mode analysis` (safe, read-only)
-- Use `--async` for non-blocking execution; await MCP notification for result
+- Always `Bash(run_in_background: true)` — stop immediately, wait for callback
 - Tool fallback: `gemini` → `qwen` → `codex`
 - Rule suggestions are guidelines — choose the best fit
 - Use `inject` for supplementary context mid-execution; `after_complete` for chained multi-step tasks
-- Check `delegate status` for snapshot preview instead of polling output
 </execution>
 
 ---
@@ -288,20 +295,15 @@ Proactively invoke `maestro delegate` when these conditions are met — no user
 
 <execution>
 
-### Launch → Monitor → Retrieve
-
-```bash
-maestro delegate "analyze auth module" --to gemini --async
-# → [MAESTRO_EXEC_ID=gem-143022-a7f2]
+### Basic Usage
 
-maestro delegate status gem-143022-a7f2
-# → status: running, Preview: "Found 3 potential injection points..."
-
-# Await MCP channel notification...
-# → [DELEGATE DONE] gem-143022-a7f2 gemini/analysis completed
-
-maestro delegate output gem-143022-a7f2
-# → full analysis result
+```
+Bash({
+  command: 'maestro delegate "analyze auth module" --to gemini',
+  run_in_background: true
+})
+// → STOP, wait for callback
+// → on callback: maestro delegate output <id>
 ```
 
 ### Inject Supplementary Context
@@ -311,20 +313,16 @@ maestro delegate message gem-143022-a7f2 "Also check src/utils/sanitize.ts"
 # → accepted: true, delivery: inject
 ```
 
-### Chain: Analyze → Auto-Fix
+### Chain: Analyze → Fix
 
-```bash
-maestro delegate "find SQL injection vulnerabilities" --to gemini --async
-maestro delegate message gem-143022-a7f2 "Fix all critical vulnerabilities" --delivery after_complete
-# → queued, auto-relaunches after analysis completes
 ```
-
-### Cancel → Redirect
-
-```bash
-maestro delegate cancel gem-143022-a7f2
-# → cancellation requested
-
-maestro delegate "analyze only the payment module" --to gemini --async
+Bash({
+  command: 'maestro delegate "find SQL injection vulnerabilities" --to gemini',
+  run_in_background: true
+})
+// → STOP, wait for callback
+// → on callback: chain next step
+maestro delegate message gem-143022-a7f2 "Fix all critical vulnerabilities" --delivery after_complete
+// → queued, relaunches after analysis completes
 ```
 </execution>