maestro-flow 0.3.9 → 0.3.11

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

@@ -1,324 +1,213 @@
 ---
 name: maestro-coordinate
-description: Team-agent pipeline coordinator — classifies intent, maps to skill chain, spawns one agent per step whose prompt contains the skill invocation ($skill-name "intent"). Step results propagate as context to each successor. Session state at .workflow/.maestro-coordinate/{session-id}/state.json.
-argument-hint: "\"intent text\" [-y] [-c|--continue] [--dry-run] [--chain <name>]"
-allowed-tools: spawn_agent, wait_agent, send_message, close_agent, Read, Write, Bash, Glob, Grep
+description: CLI-based coordinator — analyze intent → select command chain → execute sequentially via maestro delegate with auto-confirm. Async state machine with template-driven prompts and gemini analysis between steps.
+argument-hint: "\"intent text\" [-y] [-c] [--dry-run] [--chain <name>]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 ---
 
-## Auto Mode
-
-When `-y` or `--yes`: Skip clarification and confirmation prompts. Pass `-y` through to each step's skill invocation.
-
-# Maestro Coordinate
-
-## Usage
-
-```bash
-$maestro-coordinate "implement user authentication with JWT"
-$maestro-coordinate -y "refactor the payment module"
-$maestro-coordinate --continue
-$maestro-coordinate --dry-run "add rate limiting to API endpoints"
-$maestro-coordinate --chain feature "add dark mode toggle"
-```
-
-**Flags**:
-- `-y, --yes` — Auto mode: skip all prompts; propagate `-y` to each skill
-- `--continue` — Resume latest paused session from last incomplete step
-- `--dry-run` — Display planned chain without spawning any agents
-- `--chain <name>` — Force a specific chain (skips intent classification)
-
-**Session state**: `.workflow/.maestro-coordinate/{session-id}/state.json`
-
----
-
-## Overview
-
-Sequential pipeline coordinator (Pattern 2.5). Each chain step is one `spawn_agent` whose message contains a `$skill-name "intent"` invocation together with context accumulated from prior steps. The agent executes the skill and returns structured findings; those findings are injected into the next step's spawn message as `## Context from Previous Steps`.
+<purpose>
+Sequential CLI-delegate coordinator. Each chain step executes via `maestro delegate "prompt" --to <tool> --mode write`
+with a template-driven prompt. After each step, gemini analysis evaluates output quality and generates
+optimization hints for subsequent steps. All execution is background-async with hook callbacks.
 
 ```
-Intent  →  Resolve Chain  →  Step 1  →  Step 2  →  …  →  Step N  →  Report
-              (chainMap)     spawn         spawn               spawn
-                             wait          wait                wait
-                             close         close               close
-                              │             │                   │
-                           findings  →  prev_context  →  prev_context
+Intent  →  Resolve Chain  →  Step 1  →  Analysis  →  Step 2  →  Analysis  →  …  →  Report
+              (chainMap)     delegate    gemini       delegate    gemini
+                             callback   callback     callback    callback
 ```
+</purpose>
 
----
+<required_reading>
+@~/.maestro/workflows/maestro-coordinate.codex.md — authoritative `detectTaskType`, `detectNextAction`, `chainMap` (35+ intent patterns, 40+ chain types). Read before executing any step.
+</required_reading>
 
-## Chain Map
+<deferred_reading>
+- [coordinate template](~/.maestro/templates/cli/prompts/coordinate-step.txt) — read when filling step prompts
+</deferred_reading>
 
-| Intent keywords | Chain | Steps (skills, in order) |
-|----------------|-------|--------------------------|
-| fix, bug, error, broken, crash | `quality-fix` | $manage-issue-analyze → $manage-issue-execute → $maestro-verify |
-| test, spec, coverage | `quality-test` | $quality-test |
-| refactor, cleanup, debt | `quality-refactor` | $quality-refactor |
-| feature, implement, add, build | `feature` | $maestro-plan → $maestro-execute → $maestro-verify |
-| review, check, audit | `quality-review` | $quality-review |
-| deploy, release, ship | `deploy` | $maestro-verify → $maestro-execute |
+<context>
+$ARGUMENTS — user intent text, or special flags.
 
----
+**Flags:**
+- `-y, --yes` — Auto mode: skip all prompts, inject auto-confirm into delegates
+- `-c, --continue` — Resume previous session from last incomplete step
+- `--dry-run` — Show planned chain without executing
+- `--chain <name>` — Force specific chain (skips intent classification)
 
-## Implementation
+**Session state**: `.workflow/.maestro-coordinate/{session-id}/state.json`
+</context>
+
+<invariants>
+1. **STOP after each delegate call**: Background execution via `run_in_background: true`, wait for hook callback.
+2. **State machine**: Advance via `current_step`, no sync loops for async operations.
+3. **Template-driven**: All steps use `coordinate-step.txt`, no per-command prompt assembly.
+4. **Context propagation**: Parse PHASE / spec session ID / scratch_dir / issue_id from each step output, feed to next step.
+5. **Gemini analysis after each step**: Evaluate output quality, generate hints for next step, chain via `--resume`.
+6. **Auto-confirm injection**: `{{AUTO_DIRECTIVE}}` in template prevents blocking during background execution.
+7. **Resumable**: `-c` reads `state.json`, jumps to first pending step.
+8. **Delegate tool**: `maestro delegate --to codex` for all execution steps; `--to gemini` only for post-step analysis.</invariants>
 
-> **Full implementation reference**: The complete `detectTaskType`, `detectNextAction`, and `chainMap` definitions (35+ intent patterns, 40+ chain types) are in `~/.maestro/workflows/maestro-coordinate.codex.md`. Read that file for authoritative logic before executing any step.
+<execution>
 
-### Session Initialization
+### Step 1: Parse Arguments
 
 ```javascript
-const dateStr = new Date().toISOString().substring(0, 10).replace(/-/g, '')
-const timeStr = new Date().toISOString().substring(11, 19).replace(/:/g, '')
-const sessionId = `MCC-${dateStr}-${timeStr}`
-const sessionDir = `.workflow/.maestro-coordinate/${sessionId}`
-
-Bash(`mkdir -p ${sessionDir}`)
-
-functions.update_plan({
-  explanation: "Starting coordinate session",
-  plan: [
-    { step: "Phase 1: Resolve intent and chain", status: "in_progress" },
-    { step: "Phase 2: Execute steps (pipeline)", status: "pending" },
-    { step: "Phase 3: Completion report", status: "pending" }
-  ]
-})
+const args = $ARGUMENTS.trim();
+const AUTO_YES = /\b(-y|--yes)\b/.test(args);
+const RESUME = /\b(-c|--continue)\b/.test(args);
+const DRY_RUN = /\b--dry-run\b/.test(args);
+const forcedChain = args.match(/--chain\s+(\S+)/)?.[1] || null;
+const intent = args
+  .replace(/\b(-y|--yes|-c|--continue|--dry-run)\b/g, '')
+  .replace(/--chain\s+\S+/g, '')
+  .trim();
 ```
 
-### Phase 1: Resolve Intent and Chain
+**If RESUME**: Find latest `state.json` in `.workflow/.maestro-coordinate/`, load → jump to Step 6.
 
-**`--continue` mode**: Glob `.workflow/.maestro-coordinate/MCC-*/state.json` sorted by name desc; load the most recent; skip to Phase 2 at the first step where `status === "pending"`.
+### Step 2–4: Classify Intent → Confirm
 
-**Fresh mode**:
+1. Read `.workflow/state.json` + `.workflow/roadmap.md` + current phase
+2. If `--chain` given → use directly; else classify via `detectTaskType` + `chainMap`
+3. If clarity < 2 and not AUTO_YES → clarify via AskUserQuestion (max 2 rounds)
+4. **`--dry-run`**: Display chain and exit
+5. **User confirmation** (skip if AUTO_YES): Execute / Execute from step N / Cancel
 
-1. Read `.workflow/state.json` for project context (`current_phase`, `workflow_name`)
-2. If `--chain` is given, use it directly
-3. Otherwise, classify intent with keyword heuristics (see Chain Map above)
-4. If no keyword matches and not `AUTO_YES`: ask one clarifying question via `functions.request_user_input`
-5. Resolve the chain's skill list from Chain Map
-6. Write `state.json`:
+### Step 5: Setup Session
 
 ```javascript
-Write(`${sessionDir}/state.json`, JSON.stringify({
-  id: sessionId,
-  intent,
-  chain: resolvedChain,
-  auto_yes: AUTO_YES,
-  status: "in_progress",
-  started_at: new Date().toISOString(),
-  steps: CHAIN_MAP[resolvedChain].map((skill, i) => ({
-    step_n: i + 1,
-    skill,
-    status: "pending",
-    findings: null,
-    quality_score: null,
-    hints_for_next: null
+const sessionId = `coord-${new Date().toISOString().replace(/[-:T]/g, '').slice(0, 15)}`;
+const sessionDir = `.workflow/.maestro-coordinate/${sessionId}`;
+
+const state = {
+  session_id: sessionId, status: 'running',
+  created_at: new Date().toISOString(),
+  intent, task_type: taskType, chain_name: chainName,
+  auto_mode: AUTO_YES, phase: resolvedPhase,
+  current_step: 0, gemini_session_id: null, step_analyses: [],
+  steps: chain.map((s, i) => ({
+    index: i, cmd: s.cmd, args: s.args || '',
+    status: 'pending', exec_id: null, analysis: null
   }))
-}, null, 2))
-```
-
-**`--dry-run`**: Display the chain plan and stop — no agents spawned.
-
-```
-Chain:  <resolvedChain>
-Steps:
-  1. <skill-1>
-  2. <skill-2>
-  3. <skill-3>
-```
-
-**User confirmation** (skip if `AUTO_YES`): Display the plan above and prompt `Proceed? (yes/no)`.
-
-```javascript
-functions.update_plan({
-  explanation: "Chain resolved, starting pipeline",
-  plan: [
-    { step: "Phase 1: Resolve intent and chain", status: "completed" },
-    { step: "Phase 2: Execute steps (pipeline)", status: "in_progress" },
-    { step: "Phase 3: Completion report", status: "pending" }
-  ]
-})
+};
+Write(`${sessionDir}/state.json`, JSON.stringify(state, null, 2));
 ```
 
----
+### Step 6: Execute Step via maestro delegate
 
-### Phase 2: Execute Steps (Pipeline)
-
-Sequential loop — each step spawns one agent, waits for it, extracts findings, then closes it before spawning the next.
+#### 6a: Assemble args
 
 ```javascript
-let prevContext = ''  // accumulates across steps
-
-for (const step of state.steps.filter(s => s.status === 'pending')) {
-  const skillFlag = AUTO_YES ? `-y` : ''
-
-  // Assemble the agent prompt with the skill invocation embedded
-  const stepPrompt = buildStepPrompt({
-    step,
-    totalSteps: state.steps.length,
-    chain: state.chain,
-    intent: state.intent,
-    prevContext,
-    skillFlag,
-    sessionDir
-  })
-
-  // Spawn step agent
-  const agent = spawn_agent({ message: stepPrompt })
-
-  // Wait — initial spawn: 30 min
-  let result = wait_agent({ timeout_ms: 1800000 })
-  if (result.timed_out) {
-    // Step 1: Status probe (non-interrupting, 3 min)
-    followup_task({ target: agent, message: "STATUS_CHECK: Report current progress, findings so far, and estimated remaining work." })
-    const status = wait_agent({ timeout_ms: 180000 })
-    if (status.timed_out) {
-      // Step 2: Force finalize (interrupt, 3 min)
-      followup_task({ target: agent, message: "FINALIZE: Output all current findings immediately. Time limit reached.", interrupt: true })
-      const forced = wait_agent({ timeout_ms: 180000 })
-      if (forced.timed_out) {
-        // Step 3: Abort
-        close_agent({ target: agent })
-      } else {
-        result = forced
-      }
-    } else {
-      result = status
-    }
-  }
-
-  // Parse structured output from agent
-  const output = parseLastJSON(result.status[agent].completed) ?? {
-    quality_score: null,
-    findings: result.status[agent].completed?.slice(-500) ?? "(no output)",
-    hints_for_next: ""
-  }
-
-  close_agent({ target: agent })
-
-  // Persist step result
-  step.status = result.timed_out ? "failed" : "completed"
-  step.findings = output.findings
-  step.quality_score = output.quality_score
-  step.hints_for_next = output.hints_for_next
-  step.completed_at = new Date().toISOString()
-  Write(`${sessionDir}/state.json`, JSON.stringify(state, null, 2))
-
-  // Build prev_context for next step
-  prevContext += `\n\n## Step ${step.step_n}: ${step.skill}\nFindings: ${step.findings}\nHints: ${step.hints_for_next ?? ''}`
-
-  // Abort on failure — mark remaining steps as skipped
-  if (step.status === "failed") {
-    state.steps
-      .filter(s => s.status === 'pending')
-      .forEach(s => { s.status = 'skipped'; s.findings = `Blocked: step ${step.step_n} (${step.skill}) failed` })
-    state.status = "aborted"
-    Write(`${sessionDir}/state.json`, JSON.stringify(state, null, 2))
-    break
+const AUTO_FLAG_MAP = {
+  'maestro-analyze': '-y', 'maestro-brainstorm': '-y', 'maestro-ui-design': '-y',
+  'maestro-plan': '--auto', 'maestro-spec-generate': '-y', 'quality-test': '--auto-fix',
+  'quality-retrospective': '--auto-yes',
+};
+
+function assembleArgs(step) {
+  let a = (step.args || '')
+    .replace(/\{phase\}/g, context.current_phase || '')
+    .replace(/\{description\}/g, context.user_intent || '')
+    .replace(/\{issue_id\}/g, context.issue_id || '')
+    .replace(/\{spec_session_id\}/g, context.spec_session_id || '')
+    .replace(/\{scratch_dir\}/g, context.scratch_dir || '');
+  if (state.auto_mode) {
+    const flag = AUTO_FLAG_MAP[step.cmd];
+    if (flag && !a.includes(flag)) a = a ? `${a} ${flag}` : flag;
   }
+  return a.trim();
 }
 ```
 
----
-
-#### Step Agent Prompt Template (`buildStepPrompt`)
+#### 6b: Build prompt from template + launch
 
-The assembled prompt embeds the skill call so the agent knows exactly what to invoke:
+Read `~/.maestro/templates/cli/prompts/coordinate-step.txt`, fill placeholders.
+If previous step has analysis hints, inject as `{{ANALYSIS_HINTS}}`.
 
+```javascript
+const prompt = template
+  .replace('{{COMMAND}}', `/${step.cmd}`)
+  .replace('{{ARGS}}', assembledArgs)
+  .replace('{{STEP_N}}', `${state.current_step + 1}/${state.steps.length}`)
+  .replace('{{AUTO_DIRECTIVE}}', state.auto_mode ? 'Auto-confirm all prompts. No interactive questions.' : '')
+  .replace('{{CHAIN_NAME}}', state.chain_name)
+  .replace('{{ANALYSIS_HINTS}}', analysisHints);
+
+Bash({
+  command: `maestro delegate ${escapeForShell(prompt)} --to codex --mode write`,
+  run_in_background: true, timeout: 600000
+});
+// ■ STOP — wait for hook callback
 ```
-## TASK ASSIGNMENT
-
-### MANDATORY FIRST STEPS
-1. Read: ~/.maestro/workflows/maestro-coordinate.codex.md
-2. Read: ~/.codex/skills/{skill}/SKILL.md
-
----
-
-**Coordinate Chain: {chain}  |  Step {step_n} of {totalSteps}**
-
-## Skill Invocation
-Execute this skill call to complete your task:
-
-  ${skill} "{intent}" {skillFlag}
-
-Follow the Implementation section of the skill file you read in step 2.
-The intent above is your driving goal.
-
-{#if prevContext}
-## Context from Previous Steps
-{prevContext}
-
-Use hints from the previous step to guide execution priorities.
-{/if}
 
-## Output (required — last JSON block in your response)
-After execution complete, output exactly:
-```json
-{
-  "quality_score": <0-10>,
-  "findings": "<what was accomplished — max 500 chars>",
-  "hints_for_next": "<specific guidance for the next chain step>"
-}
-```
+### Step 7: Post-Step Callback
 
-Session artifacts: {sessionDir}/
+```javascript
+// Context propagation from output
+const phaseMatch = output.match(/PHASE:\s*(\d+)/m);
+if (phaseMatch) context.current_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);
+if (scratchMatch) context.scratch_dir = scratchMatch[1].trim();
+
+// Success/failure
+const failed = /^STATUS:\s*FAILURE/m.test(output);
+if (!failed) { step.status = 'completed'; }
+else if (state.auto_mode && !step.retried) { step.retried = true; /* re-execute Step 6 */ return; }
+else { step.status = 'skipped'; /* or AskUserQuestion: Retry / Skip / Abort */ }
+
+Write(`${sessionDir}/step-${stepIdx + 1}-output.txt`, output);
+// → Step 7b (gemini analysis) if completed + multi-step chain
+// → else advance current_step, loop to Step 6 or Step 8
 ```
 
----
-
-### Phase 3: Completion Report
+### Step 7b: Analyze Step Output (via gemini)
 
 ```javascript
-state.status = state.steps.every(s => s.status === 'completed') ? "completed" : state.status
-Write(`${sessionDir}/state.json`, JSON.stringify(state, null, 2))
-
-functions.update_plan({
-  explanation: "Coordinate complete",
-  plan: [
-    { step: "Phase 1: Resolve intent and chain", status: "completed" },
-    { step: "Phase 2: Execute steps (pipeline)", status: "completed" },
-    { step: "Phase 3: Completion report", status: "completed" }
-  ]
-})
-```
-
-Display:
+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
 ```
-=== COORDINATE COMPLETE ===
-Session:  <sessionId>
-Chain:    <chain>
-Steps:    <N completed>/<total>
-
-STEP RESULTS:
-  [1] <skill>  — score: <N>/10  ✓  <findings summary>
-  [2] <skill>  — score: <N>/10  ✓  <findings summary>
-  [3] <skill>  — score: <N>/10  ✓  <findings summary>
-
-State:  .workflow/.maestro-coordinate/<sessionId>/state.json
-Resume: $maestro-coordinate --continue
-```
-
----
 
-## Error Handling
+Post-analyze: store quality_score + issues + next_step_hints in `state.step_analyses[]`, chain gemini sessions via `--resume`.
 
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Intent unclassifiable after clarification | Default to `feature` chain; note in state.json |
-| E002 | error | `--chain` value not in chain map | List valid chains, abort |
-| E003 | error | Step agent timeout (4-step cascade exhausted) | Mark step `failed`; skip remaining steps; suggest `--continue` |
-| E004 | error | Step agent failed (non-JSON output) | Mark step `failed`; preserve raw output in `findings`; skip remaining |
-| E005 | error | `--continue`: no session found | Glob `.workflow/.maestro-coordinate/MCC-*/`, list sessions, prompt |
-| W001 | warning | Step output JSON missing `hints_for_next` | Continue with empty hints; next step still gets `findings` |
+### Step 8: Completion Report
 
----
-
-## Core Rules
-
-1. **Start Immediately**: Init session dir and write `state.json` before any spawn
-2. **Sequential**: Never spawn step N+1 until step N agent is closed and results written
-3. **Skill in Prompt**: Every step agent's message MUST contain `$skill-name "intent"` — this is how the agent knows which skill to execute
-4. **State.json is source of truth**: Write after every step; `--continue` reads it to resume
-5. **Skip on Failure**: Step failure immediately marks all remaining steps `skipped` and aborts the loop
-6. **Close before spawn**: Always `close_agent` the current step agent before spawning the next
-7. **Dry-run is read-only**: Stop after displaying the chain plan — never spawn agents
-8. **Timeout handling**: 4-step cascade — status probe → force finalize → abort; if all timed out → mark `failed`
-9. **No CLI fallback**: All execution is agent-native — no `exec_command("maestro delegate ...")`
+```
+============================================================
+  MAESTRO-COORDINATE COMPLETE
+============================================================
+  Session: {session_id}
+  Chain:   {chain_name} ({done}/{total})
+
+  Steps:
+    [✓] 1. maestro-plan — completed (quality: 85/100)
+    [✓] 2. maestro-execute — completed (quality: 78/100)
+
+  Avg Quality: {avg_score}/100
+  Next: $maestro-coordinate --continue
+============================================================
+```
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | No intent and project not initialized | Suggest $maestro-init |
+| E002 | error | Clarity too low after 2 rounds | Ask to rephrase |
+| E003 | error | Step failed + abort | Suggest resume with -c |
+| E004 | error | Resume session not found | Show available sessions |
+</error_codes>
+
+<success_criteria>
+- [ ] Intent classified and chain selected via detectTaskType + chainMap
+- [ ] Each step executed via `maestro delegate` with coordinate-step template
+- [ ] Auto-confirm injected, structured return parsed
+- [ ] Each completed step analyzed via `maestro delegate --to gemini --mode analysis`
+- [ ] Analysis hints injected into next step prompt via `{{ANALYSIS_HINTS}}`
+- [ ] Gemini sessions chained via `--resume` for accumulated context
+- [ ] Session state at .workflow/.maestro-coordinate/{session_id}/
+- [ ] Completion report with per-step status and quality scores
+</success_criteria>