maestro-flow 0.3.9 → 0.3.11

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

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

@@ -1,186 +0,0 @@
----
-name: manage-issue-plan
-description: Solution planning for a specific issue. Auto-detects analysis context, runs maestro delegate planning, and attaches a structured solution record with ordered steps and verification criteria to the issue in issues.jsonl.
-argument-hint: "<ISS-ID> [--tool gemini|qwen] [--from-analysis]"
-allowed-tools: Read, Write, Bash, Glob, Grep
----
-
-# Issue Plan
-
-## Usage
-
-```bash
-$manage-issue-plan "ISS-20260401-001"
-$manage-issue-plan "ISS-20260401-001 --from-analysis"
-$manage-issue-plan "ISS-20260401-001 --tool qwen"
-```
-
-**Flags**:
-- `<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 when `issue.analysis` exists.
-
-**State files**: `.workflow/issues/issues.jsonl` (read + write)
-
----
-
-## Overview
-
-Sequential 4-step pipeline: load issue → build planning prompt → run CLI planning → attach solution record. When an analysis record exists (from `manage-issue-analyze`), it is automatically included in the planning prompt to ground the solution in known root cause and affected files. This is the second step in the issue resolution workflow: **analyze → plan → execute**.
-
-```
-Load Issue  →  Build Prompt  →  CLI Planning  →  Attach Solution
-(+ analysis    (auto-detect    (gemini/qwen)    (apply_patch)
-  context)      analysis)
-```
-
----
-
-## Implementation
-
-### Step 1: Load Issue and Detect Analysis Context
-
-```javascript
-functions.update_plan({
-  explanation: "Starting issue planning",
-  plan: [
-    { step: "Load issue and detect analysis", status: "in_progress" },
-    { step: "Build planning prompt", status: "pending" },
-    { step: "Run CLI planning", status: "pending" },
-    { step: "Attach solution record", status: "pending" }
-  ]
-})
-```
-
-Read `.workflow/issues/issues.jsonl`, find the row where `id == <ISS-ID>`. Validate format and existence.
-
-Check analysis context:
-- `issue.analysis` non-null → `hasAnalysis = true` (auto-detect, no flag needed)
-- `--from-analysis` present AND `issue.analysis` is null → emit W001, proceed without context
-
-### Step 2: Build Planning Prompt
-
-```
-PURPOSE: Create a concrete, codebase-aware solution plan for '${issue.title}';
-  success = ordered steps with exact file paths, function names, and verification criteria.
-TASK: Define solution approach | Break into ordered steps | Identify files to change | Define verification
-MODE: analysis
-CONTEXT: @src/**/* | Memory: Issue: ${issue.description}
-  ${hasAnalysis ? `Root cause: ${analysis.root_cause}
-  Affected files: ${analysis.affected_files.join(', ')}
-  Fix direction: ${analysis.fix_direction}` : ''}
-EXPECTED: JSON: approach (string), steps [{order, description, file, action}],
-  verification (string[]), estimated_risk (low|medium|high)
-CONSTRAINTS: Concrete steps only | File:line references required | No speculative changes
-```
-
-### Step 3: Run CLI Planning
-
-> **Prompt safety**: `issue.title`, `issue.description`, and analysis fields may contain quotes or shell-special characters. Write the assembled prompt to a temp file before passing to exec_command.
-
-```javascript
-// Write prompt to temp file to avoid shell injection
-Write(`/tmp/iss-plan-${issueId}.txt`, prompt)
-functions.exec_command({
-  cmd: `maestro delegate "$(cat /tmp/iss-plan-${issueId}.txt)" --to ${tool} --mode analysis`,
-  workdir: "."
-})
-```
-
-Parse CLI output into `solution` object:
-```json
-{
-  "approach": "...",
-  "steps": [
-    { "order": 1, "description": "...", "file": "src/foo.ts", "action": "modify" },
-    { "order": 2, "description": "...", "file": "src/bar.ts", "action": "add" }
-  ],
-  "verification": ["Run unit tests for X", "Verify Y behavior"],
-  "estimated_risk": "medium",
-  "planned_at": "<ISO>",
-  "tool": "<tool>"
-}
-```
-
-```javascript
-functions.update_plan({
-  explanation: "Planning complete",
-  plan: [
-    { step: "Load issue and detect analysis", status: "completed" },
-    { step: "Build planning prompt", status: "completed" },
-    { step: "Run CLI planning", status: "completed" },
-    { step: "Attach solution record", status: "in_progress" }
-  ]
-})
-```
-
-### Step 4: Attach Solution Record and Report
-
-```javascript
-// Read issues.jsonl, update the matching line in-place
-const historyEntry = { action: "planned", at: new Date().toISOString(), by: "manage-issue-plan", summary: `Approach: ${solution.approach} — ${solution.steps.length} steps` }
-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.solution = solution
-    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: "Solution attached",
-  plan: [
-    { step: "Load issue and detect analysis", status: "completed" },
-    { step: "Build planning prompt", status: "completed" },
-    { step: "Run CLI planning", status: "completed" },
-    { step: "Attach solution record", status: "completed" }
-  ]
-})
-```
-
-Display:
-```
-=== SOLUTION PLAN ===
-Issue:    <ISS-ID>: <title>
-Approach: <approach>
-Risk:     <estimated_risk>
-Steps:    <N>
-
-Steps:
-  1. <description> → <file> (<action>)
-  2. <description> → <file> (<action>)
-
-Verification:
-  - <verification 1>
-
-Next: $manage-issue-execute "<ISS-ID>"
-```
-
----
-
-## Error Handling
-
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | No ISS-ID provided | Display usage hint |
-| E002 | error | ISS-ID not found in issues.jsonl | Suggest `$manage-issue "list"` |
-| E003 | error | CLI planning returned no parseable result | Retry with different `--tool` |
-| W001 | warning | `--from-analysis` but no analysis record exists | Proceed without context; suggest `$manage-issue-analyze` |
-
----
-
-## Core Rules
-
-1. **Load before plan**: Validate issue existence before any CLI call
-2. **Auto-detect analysis**: Check `issue.analysis` — never require explicit `--from-analysis` if data is present
-3. **Concrete steps only**: Each step must have a file reference — no "investigate further" placeholders
-4. **Preserve existing fields**: Patch only `solution` + `issue_history` — all other issue fields unchanged
-5. **Append-only history**: Append to `issue_history`, never overwrite existing entries
-6. **Next-step routing**: Always display `$manage-issue-execute "<ISS-ID>"` at the end