maestro-flow 0.3.9 → 0.3.10

package/workflows/maestro.md

@@ -531,9 +531,9 @@ const chainMap = {
   'memory_capture':     [{ cmd: 'manage-memory-capture', 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: '' }],
   'memory':             [{ cmd: 'manage-memory', args: '"{description}"' }],
   'quick':              [{ cmd: 'maestro-quick', args: '"{description}"' }],
   'fork':               [{ cmd: 'maestro-fork', args: '-m {milestone_num}' }],
@@ -614,15 +614,15 @@ const chainMap = {
   ],
   // 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: '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: 'manage-issue-plan', args: '{issue_id}' },
-    { cmd: 'manage-issue-execute', args: '{issue_id}' },
+    { cmd: 'maestro-plan', args: '--gaps' },
+    { cmd: 'maestro-execute', args: '' },
     { cmd: 'manage-issue', args: 'close {issue_id} --resolution fixed' }
   ]
 };
@@ -669,7 +669,6 @@ function resolvePhase(intent_analysis, project_state) {
 
   // 5. Chain doesn't need phase (init, status, memory, issue, etc.)
   const noPhaseCommands = ['manage-status', 'manage-issue', 'manage-issue-discover',
-    'manage-issue-analyze', 'manage-issue-plan', 'manage-issue-execute',
     'maestro-init', 'maestro-spec-generate', 'maestro-fork', 'maestro-merge',
     'maestro-roadmap', 'spec-setup', 'manage-memory', 'manage-memory-capture', 'manage-learn',
     'manage-codebase-rebuild', 'manage-codebase-refresh', 'maestro-milestone-audit',
@@ -939,8 +938,8 @@ Shows how structured extraction routes common inputs — especially cases where
 | `"这个问题需要看看"` | `{analyze, bug}` | analyze | maestro-analyze |
 | `"创建一个 issue 跟踪"` | `{manage, issue}` | issue | manage-issue |
 | `"discover issues"` | `{explore, issue}` | issue_discover | manage-issue-discover |
-| `"analyze issue ISS-xxx"` | `{analyze, issue, ISS-xxx}` | issue_analyze | manage-issue-analyze |
-| `"plan issue ISS-xxx"` | `{plan, issue, ISS-xxx}` | issue_plan | manage-issue-plan |
+| `"analyze issue ISS-xxx"` | `{analyze, issue, ISS-xxx}` | issue_analyze | maestro-analyze --gaps |
+| `"plan issue ISS-xxx"` | `{plan, issue, ISS-xxx}` | issue_plan | maestro-plan --gaps |
 | `"brainstorm notification system"` | `{explore, feature}` | brainstorm | brainstorm-driven |
 | `"spec generate user auth"` | `{create, spec}` | spec_generate | spec-driven |
 | `"ui design landing page"` | `{create, ui}` | ui_design | ui-design-driven |

package/workflows/retrospective.md

@@ -11,7 +11,7 @@ This is a **post-execution analysis** workflow. It reads only — until the rout
 - `.workflow/` initialized (`.workflow/state.json` exists)
 - At least one phase directory under `.workflow/phases/{NN}-{slug}/`
 - Target phase has been executed (has `.task/` and `.summaries/`)
-- `maestro cli` available (used for the four lens analyses via Agent calls)
+- `maestro delegate` available (used for the four lens analyses via Agent calls)
 
 ---
 

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

@@ -1,62 +0,0 @@
----
-name: manage-issue-analyze
-description: Root cause analysis for a specific issue using CLI exploration
-argument-hint: "<ISS-ID> [--tool gemini|qwen] [--depth standard|deep]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Root cause analysis for a specific issue. Uses CLI exploration to analyze codebase context, identify root cause, assess impact, and produce a structured analysis record attached to the issue in `.workflow/issues/issues.jsonl`.
-
-- **--tool**: CLI tool for analysis (default: gemini)
-- **--depth**: `standard` (keyword grep) or `deep` (semantic search via Agent)
-
-For issue CRUD, use `/manage-issue`. For solution planning, use `/manage-issue-plan`.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/issue-analyze.md
-</required_reading>
-
-<deferred_reading>
-- [issue.json template](~/.maestro/templates/issue.json) -- read when building the analysis record structure
-</deferred_reading>
-
-<context>
-$ARGUMENTS -- ISS-ID (required) + optional flags.
-
-**Options:**
-- `<ISS-ID>` -- issue ID in ISS-XXXXXXXX-NNN format (required)
-- `--tool gemini|qwen` -- CLI tool for analysis (default: gemini)
-- `--depth standard|deep` -- analysis depth (default: standard)
-
-**State files:**
-- `.workflow/issues/issues.jsonl` -- issue records (read + write)
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/issue-analyze.md' completely.
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E_NO_ISSUE_ID | error | No ISS-ID provided in $ARGUMENTS | Display usage hint with example |
-| E_ISSUE_NOT_FOUND | error | ISS-ID not found in issues.jsonl | Suggest `/manage-issue list` to find valid IDs |
-| E_INVALID_STATUS | warning | Issue status is not 'open' or 'registered' | Warn but allow analysis to proceed |
-| E_ANALYSIS_FAILED | error | CLI analysis returned no usable results | Retry with different --tool or report partial context |
-</error_codes>
-
-<success_criteria>
-- [ ] Issue loaded and validated from issues.jsonl
-- [ ] Codebase context gathered (grep or semantic search)
-- [ ] CLI analysis executed and JSON result parsed
-- [ ] Analysis record attached to issue in issues.jsonl
-- [ ] Summary displayed with next-step routing to manage-issue-plan
-</success_criteria>

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

@@ -1,73 +0,0 @@
----
-name: manage-issue-execute
-description: Execute planned solution for an issue via dual-mode agent dispatch
-argument-hint: "<ISS-ID> [--executor claude-code|codex|gemini] [--dry-run]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Execute a planned solution for a specific issue. Supports dual-mode dispatch:
-
-- **Server UP**: POST to `/api/execution/dispatch` for orchestrated execution
-- **Server DOWN**: Direct execution via `maestro delegate` with the solution prompt
-
-Options:
-- **--executor**: Agent to execute the solution (default: claude-code)
-- **--dry-run**: Display the constructed prompt and steps without executing
-
-For issue CRUD, use `/manage-issue`. For analysis, use `/manage-issue-analyze`. For planning, use `/manage-issue-plan`.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/issue-execute.md
-</required_reading>
-
-<deferred_reading>
-- [issue.json template](~/.maestro/templates/issue.json) -- read when updating issue status after execution
-</deferred_reading>
-
-<context>
-$ARGUMENTS -- ISS-ID (required) + optional flags.
-
-**Options:**
-- `<ISS-ID>` -- issue ID in ISS-XXXXXXXX-NNN format (required)
-- `--executor claude-code|codex|gemini` -- execution agent (default: claude-code)
-- `--dry-run` -- preview prompt and steps without executing
-
-**State files:**
-- `.workflow/issues/issues.jsonl` -- issue records (read + write)
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/issue-execute.md' completely.
-
-**Next-step routing on completion:**
-- Execution succeeded → `/manage-issue close <ISS-ID> --resolution fixed`
-- Execution failed → `/quality-debug <failure description>` then retry
-- Want verification → `/maestro-verify {phase}`
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E_NO_ISSUE_ID | error | No ISS-ID provided in $ARGUMENTS | Display usage hint with example |
-| E_NO_SOLUTION | error | Issue has no solution record (issue.solution is null) | Suggest `/manage-issue-plan` first |
-| E_DISPATCH_FAILED | error | Server dispatch or CLI execution failed | Log error, revert status to open, display failure details |
-</error_codes>
-
-<success_criteria>
-- [ ] Issue loaded with valid solution record
-- [ ] Execution mode detected (server UP or DOWN)
-- [ ] Solution executed (or dry-run displayed)
-- [ ] Issue status updated in issues.jsonl (in_progress -> resolved or open on failure)
-- [ ] Result summary displayed with next-step routing:
-  - Execution succeeded → `/manage-issue close <ISS-ID> --resolution fixed`
-  - Execution failed → `/quality-debug <failure description>` then retry
-  - Want verification → `/maestro-verify {phase}`
-</success_criteria>

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

@@ -1,62 +0,0 @@
----
-name: manage-issue-plan
-description: Solution planning for a specific issue with codebase-aware step generation
-argument-hint: "<ISS-ID> [--tool gemini|qwen] [--from-analysis]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Solution planning for a specific issue. Generates a structured, codebase-aware solution with ordered steps, context, and a prompt template for execution. Attaches the solution record to the issue in `.workflow/issues/issues.jsonl`.
-
-- **--tool**: CLI tool for planning (default: gemini)
-- **--from-analysis**: Auto-detected; includes analysis context (root_cause, related_files) in the planning prompt if issue.analysis exists
-
-For issue CRUD, use `/manage-issue`. For execution, use `/manage-issue-execute`.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/issue-plan.md
-</required_reading>
-
-<deferred_reading>
-- [issue.json template](~/.maestro/templates/issue.json) -- read when building the solution record structure
-</deferred_reading>
-
-<context>
-$ARGUMENTS -- ISS-ID (required) + optional flags.
-
-**Options:**
-- `<ISS-ID>` -- issue ID in ISS-XXXXXXXX-NNN format (required)
-- `--tool gemini|qwen` -- CLI tool for planning (default: gemini)
-- `--from-analysis` -- explicitly include analysis context (auto-detected if issue.analysis exists)
-
-**State files:**
-- `.workflow/issues/issues.jsonl` -- issue records (read + write)
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/issue-plan.md' completely.
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E_NO_ISSUE_ID | error | No ISS-ID provided in $ARGUMENTS | Display usage hint with example |
-| E_ISSUE_NOT_FOUND | error | ISS-ID not found in issues.jsonl | Suggest `/manage-issue list` to find valid IDs |
-| E_NO_ANALYSIS | warning | No analysis record on issue and --from-analysis specified | Proceed without analysis context, suggest `/manage-issue-analyze` first |
-| E_PLANNING_FAILED | error | CLI planning returned no usable results | Retry with different --tool or report partial output |
-</error_codes>
-
-<success_criteria>
-- [ ] Issue loaded and validated from issues.jsonl
-- [ ] Analysis context included in prompt (if available)
-- [ ] CLI planning executed and solution JSON parsed
-- [ ] Solution record attached to issue in issues.jsonl
-- [ ] Solution steps displayed with next-step routing to manage-issue-execute
-</success_criteria>

package/.codex/skills/manage-issue-analyze/SKILL.md

@@ -1,207 +0,0 @@
----
-name: manage-issue-analyze
-description: Root cause analysis for a specific issue via CLI exploration. Gathers codebase context (grep or semantic deep search), runs maestro delegate gemini analysis, and attaches a structured analysis record to the issue in issues.jsonl.
-argument-hint: "<ISS-ID> [--tool gemini|qwen] [--depth standard|deep]"
-allowed-tools: Read, Write, Bash, Glob, Grep
----
-
-# Issue Analyze
-
-## Usage
-
-```bash
-$manage-issue-analyze "ISS-20260401-001"
-$manage-issue-analyze "ISS-20260401-001 --depth deep"
-$manage-issue-analyze "ISS-20260401-001 --tool qwen --depth standard"
-```
-
-**Flags**:
-- `<ISS-ID>` — Issue ID in `ISS-XXXXXXXX-NNN` format (required)
-- `--tool gemini|qwen` — CLI tool for analysis (default: gemini)
-- `--depth standard|deep` — `standard` uses keyword grep; `deep` spawns a semantic explore agent (default: standard)
-
-**State files**: `.workflow/issues/issues.jsonl` (read + write)
-
----
-
-## Overview
-
-Sequential 4-step pipeline: load issue → gather codebase context → run CLI analysis → attach analysis record. The CLI analysis step invokes `maestro delegate --to gemini --mode analysis` to produce a structured root-cause record written back into issues.jsonl. This is the first step in the issue resolution workflow: **analyze → plan → execute**.
-
-```
-Load Issue  →  Gather Context  →  CLI Analysis  →  Attach Record
-(validate)     (grep / agent)     (gemini/qwen)    (apply_patch)
-```
-
----
-
-## Implementation
-
-### Step 1: Load and Validate Issue
-
-```javascript
-functions.update_plan({
-  explanation: "Starting issue analysis",
-  plan: [
-    { step: "Load and validate issue", status: "in_progress" },
-    { step: "Gather codebase context", status: "pending" },
-    { step: "Run CLI analysis", status: "pending" },
-    { step: "Attach analysis record", status: "pending" }
-  ]
-})
-```
-
-Read `.workflow/issues/issues.jsonl` line by line. Find the row where `id == <ISS-ID>`. Validate:
-- ISS-ID matches format `ISS-[0-9]{8}-[0-9]{3}`
-- Row found in file
-- Parse fields: `id`, `title`, `description`, `status`, `context`, `related_files`
-
-If `status` is not `open` or `registered`, emit W001 but continue.
-
-### Step 2: Gather Codebase Context
-
-**Standard depth** (default):
-- Grep key terms from `issue.title` + `issue.description` across `src/**` (-C 3)
-- If `issue.related_files` is set, read those files directly
-- Collect file:line references into `contextSummary`
-
-**Deep depth**:
-```javascript
-spawn_agent({
-  task_name: "ctx-explore",
-  fork_turns: "none",
-  message: `## TASK ASSIGNMENT
-
-### MANDATORY FIRST STEPS
-1. Read: ~/.codex/agents/cli-explore-agent.md
-
----
-
-Goal: Gather codebase context for issue root-cause analysis.
-Issue: <issue.title>
-Description: <issue.description>
-
-TASK: Find all code paths, functions, and modules related to this issue.
-Identify: affected locations (file:line), caller/callee chains, data flow, existing error handling.
-
-EXPECTED: JSON with: affected_files [{file, line, snippet, relevance}], related_modules, error_handling_gaps, test_coverage_gaps.
-`
-})
-const ctxResult = wait_agent({ timeout_ms: 1800000 })  // initial spawn: 30 min
-close_agent({ target: "ctx-explore" })
-```
-
-```javascript
-functions.update_plan({
-  explanation: "Context gathered",
-  plan: [
-    { step: "Load and validate issue", status: "completed" },
-    { step: "Gather codebase context", status: "completed" },
-    { step: "Run CLI analysis", status: "in_progress" },
-    { step: "Attach analysis record", status: "pending" }
-  ]
-})
-```
-
-### Step 3: Run CLI Analysis
-
-> **Prompt safety**: `issue.title` and `contextSummary` may contain quotes or shell-special characters. Write the full prompt to a temp file first and reference it via `$(cat ...)` to avoid shell injection.
-
-```javascript
-// Build prompt, write to temp file to avoid shell injection
-const promptContent = `PURPOSE: Root cause analysis for issue; identify exact cause, impact scope, fix direction; success = actionable record with file:line evidence.
-Issue: ${issue.id} — ${issue.title}
-TASK: Trace failure path | Map affected components | Assess blast radius | Define fix direction
-MODE: analysis
-CONTEXT: @src/**/* | Memory: ${contextSummary}
-EXPECTED: JSON: root_cause (string), affected_files (string[]), impact_scope (low|medium|high|critical), fix_direction (string), confidence (low|medium|high)
-CONSTRAINTS: Evidence required — file:line for each claim`
-
-Write(`/tmp/iss-analyze-${issue.id}.txt`, promptContent)
-functions.exec_command({
-  cmd: `maestro delegate "$(cat /tmp/iss-analyze-${issue.id}.txt)" --to ${tool} --mode analysis`,
-  workdir: "."
-})
-```
-
-Parse CLI output into `analysis` object:
-```json
-{
-  "root_cause": "...",
-  "affected_files": ["src/foo.ts:42"],
-  "impact_scope": "medium",
-  "fix_direction": "...",
-  "analyzed_at": "<ISO>",
-  "tool": "<tool>",
-  "depth": "<depth>",
-  "confidence": "medium"
-}
-```
-
-### Step 4: Attach Analysis Record and Report
-
-```javascript
-// Read issues.jsonl, update the matching line in-place
-const historyEntry = { action: "analyzed", at: new Date().toISOString(), by: "manage-issue-analyze", summary: `Root cause: ${analysis.root_cause}` }
-const raw = Read('.workflow/issues/issues.jsonl')
-const updated = raw.split('\n')
-  .filter(l => l.trim())
-  .map(l => {
-    const row = JSON.parse(l)
-    if (row.id !== issueId) return l
-    row.analysis = analysis
-    row.issue_history = [...(row.issue_history || []), historyEntry]
-    return JSON.stringify(row)
-  })
-  .join('\n') + '\n'
-Write('.workflow/issues/issues.jsonl', updated)
-```
-
-```javascript
-functions.update_plan({
-  explanation: "Analysis complete",
-  plan: [
-    { step: "Load and validate issue", status: "completed" },
-    { step: "Gather codebase context", status: "completed" },
-    { step: "Run CLI analysis", status: "completed" },
-    { step: "Attach analysis record", status: "completed" }
-  ]
-})
-```
-
-Display:
-```
-=== ANALYSIS COMPLETE ===
-Issue:       <ISS-ID>: <title>
-Root Cause:  <root_cause>
-Impact:      <impact_scope>
-Confidence:  <confidence>
-Affected:    <N> files
-
-Next: $manage-issue-plan "<ISS-ID>"
-```
-
----
-
-## Error Handling
-
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | No ISS-ID provided | Display usage hint with format example |
-| E002 | error | ISS-ID format invalid | Show correct format `ISS-XXXXXXXX-NNN` |
-| E003 | error | ISS-ID not found in issues.jsonl | Suggest `$manage-issue "list"` |
-| E004 | error | CLI analysis returned no parseable result | Retry with different `--tool`; report partial |
-| W001 | warning | Issue status is not open/registered | Warn, allow analysis to continue |
-
----
-
-## Core Rules
-
-1. **Start immediately**: First action is `update_plan` then issue load — no preamble
-2. **Validate before analysis**: Never run CLI without a valid loaded issue
-3. **Evidence required**: Analysis record must cite file:line — no speculative root causes
-4. **Deep agent lifecycle**: If deep spawned an agent, always `close_agent` before Step 3
-5. **Append-only history**: Append to `issue_history`, never overwrite existing entries
-- *Note*: `spawn_agent` / `wait_agent` / `close_agent` are Codex v4 built-in orchestration functions — they do not need to be listed in `allowed-tools`
-6. **Preserve existing fields**: Patch only `analysis` + `issue_history` — all other fields unchanged
-7. **Next-step routing**: Always display `$manage-issue-plan "<ISS-ID>"` at the end

package/.codex/skills/manage-issue-execute/SKILL.md

@@ -1,200 +0,0 @@
----
-name: manage-issue-execute
-description: Execute a planned solution for an issue via dual-mode dispatch. Auto-detects server UP (POST to /api/execution/dispatch) or DOWN (direct maestro delegate). Updates issue status on completion with next-step routing to close, debug, or verify.
-argument-hint: "<ISS-ID> [--executor claude-code|codex|gemini] [--dry-run]"
-allowed-tools: Read, Write, Bash, Glob, Grep
----
-
-# Issue Execute
-
-## Usage
-
-```bash
-$manage-issue-execute "ISS-20260401-001"
-$manage-issue-execute "ISS-20260401-001 --dry-run"
-$manage-issue-execute "ISS-20260401-001 --executor codex"
-$manage-issue-execute "ISS-20260401-001 --executor gemini"
-```
-
-**Flags**:
-- `<ISS-ID>` — Issue ID in `ISS-XXXXXXXX-NNN` format (required)
-- `--executor claude-code|codex|gemini` — Execution agent (default: claude-code)
-- `--dry-run` — Preview constructed prompt and steps without executing
-
-**State files**: `.workflow/issues/issues.jsonl` (read + write)
-
----
-
-## Overview
-
-Sequential 4-step pipeline with conditional dispatch: load issue → dry-run check → detect mode → execute + update. Server-UP path posts to the orchestration API; Server-DOWN path invokes `maestro delegate` directly. This is the third step in the issue resolution workflow: **analyze → plan → execute**.
-
-```
-Load Issue  →  [dry-run?]  →  Detect Mode  →  Dispatch  →  Update Status
-(+ solution     (display        server UP         POST       (apply_patch)
-  required)      + stop)        / DOWN          / cli
-```
-
----
-
-## Implementation
-
-### Step 1: Load Issue and Validate Solution
-
-```javascript
-functions.update_plan({
-  explanation: "Starting issue execution",
-  plan: [
-    { step: "Load issue and validate solution", status: "in_progress" },
-    { step: "Detect dispatch mode", status: "pending" },
-    { step: "Execute solution", status: "pending" },
-    { step: "Update issue status", status: "pending" }
-  ]
-})
-```
-
-Read `.workflow/issues/issues.jsonl`, find row where `id == <ISS-ID>`. Validate:
-- ISS-ID format `ISS-[0-9]{8}-[0-9]{3}`
-- Row exists in file
-- `issue.solution` is non-null (E002 if missing — run `manage-issue-plan` first)
-
-If `--dry-run`: display the full constructed prompt and each step from `issue.solution.steps`, then stop.
-
-### Step 2: Detect Dispatch Mode
-
-```javascript
-// Read port from config (falls back to MAESTRO_PORT env var, then 3000)
-const configPort = (() => {
-  try { return JSON.parse(Read('.workflow/config.json'))?.server?.port } catch { return null }
-})()
-const port = configPort || functions.exec_command({ cmd: "echo ${MAESTRO_PORT:-3000}", workdir: "." }).stdout.trim()
-
-const healthCheck = functions.exec_command({
-  cmd: `curl -s -o /dev/null -w '%{http_code}' http://localhost:${port}/health`,
-  workdir: "."
-})
-const serverUp = healthCheck.stdout.trim() === "200"
-```
-
-| Mode | Condition | Action |
-|------|-----------|--------|
-| Server UP | HTTP 200 from /health | POST to `/api/execution/dispatch` |
-| Server DOWN | Any other result | Direct `maestro delegate` execution |
-
-```javascript
-functions.update_plan({
-  explanation: `Dispatch mode: ${serverUp ? "server" : "cli"}`,
-  plan: [
-    { step: "Load issue and validate solution", status: "completed" },
-    { step: "Detect dispatch mode", status: "completed" },
-    { step: "Execute solution", status: "in_progress" },
-    { step: "Update issue status", status: "pending" }
-  ]
-})
-```
-
-### Step 3: Execute Solution
-
-Build the execution prompt from `issue.solution`:
-```
-PURPOSE: Implement solution for '${issue.title}'.
-TASK: ${solution.steps.map(s => `${s.order}. ${s.description} in ${s.file}`).join(' | ')}
-MODE: write
-CONTEXT: @src/**/* | Memory: Approach: ${solution.approach}
-  ${issue.analysis ? `Root cause: ${issue.analysis.root_cause}` : ''}
-EXPECTED: All steps implemented, all verification criteria met: ${solution.verification.join('; ')}
-CONSTRAINTS: Only modify files listed in steps | No scope creep
-```
-
-**Server UP**:
-```javascript
-// Write payload to temp file to avoid shell injection from prompt content
-const payload = JSON.stringify({ issue_id: issue.id, executor, prompt: execPrompt })
-Write(`/tmp/iss-exec-${issue.id}.json`, payload)
-functions.exec_command({
-  cmd: `curl -X POST http://localhost:${port}/api/execution/dispatch \
-    -H 'Content-Type: application/json' \
-    -d @/tmp/iss-exec-${issue.id}.json`,
-  workdir: "."
-})
-```
-
-**Server DOWN**:
-```javascript
-// Write prompt to temp file to avoid shell injection
-Write(`/tmp/iss-exec-${issue.id}.txt`, execPrompt)
-functions.exec_command({
-  cmd: `maestro delegate "$(cat /tmp/iss-exec-${issue.id}.txt)" --to ${executor === 'codex' ? 'codex' : 'claude'} --mode write`,
-  workdir: "."
-})
-```
-
-Set issue status to `in_progress` before dispatching via apply_patch.
-
-### Step 4: Update Issue Status and Report
-
-On success:
-```javascript
-// Read issues.jsonl, update the matching line in-place
-const historyEntry = { action: "executed", at: new Date().toISOString(), by: "manage-issue-execute", executor, summary: `Solution executed via ${serverUp ? "server" : "cli"}` }
-const raw = Read('.workflow/issues/issues.jsonl')
-const updated = raw.split('\n')
-  .filter(l => l.trim())
-  .map(l => {
-    const row = JSON.parse(l)
-    if (row.id !== issueId) return l
-    row.status = "resolved"
-    row.issue_history = [...(row.issue_history || []), historyEntry]
-    return JSON.stringify(row)
-  })
-  .join('\n') + '\n'
-Write('.workflow/issues/issues.jsonl', updated)
-```
-
-```javascript
-functions.update_plan({
-  explanation: "Execution complete",
-  plan: [
-    { step: "Load issue and validate solution", status: "completed" },
-    { step: "Detect dispatch mode", status: "completed" },
-    { step: "Execute solution", status: "completed" },
-    { step: "Update issue status", status: "completed" }
-  ]
-})
-```
-
-Display next-step routing:
-```
-=== EXECUTION COMPLETE ===
-Issue:     <ISS-ID>: <title>
-Executor:  <executor>
-Mode:      <server|cli>
-Status:    resolved
-
-Next steps:
-  Close:   $manage-issue "close <ISS-ID> --resolution fixed"
-  Verify:  $maestro-verify "<phase>"
-  Debug:   $quality-debug "<failure description>" (if issues found)
-```
-
----
-
-## Error Handling
-
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | No ISS-ID provided | Display usage hint |
-| E002 | error | No solution record on issue | Run `$manage-issue-plan "<ISS-ID>"` first |
-| E003 | error | ISS-ID not found in issues.jsonl | Suggest `$manage-issue "list"` |
-| E004 | error | Server dispatch or CLI execution failed | Log error, revert status to `open`, display failure details |
-
----
-
-## Core Rules
-
-1. **Solution required**: Never dispatch without a valid `issue.solution` record
-2. **Dry-run first**: `--dry-run` always stops after displaying prompt — no execution
-3. **Status before dispatch**: Set status to `in_progress` before dispatching, `resolved` on success, `open` on failure
-4. **Revert on failure**: If dispatch fails, revert issue status to `open` via apply_patch
-5. **Preserve history**: Append to `issue_history`, never overwrite existing entries
-6. **Next-step routing**: Always display all three options (close / verify / debug) at the end