maestro-flow 0.3.36 → 0.3.37

package/.claude/commands/maestro-composer.md

@@ -257,7 +257,7 @@ For parallel groups show fan-out/fan-in:
 ```
  N-003a [skill]  quality-review  ─┐
                                    ├─ N-004 [skill] quality-test
- N-003b [cli]    gemini analysis  ─┘
+ N-003b [cli]    cli analysis     ─┘
 ```
 
 **Step 4.2** — AskUserQuestion:

package/.claude/commands/maestro-execute.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-execute
 description: Execute plan with wave-based parallel execution and atomic commits
-argument-hint: "[phase] [--auto-commit] [--method agent|codex|gemini|cli|auto] [--executor <tool>] [--dir <path>] [-y]"
+argument-hint: "[phase] [--auto-commit] [--method agent|cli|auto] [--executor <tool>] [--dir <path>] [-y]"
 allowed-tools:
   - Read
   - Write

package/.claude/commands/maestro-ralph-execute.md

@@ -1,6 +1,6 @@
 ---
 name: maestro-ralph-execute
-description: Single-step executor — find next pending step in session, execute by type (decision/skill/cli), hand off to next iteration
+description: Single-step executor — find next pending step in session, execute by type (decision/internal/external), hand off to next iteration
 argument-hint: "[-y] [session-id]"
 allowed-tools:
   - Read
@@ -19,12 +19,12 @@ Each invocation: find next pending step → execute → update status → hand o
 
 Three node types:
 - **decision** (ralph-only): `Skill("maestro-ralph")` — ralph re-evaluates, may expand chain
-- **skill**: `Skill({ skill, args })` — synchronous in-session → self-invoke next
-- **cli**: `maestro delegate` background → STOP → callback → self-invoke next
+- **internal**: `Skill({ skill, args })` — synchronous in-session → self-invoke next
+- **external**: `maestro delegate --to claude` → new Claude Code session executing `/{skill} {args}` → STOP → callback → self-invoke next
 
 Session sources:
 - **source: "ralph"** — Adaptive chain with decision nodes. Primary use case.
-- **source: "maestro"** — Static chain, skill/cli only. No decision callbacks.
+- **source: "maestro"** — Static chain, internal/external only. No decision callbacks.
 
 Mutual invocation with `/maestro-ralph` forms a self-perpetuating work loop.
 </purpose>
@@ -149,9 +149,9 @@ Ralph will: detect running decision → evaluate results → optionally expand s
 
 **After Skill("maestro-ralph") returns, this execution ends.** Ralph handles the handoff.
 
-### 5b. skill node
+### 5b. internal node
 
-HARD RULE: Every skill step MUST be executed via `Skill({ skill, args })`.
+HARD RULE: Every internal step MUST be executed via `Skill({ skill, args })`.
 Never "simulate" or "inline" a skill's work. If Skill() is not called, the step has NOT been executed.
 
 **Auto flag propagation** (when `auto == true`):
@@ -180,20 +180,22 @@ Skill({ skill: next.skill, args: effective_args })
 **On success** → Step 5d (Mark Complete).
 **On failure** → Step 5e (Handle Failure).
 
-### 5c. cli node
+### 5c. external node
 
-Background delegate execution with stop-and-wait pattern.
+Context-isolated skill execution via new Claude Code session.
 
-```
-cli_tool = session.cli_tool
+HARD RULE: external nodes ALWAYS delegate to `claude` — only Claude Code can execute slash-command skills.
+`session.cli_tool` is for analysis-mode delegates (e.g., decision evaluation in ralph), NOT for external node execution.
 
+```
 Bash({
-  command: `maestro delegate "PURPOSE: 执行 /${next.skill} ${next.args}
-TASK: 运行 /${next.skill} ${next.args}
-MODE: write
-CONTEXT: @**/*
-EXPECTED: 产出写入 .workflow/scratch/，artifact 注册到 state.json
-CONSTRAINTS: 严格按照 /${next.skill} 的正常流程执行" --to ${cli_tool} --mode write`,
+  command: `maestro delegate "Execute: /${next.skill} ${next.args}
+
+You are a delegate session within a ralph/maestro pipeline.
+Your task: invoke the slash command /${next.skill} with args: ${next.args}
+Use Skill({ skill: \"${next.skill}\", args: \"${next.args}\" }) to execute it.
+Do NOT reimplement the skill logic manually — invoke the actual command.
+All artifact outputs follow the skill's own conventions." --to claude --mode write`,
   run_in_background: true,
   timeout: 600000
 })
@@ -218,7 +220,7 @@ Scan output for context propagation signals:
   SPEC-xxx         → context.spec_session_id
 
 Write status.json
-Display: [{next.index}/{total}] ✓ {next.skill} completed {next.type == "cli" ? "[cli]" : ""}
+Display: [{next.index}/{total}] ✓ {next.skill} completed {next.type == "external" ? "[external]" : ""}
 ```
 
 Then hand off:
@@ -277,17 +279,17 @@ Display completion report:
   Phase:    {phase}
   Steps:    {completed}/{total}
 
-  [✓] 0.   maestro-plan 1            [skill]
-  [✓] 1. ⚡ maestro-execute 1         [cli]
-  [✓] 2.   maestro-verify 1          [skill]
+  [✓] 0.   maestro-plan 1            [internal]
+  [✓] 1. ⚡ maestro-execute 1         [external]
+  [✓] 2.   maestro-verify 1          [internal]
   [✓] 3. ◆ post-verify               [decision]
-  [—] 4.   quality-auto-test 1       [skill]  (skipped)
+  [—] 4.   quality-auto-test 1       [internal]  (skipped)
   ...
 ============================================================
 ```
 
 Status icons: `✓` completed, `—` skipped, `✗` failed, ` ` pending.
-Type badges: `◆` decision, `⚡` cli, (none) skill.
+Type badges: `◆` decision, `⚡` external, (none) internal.
 
 **End.**
 
@@ -310,8 +312,8 @@ Type badges: `◆` decision, `⚡` cli, (none) skill.
 - [ ] Per-skill enrichment provides correct args when empty/minimal
 - [ ] Artifact dir resolution finds latest artifact for --dir args
 - [ ] decision nodes hand off to maestro-ralph via Skill() (ralph sessions only)
-- [ ] skill nodes execute via Skill() with auto flag propagation
-- [ ] cli nodes use maestro delegate with run_in_background + STOP pattern
+- [ ] internal nodes execute via Skill() with auto flag propagation
+- [ ] external nodes use maestro delegate --to claude with run_in_background + STOP pattern
 - [ ] Context propagation: output signals update status.json.context
 - [ ] status.json updated after every status change (resume-safe)
 - [ ] Auto mode: retry once then skip; interactive: AskUserQuestion retry/skip/abort

package/.claude/commands/maestro-ralph.md

@@ -1,6 +1,6 @@
 ---
 name: maestro-ralph
-description: Closed-loop lifecycle decision engine — read project state, infer position, build adaptive command chain with decision/skill/cli nodes
+description: Closed-loop lifecycle decision engine — read project state, infer position, build adaptive command chain with decision/internal/external nodes
 argument-hint: "[-y] \"intent\" | status | continue"
 allowed-tools:
   - Read
@@ -18,8 +18,8 @@ Closed-loop decision engine for the maestro workflow lifecycle.
 Reads project state → infers lifecycle position → builds adaptive command chain → delegates execution.
 
 Three node types:
-- **skill**: In-session `Skill()` call (synchronous, lightweight)
-- **cli**: `maestro delegate` (context-isolated, heavy computation)
+- **internal**: In-session `Skill()` call (synchronous, lightweight)
+- **external**: New Claude Code session via `maestro delegate --to claude` executing `/{skill} {args}` (context-isolated, heavy computation)
 - **decision**: Hand back to ralph for re-evaluation (adaptive branching)
 
 Key difference from maestro coordinator:
@@ -73,9 +73,9 @@ Display:
   Current:  [{current_step}] {steps[current_step].skill} [{type}]
   
   Commands:
-    [✓] 0. maestro-analyze 1         [skill]
-    [▸] 1. maestro-plan 1            [skill]
-    [ ] 2. maestro-execute 1         [cli]
+    [✓] 0. maestro-analyze 1         [external]
+    [▸] 1. maestro-plan 1            [internal]
+    [ ] 2. maestro-execute 1         [external]
     ...
 End.
 ```
@@ -164,23 +164,25 @@ Generate steps from `lifecycle_position` to target (default: `milestone-complete
 
 | Stage | Skill command | Type | Decision after |
 |-------|--------------|------|----------------|
-| brainstorm | `maestro-brainstorm "{intent}"` | cli | — (0→1 only) |
-| init | `maestro-init` | skill | — |
-| roadmap | `maestro-roadmap "{intent}"` | skill | — |
-| analyze | `maestro-analyze {phase}` | cli | — |
-| plan | `maestro-plan {phase}` | skill | — |
-| execute | `maestro-execute {phase}` | cli | — |
-| verify | `maestro-verify {phase}` | skill | `post-verify` |
-| business-test | `quality-auto-test {phase}` | skill | `post-business-test` |
-| review | `quality-review {phase}` | skill | `post-review` |
-| test-gen | `quality-auto-test {phase}` | skill | — |
-| test | `quality-test {phase}` | skill | `post-test` |
-| milestone-audit | `maestro-milestone-audit` | skill | — |
-| milestone-complete | `maestro-milestone-complete` | skill | `post-milestone` |
+| brainstorm | `maestro-brainstorm "{intent}"` | external | — (0→1 only) |
+| init | `maestro-init` | internal | — |
+| roadmap | `maestro-roadmap "{intent}"` | internal | — |
+| analyze | `maestro-analyze {phase}` | external | — |
+| plan | `maestro-plan {phase}` | internal | — |
+| execute | `maestro-execute {phase}` | external | — |
+| verify | `maestro-verify {phase}` | internal | `post-verify` |
+| business-test | `quality-auto-test {phase}` | internal | `post-business-test` |
+| review | `quality-review {phase}` | internal | `post-review` |
+| test-gen | `quality-auto-test {phase}` | internal | — |
+| test | `quality-test {phase}` | internal | `post-test` |
+| milestone-audit | `maestro-milestone-audit` | internal | — |
+| milestone-complete | `maestro-milestone-complete` | internal | `post-milestone` |
 
 **Type rationale:**
-- `cli` = heavy computation needing isolated context (analyze, execute, brainstorm)
-- `skill` = needs user interaction or is lightweight (plan, verify, quality-*, milestone-*)
+- `internal` = in-session `Skill()` call, needs user interaction or is lightweight (plan, verify, quality-*, milestone-*)
+- `external` = new Claude Code session via `maestro delegate --to claude` executing `/{skill} {args}`, context-isolated heavy computation (analyze, execute, brainstorm)
+
+IMPORTANT: `external` ≠ single CLI tool call. It spawns a full Claude Code session that executes the skill command — the delegate session has complete skill access.
 
 **Build rules:**
 1. Start from inferred position, skip completed stages
@@ -195,19 +197,19 @@ Generate steps from `lifecycle_position` to target (default: `milestone-complete
 **Example — from "plan" position:**
 ```json
 [
-  { "index": 0, "type": "skill", "skill": "maestro-plan", "args": "{phase}" },
-  { "index": 1, "type": "cli",  "skill": "maestro-execute", "args": "{phase}" },
-  { "index": 2, "type": "skill", "skill": "maestro-verify", "args": "{phase}" },
+  { "index": 0, "type": "internal", "skill": "maestro-plan", "args": "{phase}" },
+  { "index": 1, "type": "external", "skill": "maestro-execute", "args": "{phase}" },
+  { "index": 2, "type": "internal", "skill": "maestro-verify", "args": "{phase}" },
   { "index": 3, "type": "decision", "skill": "maestro-ralph", "args": "{\"decision\":\"post-verify\",\"retry_count\":0,\"max_retries\":2}" },
-  { "index": 4, "type": "skill", "skill": "quality-auto-test", "args": "{phase}" },
+  { "index": 4, "type": "internal", "skill": "quality-auto-test", "args": "{phase}" },
   { "index": 5, "type": "decision", "skill": "maestro-ralph", "args": "{\"decision\":\"post-business-test\",\"retry_count\":0,\"max_retries\":2}" },
-  { "index": 6, "type": "skill", "skill": "quality-review", "args": "{phase}" },
+  { "index": 6, "type": "internal", "skill": "quality-review", "args": "{phase}" },
   { "index": 7, "type": "decision", "skill": "maestro-ralph", "args": "{\"decision\":\"post-review\",\"retry_count\":0,\"max_retries\":2}" },
-  { "index": 8, "type": "skill", "skill": "quality-auto-test", "args": "{phase}" },
-  { "index": 9, "type": "skill", "skill": "quality-test", "args": "{phase}" },
+  { "index": 8, "type": "internal", "skill": "quality-auto-test", "args": "{phase}" },
+  { "index": 9, "type": "internal", "skill": "quality-test", "args": "{phase}" },
   { "index": 10, "type": "decision", "skill": "maestro-ralph", "args": "{\"decision\":\"post-test\",\"retry_count\":0,\"max_retries\":2}" },
-  { "index": 11, "type": "skill", "skill": "maestro-milestone-audit", "args": "" },
-  { "index": 12, "type": "skill", "skill": "maestro-milestone-complete", "args": "" },
+  { "index": 11, "type": "internal", "skill": "maestro-milestone-audit", "args": "" },
+  { "index": 12, "type": "internal", "skill": "maestro-milestone-complete", "args": "" },
   { "index": 13, "type": "decision", "skill": "maestro-ralph", "args": "{\"decision\":\"post-milestone\"}" }
 ]
 ```
@@ -253,9 +255,9 @@ Write to `.workflow/.maestro/{session_id}/status.json`.
   Target:    {target}
   Commands:  {total} steps ({decision_count} decision points)
 
-  [ ] 0. maestro-plan 1                  [skill]
-  [ ] 1. maestro-execute 1               [cli]
-  [ ] 2. maestro-verify 1                [skill]
+  [ ] 0. maestro-plan 1                  [internal]
+  [ ] 1. maestro-execute 1               [external]
+  [ ] 2. maestro-verify 1                [internal]
   [ ] 3. ◆ post-verify                   [decision]
   ...
 ============================================================
@@ -383,7 +385,7 @@ The delegate's `gap_summary` is passed as context to `quality-debug`.
 ```
 quality-debug "{gap_summary}"
 maestro-plan --gaps {phase}
-maestro-execute {phase}                    [cli]
+maestro-execute {phase}                    [external]
 maestro-verify {phase}
 decision:post-verify {retry_count + 1}
 ```
@@ -392,7 +394,7 @@ decision:post-verify {retry_count + 1}
 ```
 quality-debug --from-business-test "{gap_summary}"
 maestro-plan --gaps {phase}
-maestro-execute {phase}                    [cli]
+maestro-execute {phase}                    [external]
 maestro-verify {phase}
 decision:post-verify {retry: 0}
 quality-auto-test {phase}
@@ -403,7 +405,7 @@ decision:post-business-test {retry_count + 1}
 ```
 quality-debug "{gap_summary}"
 maestro-plan --gaps {phase}
-maestro-execute {phase}                    [cli]
+maestro-execute {phase}                    [external]
 quality-review {phase}
 decision:post-review {retry_count + 1}
 ```
@@ -412,7 +414,7 @@ decision:post-review {retry_count + 1}
 ```
 quality-debug --from-uat "{gap_summary}"
 maestro-plan --gaps {phase}
-maestro-execute {phase}                    [cli]
+maestro-execute {phase}                    [external]
 maestro-verify {phase}
 decision:post-verify {retry: 0}
 quality-auto-test {phase}

package/.claude/commands/maestro.md

@@ -114,7 +114,7 @@ In auto mode, maestro also:
 - [ ] Low-complexity intents routed to maestro-quick
 - [ ] All chains dispatched via unified executor (maestro-ralph-execute) with status.json tracking
 - [ ] Phase numbers auto-detected and passed to downstream commands
-- [ ] (super mode) Requirements expanded and validated via Gemini before roadmap creation
+- [ ] (super mode) Requirements expanded and validated via CLI delegate before roadmap creation
 - [ ] (super mode) Each milestone scored ≥ 80% before advancing
 - [ ] (super mode) All milestones completed with no user intervention
 - [ ] (super mode) Final system builds, starts, and passes all tests

package/.claude/commands/manage-issue-discover.md

@@ -16,7 +16,7 @@ Automated issue discovery via multi-perspective codebase analysis (8 perspective
 
 - **Default (no args)**: Interactive mode selection — choose multi-perspective or prompt-driven.
 - **`multi-perspective`**: 8-perspective parallel agent scan — security, performance, reliability, maintainability, scalability, UX, accessibility, compliance.
-- **`by-prompt "..."`**: Prompt-driven — Gemini plans exploration strategy, agents explore iteratively with cross-dimension analysis.
+- **`by-prompt "..."`**: Prompt-driven — CLI delegate plans exploration strategy, agents explore iteratively with cross-dimension analysis.
 
 For CRUD operations (create, list, update, close, link), use `/manage-issue`.
 
@@ -38,7 +38,7 @@ $ARGUMENTS -- optional. Parse first token to determine mode.
 **Modes:**
 - _(empty)_ -- interactive mode selection (AskUserQuestion)
 - `multi-perspective` -- 8-perspective parallel agent scan
-- `by-prompt "..."` -- prompt-driven iterative agent exploration (Gemini-planned)
+- `by-prompt "..."` -- prompt-driven iterative agent exploration (CLI-planned)
 
 **Flags:**
 - `-y` / `--yes` -- auto mode, skip confirmations

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

@@ -16,7 +16,7 @@ Entry points:
 - **`$maestro-ralph status`** — Display session progress
 
 Two node types:
-- **skill**: Executed via `spawn_agents_on_csv`. Barrier skills solo; non-barriers parallel.
+- **external**: Executed via `spawn_agents_on_csv`. Barrier steps solo; non-barriers parallel.
 - **decision**: Delegate evaluation via `maestro delegate --role analyze`, then expand/proceed/escalate.
 
 Key difference from maestro coordinator:
@@ -60,12 +60,12 @@ otherwise             → Phase 1 (New Session).
 </context>
 
 <invariants>
-1. **ALL skills via spawn_agents_on_csv** — coordinator NEVER executes skill logic directly
+1. **ALL external steps via spawn_agents_on_csv** — coordinator NEVER executes skill logic directly
 2. **Coordinator = prompt assembler** — classify → enrich args → build CSV → spawn → read results → assemble next
 3. **Decision nodes delegate-evaluate** — use `maestro delegate --role analyze` for quality-gate assessment; structural decisions (post-milestone, post-debug-escalate) evaluated directly
 4. **Decision STOP behavior** — default: STOP after evaluation; `-y` mode: auto-continue (except post-debug-escalate always STOPs)
 5. **Barrier = solo wave** — analyze, plan, execute, brainstorm, roadmap always run alone
-6. **Non-barriers can parallel** — consecutive non-barrier, non-decision steps grouped into one wave
+6. **Non-barriers can parallel** — consecutive non-barrier, non-decision external steps grouped into one wave
 7. **Wave-by-wave** — never start wave N+1 before wave N results are read
 8. **Coordinator owns context** — sub-agents never read prior results; coordinator assembles full skill_call
 9. **Abort on failure** — `-y`: retry once then skip; non-`-y`: mark remaining skipped → pause
@@ -223,7 +223,7 @@ Display:
 
   [ ] 0. maestro-plan {phase}              [barrier]
   [ ] 1. maestro-execute {phase}           [barrier]
-  [ ] 2. maestro-verify {phase}            [skill]
+  [ ] 2. maestro-verify {phase}            [external]
   [ ] 3. ◆ post-verify                     [decision]
   ...
 ============================================================
@@ -244,7 +244,7 @@ Read status.json. Rebuild `update_plan` from step statuses.
 Find first pending step.
 
 - If decision node → Step 2.2 (Delegate Evaluation)
-- If skill node → Step 2.3 (Wave Execution)
+- If external node → Step 2.3 (Wave Execution)
 - If no pending → Phase 3 (Completion)
 
 ### 2.2: Delegate Evaluation (decision nodes)
@@ -459,7 +459,7 @@ spawn_agents_on_csv({
 **10. Next step check:**
 - Decision node + auto_mode → loop to 2.2
 - Decision node + non-auto → STOP
-- Skill node → loop to step 1
+- External node → loop to step 1
 
 ---
 
@@ -513,8 +513,8 @@ id,skill_call,topic
 Rules:
 - `skill_call`: complete `$<skill> <args> [auto-flag]` from `buildSkillCall()`
 - `topic`: human-readable step description
-- Non-barrier + non-decision → multi-row (parallel)
-- Barrier → single-row (solo)
+- Non-barrier external + non-decision → multi-row (parallel)
+- Barrier external → single-row (solo)
 - Decision nodes NEVER appear in CSV — processed by coordinator directly
 
 ### Sub-Agent Instruction
@@ -570,8 +570,8 @@ Rules:
 - [ ] passed_gates cleared when code changes (fix-loop inserts execute step)
 - [ ] Fix-loop templates correctly use gap_summary from delegate
 - [ ] retry_count tracked per decision, max_retries enforced → escalation
-- [ ] ALL skills via spawn_agents_on_csv — coordinator never executes directly
-- [ ] Barrier skills solo wave, non-barriers parallel
+- [ ] ALL external steps via spawn_agents_on_csv — coordinator never executes directly
+- [ ] Barrier steps solo wave, non-barriers parallel
 - [ ] functions.update_plan() initialized in 1.6, synced per wave, finalized in Phase 3
 - [ ] status.json persisted after every wave and decision
 - [ ] Command insertion + reindex preserves step integrity

package/package.json

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