maestro-flow 0.3.8 → 0.3.10

package/workflows/maestro-coordinate.md

@@ -1,6 +1,6 @@
 # Workflow: maestro-coordinate
 
-Autonomous CLI coordinator. Classifies intent, selects command chain, executes each step via `maestro cli` with template-driven prompts and async state machine.
+Autonomous CLI coordinator. Classifies intent, selects command chain, executes each step via `maestro delegate` with template-driven prompts and async state machine.
 
 ---
 
@@ -37,9 +37,9 @@ test -f .workflow/state.json && echo "exists" || echo "missing"
 ```javascript
 const projectState = {
   initialized: true,
-  current_phase: /* from state.json */,
-  phase_slug: '...',
-  phase_status: '...', // pending|exploring|planning|executing|verifying|testing|completed|blocked
+  current_milestone: /* from state.json */,
+  latest_artifact: /* last artifact in artifacts[] */,
+  milestone_progress: '...', // derived from artifact registry
   phase_artifacts: { brainstorm: false, analysis: false, context: false, plan: false, verification: false, uat: false },
   execution: { tasks_completed: 0, tasks_total: 0 },
   verification_status: 'pending',
@@ -75,6 +75,10 @@ if (exactMatch[normalized]) {
 
 #### 3a-2: Structured intent extraction (LLM-native)
 
+> **Implementation note**: The runtime (`src/coordinator/intent-router.ts`) currently
+> uses pattern-based regex matching via `chains/_intent-map.json`. The structured
+> extraction below is a design target, not the current implementation.
+
 Instead of regex, extract a structured intent tuple using LLM semantic understanding:
 
 ```json
@@ -105,7 +109,7 @@ function routeIntent(intent, projectState) {
   // Action × Object matrix
   const matrix = {
     'fix':       { 'bug': 'debug', 'issue': 'issue', 'code': 'debug', 'performance': 'debug', 'security': 'debug', '_default': 'debug' },
-    'create':    { 'feature': 'quick', 'issue': 'issue', 'test': 'test_gen', 'spec': 'spec_generate', 'ui': 'ui_design', 'config': 'init', 'phase': 'phase_add', '_default': 'quick' },
+    'create':    { 'feature': 'quick', 'issue': 'issue', 'test': 'test_gen', 'spec': 'spec_generate', 'ui': 'ui_design', 'config': 'init', 'phase': 'roadmap', '_default': 'quick' },
     'analyze':   { 'bug': 'analyze', 'issue': 'issue_analyze', 'code': 'analyze', 'codebase': 'spec_map', '_default': 'analyze' },
     'explore':   { 'issue': 'issue_discover', 'feature': 'brainstorm', 'ui': 'ui_design', '_default': 'brainstorm' },
     'plan':      { 'issue': 'issue_plan', 'spec': 'spec_generate', '_default': 'plan' },
@@ -115,8 +119,8 @@ function routeIntent(intent, projectState) {
     'test':      { '_default': 'test' },
     'debug':     { '_default': 'debug' },
     'refactor':  { '_default': 'refactor' },
-    'manage':    { 'issue': 'issue', 'milestone': 'milestone_audit', 'phase': 'phase_transition', 'memory': 'memory', 'doc': 'sync', 'codebase': 'codebase_refresh', 'team': 'team_coordinate', '_default': 'status' },
-    'transition':{ 'phase': 'phase_transition', 'milestone': 'milestone_complete', '_default': 'phase_transition' },
+    'manage':    { 'issue': 'issue', 'milestone': 'milestone_audit', 'phase': 'milestone_close', 'memory': 'memory', 'doc': 'sync', 'codebase': 'codebase_refresh', 'team': 'team_coordinate', '_default': 'status' },
+    'transition':{ 'phase': 'milestone_close', 'milestone': 'milestone_complete', '_default': 'milestone_close' },
     'continue':  { '_default': 'state_continue' },
     'sync':      { '_default': 'sync' },
     'learn':     { '_default': 'learn' },
@@ -166,18 +170,18 @@ function detectNextAction(s) {
     if (s.verification_status === 'passed') {
       if (!s.review_verdict) return { chain: 'review', steps: [{ cmd: 'quality-review', args: '{phase}' }] };
       if (s.uat_status === 'pending') return { chain: 'test', steps: [{ cmd: 'quality-test', args: '{phase}' }] };
-      if (s.uat_status === 'passed') return { chain: 'phase-transition', steps: [{ cmd: 'maestro-phase-transition' }] };
+      if (s.uat_status === 'passed') return { chain: 'milestone-close', steps: [{ cmd: 'maestro-milestone-audit' }, { cmd: 'maestro-milestone-complete' }] };
       return { chain: 'debug', steps: [{ cmd: 'quality-debug', args: '--from-uat {phase}' }] };
     }
     return { chain: 'quality-loop-partial', steps: [{ cmd: 'maestro-plan', args: '{phase} --gaps' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }] };
   }
   if (ps === 'testing') {
-    if (s.uat_status === 'passed') return { chain: 'phase-transition', steps: [{ cmd: 'maestro-phase-transition' }] };
+    if (s.uat_status === 'passed') return { chain: 'milestone-close', steps: [{ cmd: 'maestro-milestone-audit' }, { cmd: 'maestro-milestone-complete' }] };
     return { chain: 'debug', steps: [{ cmd: 'quality-debug', args: '--from-uat {phase}' }] };
   }
   if (ps === 'completed') {
     if (s.phases_completed >= s.phases_total) return { chain: 'milestone-close', steps: [{ cmd: 'maestro-milestone-audit' }, { cmd: 'maestro-milestone-complete' }] };
-    return { chain: 'phase-transition', steps: [{ cmd: 'maestro-phase-transition' }] };
+    return { chain: 'milestone-close', steps: [{ cmd: 'maestro-milestone-audit' }, { cmd: 'maestro-milestone-complete' }] };
   }
   if (ps === 'blocked') return { chain: 'debug', steps: [{ cmd: 'quality-debug' }] };
   return { chain: 'status', steps: [{ cmd: 'manage-status' }] };
@@ -205,8 +209,8 @@ const chainMap = {
   'retrospective':      [{ cmd: 'quality-retrospective', args: '{phase}' }],
   'learn':              [{ cmd: 'manage-learn', args: '"{description}"' }],
   'sync':               [{ cmd: 'quality-sync', args: '{phase}' }],
-  'phase_transition':   [{ cmd: 'maestro-phase-transition' }],
-  'phase_add':          [{ cmd: 'maestro-phase-add', args: '"{description}"' }],
+  'milestone_close':    [{ cmd: 'maestro-milestone-audit' }, { cmd: 'maestro-milestone-complete' }],
+  'roadmap':            [{ cmd: 'maestro-roadmap', args: '"{description}"' }],
   'milestone_audit':    [{ cmd: 'maestro-milestone-audit' }],
   'milestone_complete': [{ cmd: 'maestro-milestone-complete' }],
   'codebase_rebuild':   [{ cmd: 'manage-codebase-rebuild' }],
@@ -219,10 +223,12 @@ const chainMap = {
   'memory':             [{ cmd: 'manage-memory', args: '"{description}"' }],
   'issue':              [{ cmd: 'manage-issue', args: '"{description}"' }],
   'issue_discover':     [{ cmd: 'manage-issue-discover', args: '"{description}"' }],
-  'issue_analyze':      [{ cmd: 'manage-issue-analyze', args: '"{description}"' }],
-  'issue_plan':         [{ cmd: 'manage-issue-plan', args: '"{description}"' }],
-  'issue_execute':      [{ cmd: 'manage-issue-execute', args: '"{description}"' }],
+  'issue_analyze':      [{ cmd: 'maestro-analyze', args: '--gaps "{description}"' }],
+  'issue_plan':         [{ cmd: 'maestro-plan', args: '--gaps' }],
+  'issue_execute':      [{ cmd: 'maestro-execute', args: '' }],
   'quick':              [{ cmd: 'maestro-quick', args: '"{description}"' }],
+  'fork':               [{ cmd: 'maestro-fork', args: '-m {milestone_num}' }],
+  'merge':              [{ cmd: 'maestro-merge', args: '-m {milestone_num}' }],
   'team_lifecycle':     [{ cmd: 'team-lifecycle-v4', args: '"{description}"' }],
   'team_coordinate':    [{ cmd: 'team-coordinate', args: '"{description}"' }],
   'team_qa':            [{ cmd: 'team-quality-assurance', args: '"{description}"' }],
@@ -234,7 +240,7 @@ const chainMap = {
   'spec-driven':     [{ cmd: 'maestro-init' }, { cmd: 'maestro-spec-generate', args: '"{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }],
   'brainstorm-driven': [{ cmd: 'maestro-brainstorm', args: '"{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }],
   'ui-design-driven': [{ cmd: 'maestro-ui-design', args: '{phase}' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }],
-  'full-lifecycle':  [{ cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }, { cmd: 'quality-review', args: '{phase}' }, { cmd: 'quality-test', args: '{phase}' }, { cmd: 'maestro-phase-transition' }],
+  'full-lifecycle':  [{ cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }, { cmd: 'quality-review', args: '{phase}' }, { cmd: 'quality-test', args: '{phase}' }, { cmd: 'maestro-milestone-audit' }, { cmd: 'maestro-milestone-complete' }],
   'execute-verify':  [{ cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }],
   'quality-loop':    [{ cmd: 'maestro-verify', args: '{phase}' }, { cmd: 'quality-review', args: '{phase}' }, { cmd: 'quality-test', args: '{phase}' }, { cmd: 'quality-debug', args: '--from-uat {phase}' }, { cmd: 'maestro-plan', args: '{phase} --gaps' }, { cmd: 'maestro-execute', args: '{phase}' }],
   'milestone-close': [{ cmd: 'maestro-milestone-audit' }, { cmd: 'maestro-milestone-complete' }],
@@ -242,8 +248,8 @@ const chainMap = {
   'next-milestone': [{ cmd: 'maestro-roadmap', args: '"{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }],
   'analyze-plan-execute': [{ cmd: 'maestro-analyze', args: '"{description}" -q' }, { cmd: 'maestro-plan', args: '--dir {scratch_dir}' }, { cmd: 'maestro-execute', args: '--dir {scratch_dir}' }],
   // Issue lifecycle chains (with quality gates)
-  'issue-full': [{ cmd: 'manage-issue-analyze', args: '{issue_id}' }, { cmd: 'manage-issue-plan', args: '{issue_id}' }, { cmd: 'manage-issue-execute', args: '{issue_id}' }, { cmd: 'quality-review', args: '--scope {affected_files}' }, { cmd: 'manage-issue', args: 'close {issue_id} --resolution fixed' }],
-  'issue-quick': [{ cmd: 'manage-issue-plan', args: '{issue_id}' }, { cmd: 'manage-issue-execute', args: '{issue_id}' }, { cmd: 'manage-issue', args: 'close {issue_id} --resolution fixed' }],
+  'issue-full': [{ cmd: 'maestro-analyze', args: '--gaps {issue_id}' }, { cmd: 'maestro-plan', args: '--gaps' }, { cmd: 'maestro-execute', args: '' }, { cmd: 'quality-review', args: '--scope {affected_files}' }, { cmd: 'manage-issue', args: 'close {issue_id} --resolution fixed' }],
+  'issue-quick': [{ cmd: 'maestro-plan', args: '--gaps' }, { cmd: 'maestro-execute', args: '' }, { cmd: 'manage-issue', args: 'close {issue_id} --resolution fixed' }],
 };
 
 // Aliases: task type → named multi-step chain
@@ -269,7 +275,8 @@ function resolvePhase() {
   // Fallback regex
   const m = intent.match(/phase\s*(\d+)|^(\d+)$/);
   if (m) return m[1] || m[2];
-  if (projectState.initialized) return projectState.current_phase;
+  // With scratch-based architecture, commands default to milestone-wide when no phase specified
+  // Return null to let commands use their default scope routing
   return null;
 }
 
@@ -320,12 +327,12 @@ const state = {
 };
 Write(`${sessionDir}/state.json`, JSON.stringify(state, null, 2));
 
-const context = { current_phase: resolvedPhase, user_intent: intent, issue_id: resolvedIssueId, spec_session_id: null };
+const context = { resolved_phase: resolvedPhase, user_intent: intent, issue_id: resolvedIssueId, spec_session_id: null };
 ```
 
 ---
 
-### Step 6: Execute Step via maestro cli
+### Step 6: Execute Step via maestro delegate
 
 #### 6a: Assemble args
 
@@ -338,7 +345,7 @@ const AUTO_FLAG_MAP = {
 
 function assembleArgs(step) {
   let a = (step.args || '')
-    .replace(/\{phase\}/g, context.current_phase || '')
+    .replace(/\{phase\}/g, context.resolved_phase || '')  // empty = milestone-wide default
     .replace(/\{description\}/g, context.user_intent || '')
     .replace(/\{issue_id\}/g, context.issue_id || '')
     .replace(/\{spec_session_id\}/g, context.spec_session_id || '')
@@ -397,7 +404,7 @@ state.steps[state.current_step].started_at = new Date().toISOString();
 Write(`${sessionDir}/state.json`, JSON.stringify(state, null, 2));
 
 Bash({
-  command: `maestro cli -p ${escapeForShell(prompt)} --tool ${state.tool} --mode write`,
+  command: `maestro delegate ${escapeForShell(prompt)} --to ${state.tool} --mode write`,
   run_in_background: true, timeout: 600000
 });
 // ■ STOP — wait for hook callback
@@ -418,7 +425,7 @@ step.completed_at = new Date().toISOString();
 
 // Context propagation
 const phaseMatch = output.match(/PHASE:\s*(\d+)/m);
-if (phaseMatch) context.current_phase = phaseMatch[1];
+if (phaseMatch) context.resolved_phase = phaseMatch[1];
 const specMatch = output.match(/SPEC-[\w-]+/);
 if (specMatch) context.spec_session_id = specMatch[0];
 const scratchMatch = output.match(/scratch_dir:\s*(.+)/m);
@@ -489,9 +496,9 @@ EXPECTED OUTPUT (strict JSON):
   "step_summary": ""
 }`;
 
-let cliCommand = `maestro cli -p ${escapeForShell(analysisPrompt)} --tool gemini --mode analysis --rule analysis-review-code-quality`;
-if (state.gemini_session_id) cliCommand += ` --resume ${state.gemini_session_id}`;
-Bash({ command: cliCommand, run_in_background: true, timeout: 300000 });
+let delegateCmd = `maestro delegate ${escapeForShell(analysisPrompt)} --to gemini --mode analysis --rule analysis-review-code-quality`;
+if (state.gemini_session_id) delegateCmd += ` --resume ${state.gemini_session_id}`;
+Bash({ command: delegateCmd, run_in_background: true, timeout: 300000 });
 // ■ STOP — wait for hook callback
 ```
 
@@ -562,14 +569,14 @@ Write(`${sessionDir}/state.json`, JSON.stringify(state, null, 2));
 ## Core Rules
 
 1. **Semantic routing** — LLM-native structured extraction (`action × object`) replaces regex; disambiguates "问题" by context
-2. **STOP after each `maestro cli` call** — background execution, wait for hook callback
+2. **STOP after each `maestro delegate` call** — background execution, wait for hook callback
 3. **State machine** — advance via `current_step`, no sync loops for async operations
 4. **Template-driven** — all steps use `coordinate-step.txt`, no per-command prompt assembly
 5. **Context propagation** — parse PHASE / spec session ID / scratch_dir / issue_id from each step output, feed to next step
 6. **Quality gates** — issue chains auto-include review; `issue-full` is default for issue execution
-7. **Tool fallback** — if `maestro cli` fails: retry with same tool once, then try `gemini` → `qwen`
+7. **Tool fallback** — if `maestro delegate` fails: retry with same tool once, then try `gemini` → `qwen`
 8. **Auto-confirm injection** — `{{AUTO_DIRECTIVE}}` in template prevents blocking during background execution
 9. **Resumable** — `-c` reads `state.json`, jumps to first pending step
-10. **Gemini analysis after each step** — evaluate output quality via `maestro cli --tool gemini --mode analysis`, chained via `--resume`. Analysis generates `next_step_hints` injected into next step's prompt as `{{ANALYSIS_HINTS}}`
+10. **Gemini analysis after each step** — evaluate output quality via `maestro delegate --to gemini --mode analysis`, chained via `--resume`. Analysis generates `next_step_hints` injected into next step's prompt as `{{ANALYSIS_HINTS}}`
 11. **Session capture** — after each gemini callback, capture exec_id → `gemini_session_id` for resume chain
 12. **Analysis skip conditions** — skip gemini analysis for: failed/skipped steps, single-step chains

package/workflows/maestro-link-coordinate.md

@@ -1,6 +1,6 @@
 # Workflow: maestro-link-coordinate
 
-Chain-graph coordinator via `maestro coordinate` CLI endpoint. Loads a chain graph, walks node by node via step-mode subcommands. Each command node executed through `maestro cli` internally.
+Chain-graph coordinator via `maestro coordinate` CLI endpoint. Loads a chain graph, walks node by node via step-mode subcommands. Each command node executed through `maestro delegate` internally.
 
 ---
 
@@ -93,7 +93,7 @@ After each call:
 
 The walker handles internally:
 - Prompt assembly from `coordinate-step` template (command nodes) and inline `buildDecisionPrompt` (decision nodes) — **the walker owns all prompt construction**
-- CLI execution via `maestro cli --tool {tool} --mode {write|analysis}`
+- CLI execution via `maestro delegate --to {tool} --mode {write|analysis}`
 - Decision/gate/eval node auto-resolution:
   - `strategy: 'expr'` — static expression, instant
   - `strategy: 'llm'` — spawns the configured CLI tool via a thin `DefaultLLMDecider`, expects a `DECISION: <target>\nREASONING: <text>` response