maestro-flow 0.3.9 → 0.3.10

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

@@ -1,15 +1,15 @@
 ---
 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 codex 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>] [--tool <tool>]"
+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.
+When `-y` or `--yes`: Skip clarification and confirmation prompts. Auto-confirm all delegate executions.
 
-# Maestro Coordinate
+# Maestro Coordinate (CLI Delegate)
 
 ## Usage
 
@@ -19,13 +19,15 @@ $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"
+$maestro-coordinate --tool gemini "fix auth regression"
 ```
 
 **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
+- `-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 a specific chain (skips intent classification)
+- `--tool <tool>` — CLI tool override (default: codex)
 
 **Session state**: `.workflow/.maestro-coordinate/{session-id}/state.json`
 
@@ -33,292 +35,345 @@ $maestro-coordinate --chain feature "add dark mode toggle"
 
 ## 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`.
+Sequential CLI-delegate coordinator. Each chain step is executed via `codex delegate "prompt" --to <tool> --mode write` with a template-driven prompt. After each step completes, a 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
 ```
 
 ---
 
-## Chain Map
-
-| 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 |
-
----
-
 ## Implementation
 
 > **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.
 
-### Session Initialization
+<required_reading>
+@~/.maestro/workflows/maestro-coordinate.codex.md
+</required_reading>
+
+<deferred_reading>
+- [coordinate template](~/.maestro/templates/cli/prompts/coordinate-step.txt) — read when filling step prompts
+</deferred_reading>
+
+### 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 cliTool = args.match(/--tool\s+(\S+)/)?.[1] || 'codex';
+const intent = args
+  .replace(/\b(-y|--yes|-c|--continue|--dry-run)\b/g, '')
+  .replace(/--(chain|tool)\s+\S+/g, '')
+  .trim();
 ```
 
-### Phase 1: Resolve Intent and Chain
+**If RESUME:**
+1. Find latest `state.json` in `.workflow/.maestro-coordinate/`
+2. Load state → set `current_step` to first non-completed step
+3. 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"`.
+---
 
-**Fresh mode**:
+### Step 2: Read Project State
 
-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`:
+Read `.workflow/state.json` + `.workflow/roadmap.md` + current phase `index.json`.
 
-```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
-  }))
-}, null, 2))
-```
+**If missing:** `projectState = { initialized: false }`. If intent also empty → Error E001.
+
+---
+
+### Step 3: Classify Intent & Select Chain
+
+Follow `~/.maestro/workflows/maestro-coordinate.md` Steps 3a–3d exactly:
+- Exact-match keywords (fast path)
+- Structured intent extraction (action × object matrix)
+- State-based routing for `state_continue`
+- Chain map lookup
+- Phase/issue ID resolution
+
+If clarity < 2 and not AUTO_YES: clarify via AskUserQuestion (max 2 rounds).
+
+---
 
-**`--dry-run`**: Display the chain plan and stop — no agents spawned.
+### Step 4: Confirm
+
+**If `DRY_RUN`:** Display chain and exit.
 
 ```
-Chain:  <resolvedChain>
-Steps:
-  1. <skill-1>
-  2. <skill-2>
-  3. <skill-3>
+MAESTRO-COORDINATE: {chain_name} (dry run)
+  1. [{cmd}] {args}
+  2. [{cmd}] {args}
 ```
 
-**User confirmation** (skip if `AUTO_YES`): Display the plan above and prompt `Proceed? (yes/no)`.
+**If not AUTO_YES:** AskUserQuestion — Execute / Execute from step N / Cancel.
+
+---
+
+### Step 5: Setup Session
 
 ```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" }
-  ]
-})
+const sessionId = `coord-${new Date().toISOString().replace(/[-:T]/g, '').slice(0, 15)}`;
+const sessionDir = `.workflow/.maestro-coordinate/${sessionId}`;
+Bash(`mkdir -p "${sessionDir}"`);
+
+const state = {
+  session_id: sessionId, status: 'running',
+  created_at: new Date().toISOString(),
+  intent, task_type: taskType, chain_name: chainName,
+  tool: cliTool, 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
+  }))
+};
+Write(`${sessionDir}/state.json`, JSON.stringify(state, null, 2));
 ```
 
 ---
 
-### Phase 2: Execute Steps (Pipeline)
+### Step 6: Execute Step via codex delegate
 
-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();
 }
 ```
 
----
+#### 6b: Build prompt from template
 
-#### Step Agent Prompt Template (`buildStepPrompt`)
+Read `~/.maestro/templates/cli/prompts/coordinate-step.txt`, fill placeholders.
+If previous step has analysis hints, inject them as `{{ANALYSIS_HINTS}}`.
 
-The assembled prompt embeds the skill call so the agent knows exactly what to invoke:
+```javascript
+function escapeForShell(str) { return "'" + str.replace(/'/g, "'\\''") + "'"; }
+
+const assembledArgs = assembleArgs(step);
+const template = Read('~/.maestro/templates/cli/prompts/coordinate-step.txt');
+
+let analysisHints = '';
+const prevAnalysis = (state.step_analyses || []).find(a => a.step_index === state.current_step - 1);
+if (prevAnalysis?.next_step_hints) {
+  const h = prevAnalysis.next_step_hints;
+  const parts = [];
+  if (h.prompt_additions) parts.push(h.prompt_additions);
+  if (h.cautions?.length) parts.push('Cautions: ' + h.cautions.join('; '));
+  if (h.context_to_carry) parts.push('Context from prior step: ' + h.context_to_carry);
+  if (parts.length) analysisHints = parts.join('\n');
+}
+
+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);
+```
 
+#### 6c: Launch via codex delegate
+
+```
+------------------------------------------------------------
+  STEP {i+1}/{total}: {step.cmd}  |  Tool: {cliTool}
+------------------------------------------------------------
 ```
-## TASK ASSIGNMENT
 
-### MANDATORY FIRST STEPS
-1. Read: ~/.maestro/workflows/maestro-coordinate.codex.md
-2. Read: ~/.codex/skills/{skill}/SKILL.md
+```javascript
+state.steps[state.current_step].status = 'running';
+state.steps[state.current_step].started_at = new Date().toISOString();
+Write(`${sessionDir}/state.json`, JSON.stringify(state, null, 2));
+
+Bash({
+  command: `codex delegate ${escapeForShell(prompt)} --to ${state.tool} --mode write`,
+  run_in_background: true, timeout: 600000
+});
+// ■ STOP — wait for hook callback
+```
 
 ---
 
-**Coordinate Chain: {chain}  |  Step {step_n} of {totalSteps}**
+### Step 7: Post-Step Callback
 
-## Skill Invocation
-Execute this skill call to complete your task:
+```javascript
+const stepIdx = state.current_step;
+const step = state.steps[stepIdx];
+const output = /* callback output */;
+
+step.exec_id = /* from callback stderr */;
+step.completed_at = new Date().toISOString();
+
+// Context propagation
+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) {
+  if (!step.retried) { step.retried = true; /* re-execute Step 6c */ return; }
+  step.status = 'skipped';
+} else {
+  // AskUserQuestion: Retry / Skip / Abort
+}
 
-  ${skill} "{intent}" {skillFlag}
+Write(`${sessionDir}/step-${stepIdx + 1}-output.txt`, output);
+Write(`${sessionDir}/state.json`, JSON.stringify(state, null, 2));
+
+// → Step 7b: Gemini analysis (skip if step failed/skipped or single-step chain)
+if (step.status === 'completed' && state.steps.length > 1) {
+  // → Step 7b
+} else {
+  state.current_step = stepIdx + 1;
+  Write(`${sessionDir}/state.json`, JSON.stringify(state, null, 2));
+  if (state.current_step < state.steps.length) { /* → Step 6 */ }
+  else { /* → Step 8 */ }
+}
+```
 
-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}
+### Step 7b: Analyze Step Output (via gemini)
 
-Use hints from the previous step to guide execution priorities.
-{/if}
+After each step completes, call gemini to evaluate execution quality and generate optimization hints.
 
-## Output (required — last JSON block in your response)
-After execution complete, output exactly:
-```json
+```javascript
+const analysisPrompt = `PURPOSE: Evaluate execution quality of coordinate step "${step.cmd}" and generate optimization hints for the next step.
+CHAIN: ${state.chain_name} | Intent: ${state.intent}
+COMMAND: /${step.cmd} ${step.args || ''}
+STEP OUTPUT (last 200 lines):
+${output.split('\n').slice(-200).join('\n')}
+NEXT STEP: ${nextStep ? `/${nextStep.cmd} ${nextStep.args || ''}` : 'None (last step)'}
+EXPECTED OUTPUT (strict JSON):
 {
-  "quality_score": <0-10>,
-  "findings": "<what was accomplished — max 500 chars>",
-  "hints_for_next": "<specific guidance for the next chain step>"
-}
+  "quality_score": <0-100>,
+  "execution_assessment": { "success": <bool>, "completeness": "<full|partial|minimal>", "key_outputs": [], "missing_outputs": [] },
+  "issues": [{ "severity": "critical|high|medium|low", "description": "" }],
+  "next_step_hints": {
+    "prompt_additions": "<extra context or constraints to inject into next step prompt>",
+    "cautions": ["<things next step should watch out for>"],
+    "context_to_carry": "<key facts from this step's output that next step needs>"
+  },
+  "step_summary": ""
+}`;
+
+let delegateCmd = `codex 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
 ```
 
-Session artifacts: {sessionDir}/
+### Step 7c: Post-Analyze Callback
+
+```javascript
+const analysisResult = /* parsed JSON from callback output */;
+state.gemini_session_id = /* from callback stderr */;
+
+if (!state.step_analyses) state.step_analyses = [];
+state.step_analyses.push({
+  step_index: stepIdx, cmd: step.cmd,
+  quality_score: analysisResult.quality_score,
+  issues: analysisResult.issues,
+  next_step_hints: analysisResult.next_step_hints,
+  summary: analysisResult.step_summary
+});
+step.analysis = {
+  quality_score: analysisResult.quality_score,
+  issue_count: (analysisResult.issues || []).length
+};
+Write(`${sessionDir}/step-${stepIdx + 1}-analysis.json`, JSON.stringify(analysisResult, null, 2));
+
+// Advance
+state.current_step = stepIdx + 1;
+Write(`${sessionDir}/state.json`, JSON.stringify(state, null, 2));
+
+if (state.current_step < state.steps.length) { /* → Step 6 */ }
+else { /* → Step 8 */ }
 ```
 
 ---
 
-### Phase 3: Completion Report
+### Step 8: Completion Report
 
 ```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" }
-  ]
-})
+const done = state.steps.filter(s => s.status === 'completed').length;
+state.status = state.steps.some(s => s.status === 'failed') ? 'completed_with_errors' : 'completed';
+state.completed_at = new Date().toISOString();
+Write(`${sessionDir}/state.json`, JSON.stringify(state, null, 2));
 ```
 
-Display:
 ```
-=== 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
+============================================================
+  MAESTRO-COORDINATE COMPLETE
+============================================================
+  Session: {session_id}
+  Chain:   {chain_name} ({done}/{total})
+  Tool:    {cliTool}
+
+  Steps:
+    [✓] 1. maestro-plan — completed (quality: 85/100)
+    [✓] 2. maestro-execute — completed (quality: 78/100)
+
+  Avg Quality: {avg_score}/100
+  Next: $maestro-coordinate --continue
+============================================================
 ```
 
 ---
 
 ## Error Handling
 
-| 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` |
+| 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 |
+| E005 | error | CLI tool unavailable | Try fallback tool |
 
 ---
 
 ## 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 ...")`
+1. **Semantic routing** — LLM-native structured extraction (`action × object`) replaces regex; disambiguates by context
+2. **STOP after each `codex 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 `codex 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 `codex delegate --to gemini --mode analysis`, chained via `--resume`
+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/.codex/skills/maestro-execute/SKILL.md

@@ -308,6 +308,14 @@ If a task is blocked/failed and other tasks in later waves depend on it:
    - Update `status` to match CSV status
    - Write back to disk
 
+3b. **Issue status sync**: For each completed/failed task that has `issue_id`:
+   - Read issue from `.workflow/issues/issues.jsonl` by `issue_id`
+   - Collect all `task_refs[]` statuses for that issue:
+     - All task_refs completed → `issue.status = "resolved"`
+     - Any task_ref failed → `issue.status = "in_progress"`
+   - Append history entry: `{ action: "executed", at: <ISO>, by: "maestro-execute", summary: "TASK-{NNN} {status}" }`
+   - Write updated issue back to `issues.jsonl`
+
 4. **Register EXC artifact in state.json**:
    ```
    Read .workflow/state.json

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

@@ -404,7 +404,15 @@ spawn_agents_on_csv({
    }
    ```
 
-5. **Issue linking** (if --gaps): Update issues in `issues.jsonl` with status `planned`, link to TASK IDs.
+5. **Issue linking** (if --gaps):
+   For each created TASK-{NNN}.json that has `issue_id`:
+   - Update corresponding issue in `.workflow/issues/issues.jsonl`:
+     - `task_refs`: append TASK-{NNN} to array
+     - `task_plan_dir`: relative path to `.task/` directory
+     - `status`: "planned"
+     - `updated_at`: now()
+   - Append history entry: `{ action: "planned", at: <ISO>, by: "maestro-plan", summary: "Linked to TASK-{NNN}" }`
+   This ensures bidirectional issue ↔ TASK traceability for dashboard display.
 
 6. **Display summary + options** (skip options if AUTO_YES):
    ```