maestro-flow 0.3.25 → 0.3.26

package/.claude/commands/maestro.md

@@ -26,11 +26,9 @@ Produces session directory at `.workflow/.maestro/{session_id}/` with status.jso
 Executes commands sequentially with artifact propagation between steps.
 </purpose>
 
-<required_reading>
-@~/.maestro/workflows/maestro.md
-</required_reading>
-
 <deferred_reading>
+- [maestro.md](~/.maestro/workflows/maestro.md) — read at execution start (Steps 1-3: intent analysis, chain selection, session setup)
+- [maestro-chain-execute.md](~/.maestro/workflows/maestro-chain-execute.md) — read when dispatching chain execution (Step 4b) or resume mode (Step 1b)
 - [maestro-super.md](~/.maestro/workflows/maestro-super.md) — read when `--super` flag is active
 </deferred_reading>
 
@@ -56,7 +54,9 @@ $ARGUMENTS — user intent text, or special keywords.
 </context>
 
 <execution>
-Follow '~/.maestro/workflows/maestro.md' completely.
+**Resume mode (`-c`):** Skip selection workflow entirely — scan `.workflow/.maestro/` for latest session, then read `~/.maestro/workflows/maestro-chain-execute.md` and follow it with `$SESSION_PATH` = discovered session path. **End.**
+
+**Normal mode:** Read `~/.maestro/workflows/maestro.md` from deferred_reading, then follow it completely.
 
 **Auto mode (`-y`) propagation:**
 
@@ -111,11 +111,10 @@ Context cleanup hints, context window reminders, and completion report format ar
 - [ ] Per-step engine selected (auto routes heavy steps to CLI, observable steps to internal)
 - [ ] Auto flags correctly propagated to supporting commands only
 - [ ] Session directory created at .workflow/.maestro/{session_id}/
-- [ ] status.json tracks per-step progress and execution engine
-- [ ] All chain steps executed via internal or CLI delegate with proper argument propagation
+- [ ] status.json created with steps[], context, and tracking fields
+- [ ] Low-complexity intents routed to maestro-quick
+- [ ] All chains dispatched via execution workflow (maestro-chain-execute.md) with status.json tracking
 - [ ] Phase numbers auto-detected and passed to downstream commands
-- [ ] Error handling: retry/skip/abort per step (auto-skip in -y mode)
-- [ ] Session summary displayed on completion
 - [ ] (super mode) Requirements expanded and validated via Gemini before roadmap creation
 - [ ] (super mode) Each milestone scored ≥ 80% before advancing
 - [ ] (super mode) All milestones completed with no user intervention

package/package.json

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

package/workflows/maestro-chain-execute.md

@@ -0,0 +1,204 @@
+# Workflow: maestro-chain-execute
+
+Upgraded version of maestro's original direct execution strategy.
+Reads session status.json, loops through steps with per-step engine selection,
+context propagation, post-step Gemini analysis, and error handling.
+Tracks all progress via status.json (the JSON file created during selection).
+
+**Prerequisites:**
+- Session directory with valid status.json (status: "running", pending steps)
+- $SESSION_PATH passed from maestro.md dispatch
+
+## Step 1: Load Session
+
+Read status.json from `$SESSION_PATH`.
+
+Extract: `session_id`, `chain_name`, `steps[]`, `context`, `auto_mode`, `exec_mode`, `cli_tool`, `gemini_session_id`.
+
+Set `$STEP_INDEX` = `current_step` (first pending step).
+
+Validate: `status == "running"` and at least one pending step exists.
+
+Display banner:
+
+```
+============================================================
+  CHAIN EXECUTOR
+============================================================
+  Session: {session_id}
+  Chain:   {chain_name}
+  Steps:   {completed}/{total} done, starting from step {$STEP_INDEX}
+  Auto:    {auto_mode}
+  Exec:    {exec_mode}
+```
+
+## Step 2: Context & Argument Assembly
+
+Initialize context object from `status.json.context`:
+
+```
+context = {
+  current_phase,    // from status.json.context or top-level phase
+  user_intent,      // from status.json.context or top-level intent
+  issue_id,
+  spec_session_id,
+  scratch_dir,
+  auto_mode         // from status.json.auto_mode
+}
+```
+
+### assembleArgs(step)
+
+```
+1. Substitute placeholders in step.args:
+   {phase} → context.current_phase
+   {description} → context.user_intent
+   {issue_id} → context.issue_id
+   {spec_session_id} → context.spec_session_id
+   {scratch_dir} → context.scratch_dir
+
+2. In auto_mode, append per-command flag if not already present:
+   maestro-analyze / maestro-brainstorm / maestro-roadmap / maestro-ui-design → -y
+   maestro-plan → --auto
+   quality-test → --auto-fix
+   quality-retrospective → --auto-yes
+
+3. Shell-escape strings with single quotes for CLI delegate calls.
+```
+
+## Step 3: Step Loop
+
+For each step starting at `$STEP_INDEX`:
+
+### 3a. Select engine & display banner
+
+Per-step engine selection:
+
+```
+If exec_mode is 'cli' or 'skill' → force that engine for all steps.
+
+In 'auto' mode, select per step:
+  CLI steps (heavy, context-isolated):
+    maestro-plan, maestro-execute, maestro-analyze, maestro-brainstorm,
+    maestro-roadmap, maestro-ui-design, quality-refactor
+
+  Skill steps (observable, interactive, lightweight):
+    everything else — verify, review, test, debug, milestone-*,
+    manage-*, spec-*, quick, etc.
+```
+
+Display: `[Step {N}/{total}] /{cmd} [{engine}] — {args}`
+
+Update status.json: step `status = "running"`, `engine`, `started_at`.
+
+Context window hint:
+- Step >= 4 and not autoYes: hint user about `/maestro -c` for fresh context resume.
+- autoYes and step >= 5: log warning to status.json.
+
+### 3b. Execute (engine-dependent)
+
+**Skill engine** — invoke directly (synchronous, visible):
+
+```
+Skill({ skill: step.cmd, args: assembledArgs })
+```
+
+**CLI engine** — template-driven, async, context-isolated:
+
+```
+1. Load template ~/.maestro/templates/cli/prompts/coordinate-step.txt
+2. Build analysisHints from previous step's next_step_hints
+   (prompt_additions, cautions, context_to_carry)
+3. Substitute template placeholders:
+   {{COMMAND}}, {{ARGS}}, {{STEP_N}}, {{AUTO_DIRECTIVE}},
+   {{CHAIN_NAME}}, {{ANALYSIS_HINTS}}
+4. Run:
+   Bash(maestro delegate "<prompt>" --to {cli_tool} --mode write,
+        run_in_background: true, timeout: 600000)
+5. **STOP** — wait for background callback
+```
+
+### 3c. Parse output & update context
+
+Scan step output for context propagation:
+
+```
+PHASE: N         → context.current_phase
+SPEC-xxx         → context.spec_session_id
+scratch_dir: path → context.scratch_dir
+```
+
+CLI: capture `exec_id` from stderr `[MAESTRO_EXEC_ID=<id>]`.
+
+**Persist context back to status.json** after each step — write updated `context` field and `current_step`. This enables resume via `/maestro -c`.
+
+### 3d. Handle result
+
+**Success:** mark step `status = "completed"`, set `completed_at` in status.json.
+CLI: save output to `step-{N}-output.txt` in session directory.
+
+**Failure:**
+- `auto_mode` → retry once, then skip (mark `"skipped"`).
+- Interactive → offer: Retry (max 2) / Skip / Abort.
+- Abort → **Error E003** — update status.json `status = "aborted"`, display resume hint: `/maestro -c`.
+
+### 3e. Post-step analysis (CLI steps only)
+
+Skip if: step failed/skipped, or `engine == 'skill'`.
+
+Delegate to gemini (analysis mode, `--resume` if `gemini_session_id` exists) with prompt containing:
+- Step command, args, chain name, intent
+- Last 200 lines of step output
+- Next step info (command, args) if any
+
+Expected JSON response:
+
+```json
+{
+  "quality_score": "<0-100>",
+  "execution_assessment": {
+    "success": "<bool>",
+    "completeness": "<full|partial|minimal>",
+    "key_outputs": [],
+    "missing_outputs": []
+  },
+  "issues": [
+    { "severity": "critical|high|medium|low", "description": "" }
+  ],
+  "next_step_hints": {
+    "prompt_additions": "<extra context for next step>",
+    "cautions": ["<things to watch out for>"],
+    "context_to_carry": "<key facts from this step>"
+  },
+  "step_summary": ""
+}
+```
+
+On callback:
+1. Capture gemini `exec_id` → store as `gemini_session_id` in status.json for session continuity.
+2. Store analysis in `step_analyses[]` and `step-{N}-analysis.json` in session directory.
+3. Advance to next step (**3a**).
+
+## Step 4: Completion Report
+
+Update status.json: `status = "completed"`.
+
+```
+============================================================
+  MAESTRO SESSION COMPLETE
+============================================================
+  Session:  {session_id}
+  Chain:    {chain_name}
+  Steps:    {completed}/{total} completed
+  Phase:    {context.current_phase}
+
+  Results:
+    [✓] 1. maestro-plan — completed [cli] (quality: 85/100)
+    [✓] 2. maestro-verify — completed [skill]
+    [—] 3. quality-review — skipped [skill]
+
+  CLI Avg Quality: {avgScore}/100 (based on {cliStepCount} cli steps)
+
+  Next: /maestro continue | /manage-status
+============================================================
+```

package/workflows/maestro.md

@@ -20,16 +20,7 @@ Parse $ARGUMENTS → extract flags, remainder is intent text.
   intent = arguments with all flags/valued options stripped, trimmed
 ```
 
-### 1b: Handle resume mode
-
-If `resumeMode`:
-1. Scan `.workflow/.maestro/` for latest session (or session ID if specified)
-2. Read `status.json` → find last completed step, remaining steps
-3. Set `$CHAIN` from status.json, `$STEP_INDEX` = last_completed + 1
-4. If no session found: **Error E004** — list available sessions
-5. Jump to **Step 4** at resume point
-
-### 1c: Read project state
+### 1b: Read project state
 
 Check `.workflow/state.json` existence.
 
@@ -54,7 +45,7 @@ Check `.workflow/state.json` existence.
 
 **If missing:** `$PROJECT_STATE = { initialized: false }`. If intent also empty → **Error E001** (suggest `maestro-init`).
 
-### 1d: Display banner
+### 1c: Display banner
 
 ```
 ============================================================
@@ -267,105 +258,36 @@ Create session directory `.workflow/.maestro/maestro-{YYYYMMDD-HHMMSS}/` and wri
   "cli_tool": "{cliTool}",
   "gemini_session_id": null,
   "step_analyses": [],
+  "context": {
+    "current_phase": "{resolved_phase}",
+    "user_intent": "{original_intent}",
+    "issue_id": "{resolved_issue_id or null}",
+    "spec_session_id": null,
+    "scratch_dir": null
+  },
   "steps": [{ "index": 0, "skill": "{cmd}", "args": "{args}", "engine": null, "status": "pending", "started_at": null, "completed_at": null }],
   "current_step": 0,
   "status": "running"
 }
 ```
 
-## Step 4: Execute Chain
-
-### Shared: context & argument assembly
-
-```
-Context object tracks: current_phase, user_intent, issue_id, spec_session_id, scratch_dir, auto_mode.
-
-assembleArgs: substitute placeholders {phase}, {description}, {issue_id}, {spec_session_id}, {scratch_dir} in step.args.
-  In auto_mode, append per-command flag if not already present:
-    maestro-analyze/brainstorm/roadmap/ui-design → -y
-    maestro-plan → --auto
-    quality-test → --auto-fix
-    quality-retrospective → --auto-yes
-
-Shell-escape strings with single quotes for CLI delegate calls.
-```
-
-### Step loop — for each step starting at `$STEP_INDEX` (default 0):
-
-**4a. Select engine & display banner:**
-
-Select engine per step (see 3e). Display step banner with index, command name, engine, args.
-- Step >= 4 and not autoYes: hint user about `/maestro -c` for fresh context resume.
-- autoYes and step >= 5: log warning to status.json.
-- Update status.json: step status = `"running"`, engine, started_at.
-
-**4b. Execute (engine-dependent):**
-
-**Skill** — invoke `Skill({ skill: step.cmd, args: assembledArgs })` directly (synchronous, visible).
-
-**CLI** — template-driven, async, context-isolated:
-1. Load template `~/.maestro/templates/cli/prompts/coordinate-step.txt`
-2. Build `analysisHints` from previous step's `next_step_hints` (prompt_additions, cautions, context_to_carry)
-3. Substitute template placeholders: `{{COMMAND}}`, `{{ARGS}}`, `{{STEP_N}}`, `{{AUTO_DIRECTIVE}}`, `{{CHAIN_NAME}}`, `{{ANALYSIS_HINTS}}`
-4. Run `maestro delegate <prompt> --to {cliTool} --mode write` via `Bash(run_in_background: true, timeout: 600000)`
-5. **STOP** — wait for background callback
-
-**4c. Parse output & update context:**
-
-Scan step output for context propagation: `PHASE: N` → current_phase, `SPEC-xxx` → spec_session_id, `scratch_dir: path` → scratch_dir. CLI: capture exec_id from stderr.
-
-**4d. Handle result:**
-
-Success: mark `"completed"` in status.json. CLI: save output to `step-{N}-output.txt`.
-Failure: autoYes → retry once then skip. Interactive → Retry (max 2) / Skip / Abort. Abort → **Error E003** with resume hint.
-
-**4e. Post-step analysis (CLI steps only, multi-step chains):**
-
-Skip if: step failed/skipped, single-step chain, or `stepEngine === 'skill'`.
-
-Delegate to gemini (analysis mode, `--resume` if prior gemini_session_id exists) with prompt containing:
-- Step command, args, chain name, intent
-- Last 200 lines of step output
-- Next step info (if any)
-
-Expected JSON response:
-```json
-{
-  "quality_score": "<0-100>",
-  "execution_assessment": { "success": "<bool>", "completeness": "<full|partial|minimal>", "key_outputs": [], "missing_outputs": [] },
-  "issues": [{ "severity": "critical|high|medium|low", "description": "" }],
-  "next_step_hints": {
-    "prompt_additions": "<extra context for next step>",
-    "cautions": ["<things to watch out for>"],
-    "context_to_carry": "<key facts from this step>"
-  },
-  "step_summary": ""
-}
-```
-
-On callback: capture gemini exec_id for session continuity, store analysis in `state.step_analyses[]` and `step-{N}-analysis.json`, advance to next step (**4a**).
+## Step 4: Dispatch
 
-**4f. Completion report:**
+### 4a: Low-complexity fast path
 
-```
-============================================================
-  MAESTRO SESSION COMPLETE
-============================================================
-  Session:  {session_id}
-  Chain:    {chain_name}
-  Steps:    {completed}/{total} completed
-  Phase:    {current_phase}
+If ALL conditions met:
+- clarity >= 2
+- task_type == `'quick'` or (action == `'create'` && object == `'feature'`)
+- NOT `forcedChain`, NOT `state_continue`
 
-  Results:
-    [✓] 1. maestro-plan — completed [cli] (quality: 85/100)
-    [✓] 2. maestro-verify — completed [skill]
-    [—] 3. quality-review — skipped [skill]
+Then: `Skill({ skill: "maestro-quick", args: '"{description}"' })`. **End.**
 
-  CLI Avg Quality: {avgScore}/100 (based on {cliStepCount} cli steps)
+### 4b: Standard execution — read and follow execution workflow
 
-  Next: /maestro continue | /manage-status
-============================================================
-```
+For ALL chains (regardless of step count):
+1. status.json already created in Step 3f with `steps[]` and `context`
+2. Read `~/.maestro/workflows/maestro-chain-execute.md`
+3. Follow it with `$SESSION_PATH` = session directory from Step 3f
 
 ---