maestro-flow-one 0.1.2 → 0.2.0

package/README.md

@@ -2,37 +2,45 @@
 
 All 49 Maestro workflow commands as a single skill with dual-variant support (Codex + Claude Code).
 
+## Prerequisites
+
+Install [Maestro Flow](https://github.com/catlog22/maestro-flow) CLI first:
+
+```bash
+npm install -g maestro-flow
+```
+
 ## Install
 
 ```bash
 npm install -g maestro-flow-one
 ```
 
-> **Important:** The CLI must be globally installed (`maestro-flow` command available in PATH) to ensure delegate sessions can correctly invoke `/maestro-flow --cmd ...` during wave/step execution. Without global install, external steps and cross-command calls will fail.
+> **Important:** Both `maestro-flow` and `maestro-flow-one` must be globally installed to ensure delegate sessions can correctly invoke `/maestro-flow --cmd ...` during wave/step execution. Without global install, external steps and cross-command calls will fail.
 
 ### Install skill
 
 ```bash
-# Default: install both variants
+# Default: global install, both variants
 maestro-flow install
-#   .codex/skills/maestro-flow/  -> codex (spawn_agents_on_csv)
-#   .claude/skills/maestro-flow/ -> claude (Skill + delegate)
+#   ~/.codex/skills/maestro-flow/  -> codex (spawn_agents_on_csv)
+#   ~/.claude/skills/maestro-flow/ -> claude (Skill + delegate)
 
 # Single variant
-maestro-flow install --variant codex
-maestro-flow install --variant claude
+maestro-flow install --variant codex    # codex only -> ~/.codex/skills/
+maestro-flow install --variant claude   # claude only -> ~/.claude/skills/
 
-# Project-level (instead of global ~/.)
-maestro-flow install --project ./my-project
-maestro-flow install --variant codex --project .
+# Project-level install (instead of global)
+maestro-flow install --project .
+maestro-flow install --variant codex --project ./my-project
 ```
 
 ### Uninstall
 
 ```bash
-maestro-flow uninstall                        # Remove both from global
+maestro-flow uninstall                        # Remove both from global (~/)
 maestro-flow uninstall --variant codex        # Remove codex only
-maestro-flow uninstall --project .            # Remove from current project
+maestro-flow uninstall --project .            # Remove from current project only
 npm uninstall -g maestro-flow-one             # Remove global CLI
 ```
 

package/claude/maestro-flow/SKILL.md

@@ -30,11 +30,34 @@ Session path: `.workflow/.maestro/flow-{YYYYMMDD-HHmmss}/status.json`
 <context>
 $ARGUMENTS -- intent text, flags, or special keywords.
 
+**Skill directory structure** (relative to this SKILL.md):
+```
+maestro-flow/
+  SKILL.md              <- this file (router)
+  executor.md           <- step execution loop (deferred read)
+  commands/
+    lifecycle/          <- 17 commands: init, analyze, plan, execute, verify, ...
+    quality/            <- 7 commands: debug, review, test, auto-test, ...
+    manage/             <- 10 commands: status, issue, wiki, harvest, ...
+    learn/              <- 5 commands: decompose, follow, investigate, ...
+    milestone/          <- 3 commands: audit, complete, release
+    spec/               <- 4 commands: add, load, remove, setup
+    wiki/               <- 2 commands: connect, digest
+  chains/
+    templates.json      <- 14 chain templates + decision types
+```
+
 **State files:**
 - `.workflow/state.json` -- project artifact registry (optional)
 - `.workflow/.maestro/flow-*/status.json` -- flow session state
+
+**CLI prerequisite:** `maestro-flow` command must be globally available (`npm install -g maestro-flow-one`)
 </context>
 
+<deferred_reading>
+- [executor.md](executor.md) -- read when entering Phase 2 (step execution loop)
+</deferred_reading>
+
 <execution>
 
 ## Step 1: Parse & Route
@@ -59,9 +82,9 @@ Parse $ARGUMENTS:
     -> End.
 
   execute | continue
-    -> Find latest running flow session
-    -> If not found: "No running flow session." End.
-    -> Phase 2 (Step Execution Loop)
+    -> Read executor.md from deferred_reading
+    -> Follow executor.md completely
+    -> End.
 
   --chain <name> [-y] <remaining>
     -> Force chain selection, go to Step 4
@@ -134,98 +157,9 @@ Fall through to Phase 2.
 
 ## Phase 2: Step Execution Loop
 
-### 2.1: Load next step
-
-```
-Bash: maestro-flow next
-```
-
-Parse output:
-- `NO_SESSION` -> End.
-- `SESSION_COMPLETE` -> Display summary. End.
-- `STEP: idx/total` + `TYPE` + `SKILL` + `ARGS` + `PATH` + `---COMMAND---` -> continue
-
-### 2.2: Route by type
-
-```
-If TYPE == "decision" -> Step 2.3 (Decision Evaluation)
-If TYPE == "internal" -> Step 2.4 (Internal Execution)
-If TYPE == "external" -> Step 2.5 (External Execution)
-```
-
-### 2.3: Decision Evaluation
-
-**Quality-gate decisions** (post-verify, post-review, post-test, post-business-test):
-
-```
-Resolve artifact dir from .workflow/state.json
-
-Bash({
-  command: `maestro delegate "evaluate ${decision} quality gate
-CONTEXT: @${result_files}
----VERDICT---
-STATUS: proceed | fix | escalate
-REASON: one-line
-GAP_SUMMARY: details
-CONFIDENCE: high | medium | low
----END---" --role analyze --mode analysis`,
-  run_in_background: true
-})
-STOP -- wait for callback.
-```
-
-On callback: parse verdict, apply (proceed/fix-loop/escalate).
-
-**Structural decisions** (post-milestone): evaluate directly.
-
-After decision: `Bash: maestro-flow done` -> loop to 2.1.
+Read [executor.md](executor.md) from deferred_reading and follow it completely.
 
-### 2.4: Internal Execution
-
-The command content was loaded by `maestro-flow next` (after `---COMMAND---`).
-
-```
-1. Parse loaded command .md
-2. Set $ARGUMENTS = ARGS (with auto-flag if session.auto_mode)
-3. Follow <execution> section completely
-
-Auto flags: maestro-init -y, maestro-plan -y, maestro-execute -y,
-            quality-test -y --auto-fix, etc.
-
-On complete: Bash: maestro-flow done -> loop to 2.1
-On failure: -> Step 2.6
-```
-
-### 2.5: External Execution
-
-```
-Bash({
-  command: `maestro delegate --to claude "Execute: /maestro-flow --cmd {SKILL} {ARGS}" --mode write`,
-  run_in_background: true,
-  timeout: 600000
-})
-STOP -- wait for callback.
-
-On callback:
-  On success: Bash: maestro-flow done -> loop to 2.1
-  On failure: -> Step 2.6
-```
-
-### 2.6: Handle Failure
-
-```
-Auto mode: retry once (maestro-flow step {id} {idx} pending), then skip
-Interactive: AskUserQuestion retry/skip/abort
-```
-
----
-
-## Phase 3: Completion
-
-```
-Display session summary with step statuses.
-End.
-```
+Executor loop: `maestro-flow next` -> route by type -> execute -> `maestro-flow done` -> `Skill({ skill: "maestro-flow", args: "execute" })` until SESSION_COMPLETE.
 
 </execution>
 

package/claude/maestro-flow/executor.md

@@ -0,0 +1,328 @@
+# Flow Executor -- CLI-Driven Step Execution (Claude Variant)
+
+Single-step executor for flow sessions. Each invocation: `maestro-flow next` -> execute -> `maestro-flow done` -> self-invoke.
+
+**Core loop:**
+```
+maestro-flow next  ->  route by type  ->  execute  ->  maestro-flow done  ->  self-invoke
+```
+
+## Execution
+
+### Step 1: Load Next Step
+
+```
+Bash: maestro-flow next [session-id]
+
+Parse output lines:
+  "NO_SESSION"       -> "No running flow session." End.
+  "SESSION_COMPLETE" -> Display completion summary. End.
+  Otherwise parse structured output:
+    STEP: {idx}/{total}
+    TYPE: internal | external | decision
+    SKILL: {command-name}
+    ARGS: {arguments}
+    DECISION: {post-verify|post-review|...}   (decision only)
+    RETRY: {N}/{M}                             (decision only)
+    PATH: {/absolute/path/to/command.md}       (internal/external only)
+    ---COMMAND---
+    {full .md file content follows}
+```
+
+Display step banner:
+```
+------------------------------------------------------------
+  [{idx}/{total}] {SKILL} [{TYPE}]
+------------------------------------------------------------
+  Args: {ARGS}
+```
+
+Context weight hint (after 4+ completed steps):
+```
+Note: {completed} steps done. Use /maestro-flow execute in fresh context to resume.
+```
+
+### Step 2: Route by Type
+
+```
+TYPE == "decision"  -> Step 3 (Decision Evaluation)
+TYPE == "internal"  -> Step 4 (Internal Execution)
+TYPE == "external"  -> Step 5 (External Execution)
+```
+
+---
+
+### Step 3: Decision Evaluation
+
+#### 3.1: Parse decision metadata
+
+```
+decision_type = DECISION field    // e.g., "post-verify"
+retry_count / max_retries = from RETRY field
+```
+
+#### 3.2: Resolve artifact directory
+
+```
+Read .workflow/state.json
+Filter artifacts: milestone == session.milestone, phase == session.phase
+Sort by created_at DESC -> take first
+
+artifact_dir = .workflow/scratch/{artifact.path}/
+Fallback: glob .workflow/scratch/*-P{phase}-*/ sorted by date DESC
+```
+
+#### 3.3: Structural vs Quality-gate
+
+**Structural decisions (post-milestone)** -- evaluate directly:
+
+```
+post-milestone:
+  Read .workflow/state.json -> check next milestone (status "pending"/"active")
+  If found:
+    Read session status.json
+    Update: milestone, phase, reset passed_gates
+    Insert full-lifecycle steps for next milestone after current position
+    Reindex all steps, write status.json
+    Display: post-milestone: advancing to {next_milestone}
+  If none:
+    Display: post-milestone: all milestones complete
+    -> proceed (mark done, continue)
+```
+
+**Quality-gate decisions** -- delegate to external analyzer:
+
+Result file mapping:
+
+| Decision | Files |
+|----------|-------|
+| post-verify | `{artifact_dir}/verification.json` |
+| post-business-test | `{artifact_dir}/business-test-results.json` |
+| post-review | `{artifact_dir}/review.json` |
+| post-test | `{artifact_dir}/uat.md`, `{artifact_dir}/.tests/test-results.json` |
+
+```
+Bash({
+  command: `maestro delegate "PURPOSE: evaluate ${decision_type} quality gate result
+TASK: read result files | analyze pass/fail status | assess severity | recommend
+MODE: analysis
+CONTEXT: @${result_files}
+EXPECTED: strict format:
+---VERDICT---
+STATUS: proceed | fix | escalate
+REASON: one-line explanation
+GAP_SUMMARY: problem details (fix/escalate only)
+CONFIDENCE: high | medium | low
+---END---
+CONSTRAINTS: evaluate only | STATUS must be one of three | if retry ${retry_count}/${max_retries} at max and still failing, must escalate" --role analyze --mode analysis`,
+  run_in_background: true
+})
+STOP -- wait for background callback.
+```
+
+#### 3.4: Parse verdict
+
+```
+On callback: maestro delegate output <exec_id>
+
+Extract between ---VERDICT--- and ---END---:
+  verdict.status     = "proceed" | "fix" | "escalate"
+  verdict.reason     = string
+  verdict.gap_summary = string
+  verdict.confidence = "high" | "medium" | "low"
+
+If parse fails -> fallback: status = "fix", gap_summary = "verdict parse failed"
+```
+
+#### 3.5: Confirm (interactive mode)
+
+```
+Display: Decision: {decision_type} -> {verdict.status} ({verdict.reason})
+         Confidence: {verdict.confidence}
+
+Auto mode (session.auto_mode == true):
+  Follow verdict directly, no confirmation.
+
+Interactive mode:
+  AskUserQuestion: "Follow recommendation / Override proceed / Override fix / Cancel"
+  - Cancel -> session status = "paused", write status.json. End.
+```
+
+#### 3.6: Apply verdict
+
+| Verdict | Action |
+|---------|--------|
+| proceed | Add gate to session.passed_gates[], mark decision completed |
+| fix | Clear session.passed_gates[], insert fix-loop commands |
+| escalate | Set session.status = "paused". Display escalation message. End. |
+
+#### 3.7: Fix-loop insertion
+
+When verdict == "fix", insert commands after current position based on decision type:
+
+**post-verify fix-loop:**
+```
+quality-debug "{gap_summary}"                 [internal]
+maestro-plan {phase} --gaps                   [internal]
+maestro-execute {phase}                       [external]
+maestro-verify {phase}                        [internal]
+decision:post-verify {retry_count + 1}        [decision]
+```
+
+**post-review fix-loop:**
+```
+quality-debug "{gap_summary}"                 [internal]
+maestro-plan {phase} --gaps                   [internal]
+maestro-execute {phase}                       [external]
+quality-review {phase}                        [internal]
+decision:post-review {retry_count + 1}        [decision]
+```
+
+**post-test fix-loop:**
+```
+quality-debug --from-uat "{gap_summary}"      [internal]
+maestro-plan {phase} --gaps                   [internal]
+maestro-execute {phase}                       [external]
+maestro-verify {phase}                        [internal]
+decision:post-verify {retry: 0}               [decision]
+quality-test {phase}                          [internal]
+decision:post-test {retry_count + 1}          [decision]
+```
+
+**post-business-test fix-loop:**
+```
+quality-debug --from-business-test "{gap_summary}"  [internal]
+maestro-plan {phase} --gaps                         [internal]
+maestro-execute {phase}                             [external]
+maestro-verify {phase}                              [internal]
+decision:post-verify {retry: 0}                     [decision]
+quality-auto-test {phase}                           [internal]
+decision:post-business-test {retry_count + 1}       [decision]
+```
+
+```
+Read session status.json
+Insert new steps at position (current_step + 1)
+Reindex all steps: step.index = array position
+Mark current decision node: status = "completed"
+Write status.json
+
+Display: Decision: {decision_type} -> fix (+{N} commands inserted)
+```
+
+#### 3.8: Continue
+
+```
+Bash: maestro-flow done
+-> Skill({ skill: "maestro-flow", args: "execute" })
+End.
+```
+
+---
+
+### Step 4: Internal Execution
+
+The command .md content was loaded by `maestro-flow next` (after `---COMMAND---`).
+
+```
+1. The command content is already in context from Step 1 output
+2. Set $ARGUMENTS = ARGS from step output
+3. Apply auto-flag if session.auto_mode == true (see table below)
+4. Follow the command's <execution> section completely
+   - Respect <required_reading> and <deferred_reading> references
+```
+
+**Auto flag propagation:**
+
+| Skill | Flag appended |
+|-------|---------------|
+| maestro-init | -y |
+| maestro-analyze | -y |
+| maestro-brainstorm | -y |
+| maestro-roadmap | -y |
+| maestro-plan | -y |
+| maestro-execute | -y |
+| quality-auto-test | -y |
+| quality-test | -y --auto-fix |
+| maestro-milestone-complete | -y |
+| (all others) | (none) |
+
+```
+On success -> Step 6 (Mark Done)
+On failure -> Step 7 (Handle Failure)
+```
+
+---
+
+### Step 5: External Execution
+
+Delegate to a new Claude Code session via maestro delegate:
+
+```
+Bash({
+  command: `maestro delegate --to claude "Execute: /maestro-flow --cmd {SKILL} {ARGS}
+
+You are a delegate session executing a flow pipeline step.
+Use Skill() to invoke: /maestro-flow --cmd {SKILL} {ARGS}
+Do NOT reimplement the command logic -- invoke through the skill." --mode write`,
+  run_in_background: true,
+  timeout: 600000
+})
+
+STOP -- wait for background callback.
+```
+
+**On callback:**
+- Retrieve output: `maestro delegate output <exec_id>`
+- On success -> Step 6 (Mark Done)
+- On failure -> Step 7 (Handle Failure)
+
+---
+
+### Step 6: Mark Done & Advance
+
+```
+Bash: maestro-flow done [session-id]
+
+Parse output:
+  "COMPLETED: {idx} {skill}"  -> display confirmation
+  "NEXT: {idx} {skill} [{type}]" -> more steps remain
+  "SESSION_COMPLETE" -> all done, display summary. End.
+```
+
+If more steps, self-invoke:
+```
+Skill({ skill: "maestro-flow", args: "execute" })
+End.
+```
+
+---
+
+### Step 7: Handle Failure
+
+```
+Bash: maestro-flow step {session_id} {idx} failed
+Display: [{idx}/{total}] FAIL {SKILL}: {error}
+```
+
+**Auto mode (session.auto_mode == true):**
+```
+If not already retried:
+  Bash: maestro-flow step {session_id} {idx} pending
+  -> Skill({ skill: "maestro-flow", args: "execute" })  // retry once
+
+If already retried:
+  Bash: maestro-flow step {session_id} {idx} skipped
+  Display: [{idx}] skipped after retry
+  -> Skill({ skill: "maestro-flow", args: "execute" })  // continue to next
+```
+
+**Interactive mode:**
+```
+AskUserQuestion: "retry / skip / abort"
+  retry -> maestro-flow step {session_id} {idx} pending
+    -> Skill({ skill: "maestro-flow", args: "execute" })
+  skip  -> maestro-flow step {session_id} {idx} skipped
+    -> Skill({ skill: "maestro-flow", args: "execute" })
+  abort -> set session status = "paused" via status.json. End.
+```

package/codex/maestro-flow/SKILL.md

@@ -21,9 +21,27 @@ Session path: `.workflow/.maestro/flow-{YYYYMMDD-HHmmss}/status.json`
 <context>
 $ARGUMENTS -- intent text, flags, or special keywords.
 
+**Skill directory structure** (relative to this SKILL.md):
+```
+maestro-flow/
+  SKILL.md              <- this file (router + wave executor)
+  commands/
+    lifecycle/          <- 17 commands: init, analyze, plan, execute, verify, ...
+    quality/            <- 7 commands: debug, review, test, auto-test, ...
+    manage/             <- 10 commands: status, issue, wiki, harvest, ...
+    learn/              <- 5 commands: decompose, follow, investigate, ...
+    milestone/          <- 3 commands: audit, complete, release
+    spec/               <- 4 commands: add, load, remove, setup
+    wiki/               <- 2 commands: connect, digest
+  chains/
+    templates.json      <- 14 chain templates + decision types
+```
+
 **State files:**
 - `.workflow/state.json` -- project artifact registry (optional)
 - `.workflow/.maestro/flow-*/status.json` -- flow session state
+
+**CLI prerequisite:** `maestro-flow` command must be globally available (`npm install -g maestro-flow-one`)
 </context>
 
 <invariants>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maestro-flow-one",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "All Maestro workflow commands as a single Claude Code skill — intent routing, decision gates, minimal closed-loop chains",
   "bin": {
     "maestro-flow": "bin/maestro-flow.js"