maestro-flow 0.3.26 → 0.3.28

package/.claude/commands/maestro.md

@@ -11,6 +11,7 @@ allowed-tools:
   - Grep
   - Agent
   - AskUserQuestion
+  - TodoWrite
 ---
 <purpose>
 Orchestrate all maestro commands automatically based on user intent and current project state.
@@ -28,7 +29,7 @@ Executes commands sequentially with artifact propagation between steps.
 
 <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-chain-execute.md](~/.maestro/workflows/maestro-chain-execute.md) — read when dispatching chain execution (Step 4) or resume mode
 - [maestro-super.md](~/.maestro/workflows/maestro-super.md) — read when `--super` flag is active
 </deferred_reading>
 
@@ -83,12 +84,10 @@ When `-y` is active, maestro propagates auto flags to downstream commands. Only
 Commands not listed (manage-*, spec-*, milestone-*) have no auto flags and execute as-is.
 
 In auto mode, maestro also:
-- Skips its own clarification (Step 4)
-- Skips chain confirmation (Step 5d)
+- Skips intent clarification (workflow Step 2d)
+- Skips chain confirmation (workflow Step 3d)
 - Auto-skips on step errors (retry once, then skip and continue)
 
-Context cleanup hints, context window reminders, and completion report format are defined in workflow maestro.md (Steps 7a-1, 7f).
-
 **Super mode (`--super`):** Read `maestro-super.md` from deferred_reading, then follow it completely.
 </execution>
 

package/.codex/skills/maestro/SKILL.md

@@ -129,10 +129,24 @@ After each barrier skill completes, read its artifacts and update `state.context
 }
 ```
 
+7. **Initialize plan tracking** (dual-track: status.json + update_plan):
+
+```
+functions.update_plan({
+  plan: steps.map((step, i) => ({
+    id: `step-${i}`,
+    title: `[${i + 1}/${steps.length}] ${step.skill}${barrier(step) ? ' [BARRIER]' : ''}`,
+    status: "open"
+  }))
+})
+```
+
 **`--dry-run`**: Display chain with `[BARRIER]` markers, stop.
 
 **User confirmation** (skip if AUTO_YES): Display plan, prompt `Proceed? (yes/no)`.
 
+**`--continue` plan rebuild**: When resuming, rebuild `update_plan` from status.json — completed steps → `"completed"`, current → `"in_progress"`, rest → `"open"`.
+
 ### Phase 2: Wave Execution Loop
 
 **While pending steps remain**, increment `waveNum` and repeat:
@@ -151,8 +165,21 @@ After each barrier skill completes, read its artifacts and update `state.context
    ```
 4. **Read results**: Update each step's `status`, `wave_n` from results CSV
 5. **Barrier check**: If wave was a barrier skill, run barrier analysis logic (read artifacts, update context)
-6. **Persist**: Append wave to `state.waves[]`, write `status.json`
-7. **Abort on failure**: If any result `status === 'failed'` → mark remaining steps `skipped`, set `state.status = 'aborted'`, break
+6. **Dual-track persist**:
+   - status.json: Append wave to `state.waves[]`, update step statuses, write `status.json`
+   - update_plan: Sync plan items from status.json step statuses:
+     ```
+     functions.update_plan({
+       plan: steps.map((step, i) => ({
+         id: `step-${i}`,
+         title: `[${i + 1}/${steps.length}] ${step.skill}`,
+         status: step.status === 'completed' ? 'completed'
+               : step.status === 'pending' && i === nextPendingIndex ? 'in_progress'
+               : step.status
+       }))
+     })
+     ```
+7. **Abort on failure**: If any result `status === 'failed'` → mark remaining steps `skipped` in both status.json and update_plan, set `state.status = 'aborted'`, break
 
 ### Skill Call Assembly
 
@@ -196,6 +223,10 @@ Object with all fields required: `status` ("completed"|"failed"), `skill_call` (
 
 ### Phase 3: Completion Report
 
+Finalize dual tracking:
+- status.json: `state.status = 'completed'`
+- update_plan: all steps → `"completed"` (skipped steps also marked completed)
+
 ```
 === COORDINATE COMPLETE ===
 Session:  <sessionId>

package/package.json

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

package/workflows/maestro-chain-execute.md

@@ -3,10 +3,11 @@
 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).
+Dual-track progress: status.json (persistence + resume) and TodoWrite (UI visibility).
 
 **Prerequisites:**
 - Session directory with valid status.json (status: "running", pending steps)
+- TodoWrite initialized by selection workflow (Step 3h) with `MAESTRO:{chain_name}:` prefix
 - $SESSION_PATH passed from maestro.md dispatch
 
 ## Step 1: Load Session
@@ -19,6 +20,18 @@ Set `$STEP_INDEX` = `current_step` (first pending step).
 
 Validate: `status == "running"` and at least one pending step exists.
 
+**TodoWrite sync (resume mode):** If TodoWrite has no `MAESTRO:{chain_name}:` entries (e.g., fresh context after `/maestro -c`), rebuild from status.json:
+
+```javascript
+const todos = steps.map((step, i) => ({
+  content: `MAESTRO:${chain_name}: [${i + 1}/${steps.length}] ${step.skill}`,
+  status: step.status === 'completed' ? 'completed'
+        : i === $STEP_INDEX ? 'in_progress'
+        : 'pending'
+}));
+TodoWrite({ todos });
+```
+
 Display banner:
 
 ```
@@ -41,9 +54,9 @@ context = {
   current_phase,    // from status.json.context or top-level phase
   user_intent,      // from status.json.context or top-level intent
   issue_id,
+  milestone_num,
   spec_session_id,
-  scratch_dir,
-  auto_mode         // from status.json.auto_mode
+  scratch_dir
 }
 ```
 
@@ -52,10 +65,11 @@ context = {
 ```
 1. Substitute placeholders in step.args:
    {phase} → context.current_phase
-   {description} → context.user_intent
+   {description} → context.user_intent (chainMap uses {description} as alias for user intent)
    {issue_id} → context.issue_id
    {spec_session_id} → context.spec_session_id
    {scratch_dir} → context.scratch_dir
+   {milestone_num} → context.milestone_num
 
 2. In auto_mode, append per-command flag if not already present:
    maestro-analyze / maestro-brainstorm / maestro-roadmap / maestro-ui-design → -y
@@ -72,22 +86,16 @@ For each step starting at `$STEP_INDEX`:
 
 ### 3a. Select engine & display banner
 
-Per-step engine selection:
+Read `step.engine` from status.json (pre-computed by selection workflow Step 3e).
 
+If `step.engine` is missing or null, fallback to auto 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.
+  CLI: maestro-plan, maestro-execute, maestro-analyze, maestro-brainstorm,
+       maestro-roadmap, maestro-ui-design, quality-refactor
+  Internal: everything else (current-session Skill() call)
 ```
 
-Display: `[Step {N}/{total}] /{cmd} [{engine}] — {args}`
+Display: `[Step {N}/{total}] /{step.skill} [{engine}] — {args}`
 
 Update status.json: step `status = "running"`, `engine`, `started_at`.
 
@@ -97,10 +105,10 @@ Context window hint:
 
 ### 3b. Execute (engine-dependent)
 
-**Skill engine** — invoke directly (synchronous, visible):
+**Internal engine** — current-session Skill() call (synchronous, visible):
 
 ```
-Skill({ skill: step.cmd, args: assembledArgs })
+Skill({ skill: step.skill, args: assembledArgs })
 ```
 
 **CLI engine** — template-driven, async, context-isolated:
@@ -132,19 +140,39 @@ 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.
+### 3d. Handle result & sync dual tracking
+
+**Success:**
+1. status.json: mark step `status = "completed"`, set `completed_at`
+2. TodoWrite: mark current step `completed`, next step `in_progress`
+3. CLI: save output to `step-{N}-output.txt` in session directory
+
+```javascript
+// Dual-track update after each step
+function updateDualTracking(stepIndex, total, chain_name, result) {
+  // 1. status.json — already updated in 3c
+  // 2. TodoWrite — sync UI
+  const todos = getAllTodos().map(todo => {
+    if (!todo.content.startsWith(`MAESTRO:${chain_name}:`)) return todo;
+    const num = extractStepNum(todo.content);
+    if (num === stepIndex + 1) return { ...todo, status: result };
+    if (num === stepIndex + 2 && result === 'completed') return { ...todo, status: 'in_progress' };
+    return todo;
+  });
+  TodoWrite({ todos });
+}
+```
 
 **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`.
+1. status.json: mark step `"failed"` or `"skipped"`
+2. TodoWrite: mark step `completed` (skipped) or keep `in_progress` (retry)
+3. `auto_mode` → retry once, then skip
+4. Interactive → offer: Retry (max 2) / Skip / Abort
+5. Abort → status.json `status = "aborted"`, TodoWrite mark remaining `pending`, display resume hint: `/maestro -c`
 
 ### 3e. Post-step analysis (CLI steps only)
 
-Skip if: step failed/skipped, or `engine == 'skill'`.
+Skip if: step failed/skipped, or `engine == 'internal'`.
 
 Delegate to gemini (analysis mode, `--resume` if `gemini_session_id` exists) with prompt containing:
 - Step command, args, chain name, intent
@@ -181,7 +209,9 @@ On callback:
 
 ## Step 4: Completion Report
 
-Update status.json: `status = "completed"`.
+Finalize dual tracking:
+1. status.json: `status = "completed"`
+2. TodoWrite: all steps marked `completed` (or `completed` for skipped)
 
 ```
 ============================================================
@@ -194,8 +224,8 @@ Update status.json: `status = "completed"`.
 
   Results:
     [✓] 1. maestro-plan — completed [cli] (quality: 85/100)
-    [✓] 2. maestro-verify — completed [skill]
-    [—] 3. quality-review — skipped [skill]
+    [✓] 2. maestro-verify — completed [internal]
+    [—] 3. quality-review — skipped [internal]
 
   CLI Avg Quality: {avgScore}/100 (based on {cliStepCount} cli steps)
 

package/workflows/maestro.codex.md

@@ -290,8 +290,8 @@ Build context: `{ current_phase, user_intent, issue_id, spec_session_id: null, s
 
 ```
 MAESTRO-COORDINATE: {chain_name}  (dry run)
-  1. ${step.cmd} {step.args}
-  2. ${step.cmd} {step.args}
+  1. ${step.skill} {step.args}
+  2. ${step.skill} {step.args}
   …
 ```
 
@@ -310,7 +310,7 @@ Create session directory `.workflow/.maestro/maestro-{timestamp}/`.
 
 **Auto-flag injection** (when AUTO_YES): `maestro-analyze/-brainstorm/-roadmap/-ui-design` → `-y`, `maestro-plan` → `--auto`, `quality-test` → `--auto-fix`, `quality-retrospective` → `--auto-yes`.
 
-Initialize `state.json` with: session_id, intent, chain_name, auto_yes, context (phase, dirs, issue_id, gaps), waves[], and steps[] (each with index, cmd, args, status=pending).
+Initialize `state.json` with: session_id, intent, chain_name, auto_yes, context (phase, dirs, issue_id, gaps), waves[], and steps[] (each with index, skill, args, status=pending).
 
 ---
 

package/workflows/maestro.md

@@ -7,7 +7,7 @@ Default `auto` mode selects engine based on chain complexity.
 **Prerequisites:**
 - None for initial invocation (can bootstrap)
 - `continue`/`next`: `.workflow/state.json` must exist
-- `-c` (resume): `.workflow/.maestro/*/status.json` must exist
+- `-c` (resume): handled by command file before this workflow loads — not applicable here
 
 ## Step 1: Parse & Initialize
 
@@ -15,8 +15,8 @@ Default `auto` mode selects engine based on chain complexity.
 
 ```
 Parse $ARGUMENTS → extract flags, remainder is intent text.
-  Flags: autoYes (-y/--yes), resumeMode (-c/--continue), dryRun (--dry-run)
-  Valued: forcedChain (--chain X), execMode (--exec auto|cli|skill, default 'auto'), cliTool (--tool X, default 'claude')
+  Flags: autoYes (-y/--yes), dryRun (--dry-run)
+  Valued: execMode (--exec auto|cli|internal, default 'auto'), cliTool (--tool X, default 'claude')
   intent = arguments with all flags/valued options stripped, trimmed
 ```
 
@@ -51,9 +51,9 @@ Check `.workflow/state.json` existence.
 ============================================================
   MAESTRO COORDINATOR
 ============================================================
-  Mode:  {intent-based | state-based | resume}
+  Mode:  {intent-based | state-based}
   Auto:  {yes | no}
-  Exec:  {auto | cli | skill}
+  Exec:  {auto | cli | internal}
   Input: {intent or "continue"}
 ```
 
@@ -61,16 +61,13 @@ Check `.workflow/state.json` existence.
 
 ### 2a: Fast path — forced chain or exact match
 
-**Forced chain (`--chain`):**
-- Validate against known chains (see [Chain Reference](#chain-reference))
-- If valid: skip intent analysis, jump to **Step 3**
-- If invalid: display valid chains, ask user to choose
-
 **Exact-match keywords:**
 ```
 Keyword → taskType (skip to Step 3):
   continue/next/go/继续/下一步 → 'state_continue'
-  status/状态/dashboard → 'status'
+
+Short-circuit (execute immediately, no chain):
+  status/状态/dashboard → Skill({ skill: "manage-status" }). **End.**
 ```
 
 ### 2b: Structured intent extraction (LLM-native)
@@ -160,7 +157,7 @@ Route priority:
   test:       feature/code→test; default→test
   debug:      default→debug
   refactor:   default→refactor
-  manage:     issue→issue, milestone→milestone_audit, phase→milestone_close, memory→memory, doc→sync, codebase→codebase_refresh, config→spec_setup, team→team_coordinate; default→status
+  manage:     issue→issue, milestone→milestone_audit, phase→milestone_close, memory→knowhow, doc→sync, codebase→codebase_refresh, config→spec_setup, team→team_coordinate; default→status
   transition: phase→milestone_close, milestone→milestone_complete; default→milestone_close
   continue:   default→state_continue
   sync:       doc→sync, codebase→codebase_refresh; default→sync
@@ -187,10 +184,9 @@ Display intent analysis: action, object, scope, issue_id, phase_ref, task_type,
 ### 3a: Map task_type → chain
 
 **Resolution order:**
-1. `forcedChain` → `chainMap[forcedChain]`
-2. `state_continue` → `detectNextAction(projectState)` → `{ chain, argsOverride? }`. Apply argsOverride before template substitution.
-3. Task-type aliases → named chain: `spec_generate`→`spec-driven`, `brainstorm`→`brainstorm-driven`, `issue_execute`→`issue-full`
-4. `chainMap[taskType]` → direct lookup
+1. `state_continue` → `detectNextAction(projectState)` → `{ chain, argsOverride? }`. Apply argsOverride before template substitution.
+2. Task-type aliases → named chain: `spec_generate`→`spec-driven`, `brainstorm`→`brainstorm-driven`, `issue_execute`→`issue-full`
+3. `chainMap[taskType]` → direct lookup
 
 Full `chainMap` and `detectNextAction` are in the [Reference Data](#reference-data) section.
 
@@ -228,21 +224,31 @@ When executing issue chains, replace `{issue_id}` in step args with resolved ID.
 
 **If `dryRun`:** Display chain visualization and exit.
 **If not `autoYes`:** Confirm with user — show numbered steps, offer: Execute / Execute from step N / Cancel.
+If user chooses "Execute from step N": set `$START_STEP = N` (used in 3f to set `current_step`).
 
 ### 3e: Step-level engine selection
 
-Engine is selected **per step**, not per chain.
+Engine is selected **per step**, not per chain. Pre-compute and write to each step's `engine` field in status.json (execution workflow reads this, does not re-compute).
 
 ```
-If execMode is 'cli' or 'skill' → force that engine for all steps.
+If execMode is 'cli' or 'internal' → 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 (everything else): observable, interactive, lightweight (verify, review, test, debug, milestone-*, manage-*, spec-*, quick, etc.)
+  Internal steps (everything else): current-session Skill() call — verify, review, test, debug, milestone-*, manage-*, spec-*, quick, etc.
 ```
 
-**Trade-off:** CLI = context isolation + template prompts + gemini analysis. Skill = direct visibility + synchronous + user can intervene.
+**Trade-off:** CLI = context isolation + template prompts + gemini analysis. Internal = current-session Skill() call, direct visibility + synchronous + user can intervene.
+
+### 3f: Low-complexity fast path (before session creation)
+
+If ALL conditions met:
+- clarity >= 2
+- task_type == `'quick'` or (action == `'create'` && object == `'feature'`)
+- NOT `state_continue`
 
-### 3f: Setup session
+Then: `Skill({ skill: "maestro-quick", args: '"{description}"' })`. **End.** (no session created, no status.json)
+
+### 3g: Setup session
 
 Create session directory `.workflow/.maestro/maestro-{YYYYMMDD-HHMMSS}/` and write `status.json`:
 ```json
@@ -262,32 +268,34 @@ Create session directory `.workflow/.maestro/maestro-{YYYYMMDD-HHMMSS}/` and wri
     "current_phase": "{resolved_phase}",
     "user_intent": "{original_intent}",
     "issue_id": "{resolved_issue_id or null}",
+    "milestone_num": "{current_milestone_num 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,
+  "steps": [{ "index": 0, "skill": "{chainMap[].cmd}", "args": "{chainMap[].args}", "engine": "{cli|internal from 3e}", "status": "pending", "started_at": null, "completed_at": null }],
+  "current_step": "{$START_STEP or 0}",
   "status": "running"
 }
 ```
 
-## Step 4: Dispatch
+### 3h: Initialize TodoWrite tracking
 
-### 4a: Low-complexity fast path
+Create TodoWrite entries with `MAESTRO:{chain_name}:` prefix for UI-visible progress tracking. TodoWrite and status.json form dual-track system — TodoWrite for user visibility, status.json for persistence and resume.
 
-If ALL conditions met:
-- clarity >= 2
-- task_type == `'quick'` or (action == `'create'` && object == `'feature'`)
-- NOT `forcedChain`, NOT `state_continue`
+```javascript
+const todos = steps.map((step, i) => ({
+  content: `MAESTRO:${chain_name}: [${i + 1}/${steps.length}] ${step.skill}`,
+  status: i === 0 ? 'in_progress' : 'pending'
+}));
+TodoWrite({ todos });
+```
 
-Then: `Skill({ skill: "maestro-quick", args: '"{description}"' })`. **End.**
+## Step 4: Dispatch to execution workflow
 
-### 4b: Standard execution — read and follow execution workflow
+status.json already created in Step 3g, TodoWrite initialized in Step 3h.
 
-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
+1. Read `~/.maestro/workflows/maestro-chain-execute.md`
+2. Follow it with `$SESSION_PATH` = session directory from Step 3g
 
 ---
 
@@ -476,8 +484,8 @@ detectNextAction(state):
 1. **Semantic Routing** — LLM-native `action × object` extraction; disambiguates "问题" by context
 2. **State-Aware** — Reads `.workflow/state.json` before routing
 3. **Quality Gates** — Issue chains auto-include review; `issue-full` is default for issue execution
-4. **Per-Step Engine** — Each step independently selects Skill or CLI. Heavy steps (plan, execute, analyze, brainstorm) → CLI for context isolation. Observable steps (verify, review, test, debug, manage-*) → Skill for direct visibility. `--exec cli|skill` forces all steps.
-5. **CLI Analysis Chain** — Gemini evaluates each CLI step's output, generates `next_step_hints` via `{{ANALYSIS_HINTS}}`. Skill steps skip analysis (output already visible). Sessions chained via `--resume`
+4. **Per-Step Engine** — Each step independently selects internal or CLI. Heavy steps (plan, execute, analyze, brainstorm) → CLI for context isolation. Observable steps (verify, review, test, debug, manage-*) → internal (current-session Skill()) for direct visibility. `--exec cli|internal` forces all steps.
+5. **CLI Analysis Chain** — Gemini evaluates each CLI step's output, generates `next_step_hints` via `{{ANALYSIS_HINTS}}`. Internal steps skip analysis (output already visible). Sessions chained via `--resume`
 6. **Phase Propagation** — Auto-detects and passes phase numbers to downstream commands
 7. **Auto Mode** — `-y` propagates through chain, skipping all confirmations
 8. **Resumable** — Session state in `.workflow/.maestro/` enables `-c` resume