maestro-flow 0.1.3 → 0.2.0

package/.claude/commands/maestro-verify.md

@@ -1,84 +1,87 @@
----
-name: maestro-verify
-description: Goal-Backward verification with 3-layer must-have checks, anti-pattern scan, Nyquist test coverage validation, and gap-fix plan generation
-argument-hint: "<phase> [--skip-tests] [--skip-antipattern]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Verify phase execution results through three complementary methods:
-1. **Goal-Backward verification** — 3-layer check (Truths → Artifacts → Wiring) that validates goals are actually achieved, not just tasks completed
-2. **Anti-pattern scan** — detect stubs, placeholders, TODO/FIXME, empty returns in modified files
-3. **Nyquist test coverage validation** — requirement-to-test mapping with gap classification (COVERED/PARTIAL/MISSING)
-
-Core principle: **Task completion ≠ Goal achievement**. A task "create chat component" can be marked complete when the component is a placeholder. This verifier checks that the goal "working chat interface" is actually achieved.
-
-Produces verification.json with must-have checks, gaps, anti-patterns, and fix plans. Optionally produces validation.json with test coverage analysis.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/verify.md
-</required_reading>
-
-<deferred_reading>
-- [verification.json](~/.maestro/templates/verification.json) — read when generating verification output
-- [validation.json](~/.maestro/templates/validation.json) — read when generating validation output
-- [index.json](~/.maestro/templates/index.json) — read when updating phase index
-</deferred_reading>
-
-<context>
-Phase: $ARGUMENTS (required -- phase number or slug)
-
-**Flags:**
-- `--skip-tests` -- Skip Nyquist test coverage validation (V2), only run Goal-Backward verification
-- `--skip-antipattern` -- Skip anti-pattern scan
-
-Context files resolved from `.workflow/phases/{NN}-{slug}/`:
-- index.json (phase metadata, success_criteria, plan, execution results)
-- plan.json (task overview)
-- .task/TASK-{NNN}.json (task definitions with convergence.criteria)
-- .summaries/TASK-{NNN}-summary.md (execution results)
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/verify.md' completely.
-
-**Next-step routing on completion:**
-- All checks pass, no gaps → Skill({ skill: "quality-review", args: "{phase}" })
-- Gaps found (must-have failures or anti-pattern blockers) → Skill({ skill: "maestro-plan", args: "{phase} --gaps" })
-- Low test coverage (Nyquist gaps) → Skill({ skill: "quality-test-gen", args: "{phase}" })
-
-**Gap-fix closure loop:**
-Gaps found → maestro-plan --gaps → maestro-execute → maestro-verify (re-run)
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Phase argument required | Check arguments format, re-run with correct input |
-| E002 | error | Phase directory not found | Check arguments format, re-run with correct input |
-| E003 | error | No execution results found (missing summaries) | Check arguments format, re-run with correct input |
-| W001 | warning | Test coverage below configured threshold | Review coverage gaps, run quality-test-gen |
-| W002 | warning | Anti-pattern blockers found in modified files | Fix anti-pattern blockers before proceeding |
-</error_codes>
-
-<success_criteria>
-- [ ] Must-haves established (from success_criteria, convergence.criteria, or derived)
-- [ ] All truths verified with status and evidence (Layer 1)
-- [ ] All artifacts checked at L1 (exists), L2 (substantive), L3 (wired) (Layer 2)
-- [ ] All key links verified with evidence (Layer 3)
-- [ ] Anti-patterns scanned and categorized (unless skipped)
-- [ ] Nyquist test coverage assessed with gap classification (unless skipped)
-- [ ] Fix plans generated for identified gaps
-- [ ] Human verification items identified
-- [ ] verification.json written with complete results
-- [ ] validation.json written if test audit ran
-- [ ] index.json updated with verification status and timestamps
-</success_criteria>
+---
+name: maestro-verify
+description: Goal-Backward verification with 3-layer must-have checks, anti-pattern scan, Nyquist test coverage validation, and gap-fix plan generation
+argument-hint: "<phase> [--skip-tests] [--skip-antipattern]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Verify phase execution results through three complementary methods:
+1. **Goal-Backward verification** — 3-layer check (Truths → Artifacts → Wiring) that validates goals are actually achieved, not just tasks completed
+2. **Anti-pattern scan** — detect stubs, placeholders, TODO/FIXME, empty returns in modified files
+3. **Nyquist test coverage validation** — requirement-to-test mapping with gap classification (COVERED/PARTIAL/MISSING)
+
+Core principle: **Task completion ≠ Goal achievement**. A task "create chat component" can be marked complete when the component is a placeholder. This verifier checks that the goal "working chat interface" is actually achieved.
+
+Produces verification.json with must-have checks, gaps, anti-patterns, and fix plans. Optionally produces validation.json with test coverage analysis.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/verify.md
+</required_reading>
+
+<deferred_reading>
+- [verification.json](~/.maestro/templates/verification.json) — read when generating verification output
+- [validation.json](~/.maestro/templates/validation.json) — read when generating validation output
+- [index.json](~/.maestro/templates/index.json) — read when updating phase index
+</deferred_reading>
+
+<context>
+Phase: $ARGUMENTS (required -- phase number or slug)
+
+**Flags:**
+- `--skip-tests` -- Skip Nyquist test coverage validation (V2), only run Goal-Backward verification
+- `--skip-antipattern` -- Skip anti-pattern scan
+
+Context files resolved from `.workflow/phases/{NN}-{slug}/`:
+- index.json (phase metadata, success_criteria, plan, execution results)
+- plan.json (task overview)
+- .task/TASK-{NNN}.json (task definitions with convergence.criteria)
+- .summaries/TASK-{NNN}-summary.md (execution results)
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/verify.md' completely.
+
+**Next-step routing on completion:**
+- All checks pass, no gaps → Skill({ skill: "quality-review", args: "{phase}" })
+- Gaps found (must-have failures or anti-pattern blockers) → Skill({ skill: "maestro-plan", args: "{phase} --gaps" })
+- Low test coverage (Nyquist gaps) → Skill({ skill: "quality-test-gen", args: "{phase}" })
+
+**Gap-fix closure loop:**
+Gaps found → maestro-plan --gaps → maestro-execute → maestro-verify (re-run)
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Phase argument required | Check arguments format, re-run with correct input |
+| E002 | error | Phase directory not found | Check arguments format, re-run with correct input |
+| E003 | error | No execution results found (missing summaries) | Check arguments format, re-run with correct input |
+| W001 | warning | Test coverage below configured threshold | Review coverage gaps, run quality-test-gen |
+| W002 | warning | Anti-pattern blockers found in modified files | Fix anti-pattern blockers before proceeding |
+| W003 | warning | Wiki health below threshold (score < 80) | Review broken links and orphan specs |
+| W004 | warning | Wiki health check unavailable | Skipped — wiki may not be initialized |
+</error_codes>
+
+<success_criteria>
+- [ ] Must-haves established (from success_criteria, convergence.criteria, or derived)
+- [ ] All truths verified with status and evidence (Layer 1)
+- [ ] All artifacts checked at L1 (exists), L2 (substantive), L3 (wired) (Layer 2)
+- [ ] Wiki health score reported (Layer 2.5) — warnings emitted if score < 80 or orphan specs found
+- [ ] All key links verified with evidence (Layer 3)
+- [ ] Anti-patterns scanned and categorized (unless skipped)
+- [ ] Nyquist test coverage assessed with gap classification (unless skipped)
+- [ ] Fix plans generated for identified gaps
+- [ ] Human verification items identified
+- [ ] verification.json written with complete results
+- [ ] validation.json written if test audit ran
+- [ ] index.json updated with verification status and timestamps
+</success_criteria>

package/.claude/commands/maestro.md

@@ -64,7 +64,9 @@ When `-y` is active, maestro propagates auto flags to downstream commands. Only
 | quality-test | `--auto-fix` | Auto-trigger gap-fix loop on failures |
 | quality-test-gen | *(none)* | No auto flag — generates tests normally |
 | quality-debug | *(none)* | No auto flag — runs diagnosis normally |
+| quality-retrospective | `--auto-yes` | Accept all routing recommendations (spec/note/issue) without prompting |
 | maestro-phase-transition | *(none)* | No auto flag — validates and transitions |
+| manage-learn | *(none)* | No auto flag — pure file operation, no prompts |
 
 Commands not listed (manage-*, spec-*, milestone-*) have no auto flags and execute as-is.
 

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

@@ -1,62 +1,62 @@
----
-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>
+---
+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-discover.md

@@ -1,77 +1,77 @@
----
-name: manage-issue-discover
-description: Automated issue discovery -- multi-perspective analysis or prompt-driven exploration
-argument-hint: "[multi-perspective | by-prompt \"what to look for\"] [-y|--yes] [--scope=src/**] [--depth=standard|deep]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Automated issue discovery via multi-perspective codebase analysis (8 perspectives) or prompt-driven exploration. Discovers issues, deduplicates findings, and records them in `.workflow/issues/issues.jsonl`.
-
-- **Default (no args)**: Interactive mode selection — choose multi-perspective or prompt-driven.
-- **`multi-perspective`**: 8-perspective parallel agent scan — security, performance, reliability, maintainability, scalability, UX, accessibility, compliance.
-- **`by-prompt "..."`**: Prompt-driven — Gemini plans exploration strategy, agents explore iteratively with cross-dimension analysis.
-
-For CRUD operations (create, list, update, close, link), use `/manage-issue`.
-
-After discovery, use `/manage-issue-analyze <ISS-ID>` to perform root cause analysis on individual findings.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/issue-discover.md
-</required_reading>
-
-<deferred_reading>
-- [issue.json template](~/.maestro/templates/issue.json) — read when creating issue records from findings (Step 6/11)
-- [search-tools](~/.maestro/templates/search-tools.md) — search tool priority, passed to agents via workflow
-</deferred_reading>
-
-<context>
-$ARGUMENTS -- optional. Parse first token to determine mode.
-
-**Modes:**
-- _(empty)_ -- interactive mode selection (AskUserQuestion)
-- `multi-perspective` -- 8-perspective parallel agent scan
-- `by-prompt "..."` -- prompt-driven iterative agent exploration (Gemini-planned)
-
-**Flags:**
-- `-y` / `--yes` -- auto mode, skip confirmations
-- `--scope=<pattern>` -- file scope (default: `**/*`)
-- `--depth=standard|deep` -- exploration depth (by-prompt only, default: `standard`)
-
-**State files:**
-- `.workflow/issues/issues.jsonl` -- issues appended here
-- `.workflow/issues/discoveries/{SESSION_ID}/` -- session artifacts
-</context>
-
-<execution>
-Determine mode from $ARGUMENTS:
-- No arguments or empty → interactive selection via AskUserQuestion
-- First token is `multi-perspective` → multi-perspective mode
-- First token is `by-prompt` → prompt-driven mode, remaining tokens are the user prompt
-
-Follow '~/.maestro/workflows/issue-discover.md' completely.
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E_NO_PROJECT | error | `.workflow/` does not exist | Prompt user to run `/maestro-init` first |
-| E_DISCOVERY_FAILED | error | CLI analysis returned no results | Retry with different tool or report partial findings |
-| E_EMPTY_PROMPT | warning | `by-prompt` used without prompt text | Interactive prompt with suggested options |
-</error_codes>
-
-<success_criteria>
-- [ ] Discovery mode correctly determined from arguments
-- [ ] All perspectives analyzed (multi-perspective) or dimensions explored (by-prompt)
-- [ ] Findings deduplicated before issue creation
-- [ ] Issues appended to issues.jsonl with correct schema
-- [ ] Discovery session fully traceable via session directory
-- [ ] Next step routing: Skill({ skill: "manage-issue-analyze", args: "<ISS-ID>" }) for root cause analysis, or Skill({ skill: "manage-issue", args: "list" }) to review all issues
-</success_criteria>
+---
+name: manage-issue-discover
+description: Automated issue discovery -- multi-perspective analysis or prompt-driven exploration
+argument-hint: "[multi-perspective | by-prompt \"what to look for\"] [-y|--yes] [--scope=src/**] [--depth=standard|deep]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Automated issue discovery via multi-perspective codebase analysis (8 perspectives) or prompt-driven exploration. Discovers issues, deduplicates findings, and records them in `.workflow/issues/issues.jsonl`.
+
+- **Default (no args)**: Interactive mode selection — choose multi-perspective or prompt-driven.
+- **`multi-perspective`**: 8-perspective parallel agent scan — security, performance, reliability, maintainability, scalability, UX, accessibility, compliance.
+- **`by-prompt "..."`**: Prompt-driven — Gemini plans exploration strategy, agents explore iteratively with cross-dimension analysis.
+
+For CRUD operations (create, list, update, close, link), use `/manage-issue`.
+
+After discovery, use `/manage-issue-analyze <ISS-ID>` to perform root cause analysis on individual findings.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/issue-discover.md
+</required_reading>
+
+<deferred_reading>
+- [issue.json template](~/.maestro/templates/issue.json) — read when creating issue records from findings (Step 6/11)
+- [search-tools](~/.maestro/templates/search-tools.md) — search tool priority, passed to agents via workflow
+</deferred_reading>
+
+<context>
+$ARGUMENTS -- optional. Parse first token to determine mode.
+
+**Modes:**
+- _(empty)_ -- interactive mode selection (AskUserQuestion)
+- `multi-perspective` -- 8-perspective parallel agent scan
+- `by-prompt "..."` -- prompt-driven iterative agent exploration (Gemini-planned)
+
+**Flags:**
+- `-y` / `--yes` -- auto mode, skip confirmations
+- `--scope=<pattern>` -- file scope (default: `**/*`)
+- `--depth=standard|deep` -- exploration depth (by-prompt only, default: `standard`)
+
+**State files:**
+- `.workflow/issues/issues.jsonl` -- issues appended here
+- `.workflow/issues/discoveries/{SESSION_ID}/` -- session artifacts
+</context>
+
+<execution>
+Determine mode from $ARGUMENTS:
+- No arguments or empty → interactive selection via AskUserQuestion
+- First token is `multi-perspective` → multi-perspective mode
+- First token is `by-prompt` → prompt-driven mode, remaining tokens are the user prompt
+
+Follow '~/.maestro/workflows/issue-discover.md' completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E_NO_PROJECT | error | `.workflow/` does not exist | Prompt user to run `/maestro-init` first |
+| E_DISCOVERY_FAILED | error | CLI analysis returned no results | Retry with different tool or report partial findings |
+| E_EMPTY_PROMPT | warning | `by-prompt` used without prompt text | Interactive prompt with suggested options |
+</error_codes>
+
+<success_criteria>
+- [ ] Discovery mode correctly determined from arguments
+- [ ] All perspectives analyzed (multi-perspective) or dimensions explored (by-prompt)
+- [ ] Findings deduplicated before issue creation
+- [ ] Issues appended to issues.jsonl with correct schema
+- [ ] Discovery session fully traceable via session directory
+- [ ] Next step routing: Skill({ skill: "manage-issue-analyze", args: "<ISS-ID>" }) for root cause analysis, or Skill({ skill: "manage-issue", args: "list" }) to review all issues
+</success_criteria>

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

@@ -1,73 +1,73 @@
----
-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 cli` 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 → Skill({ skill: "manage-issue", args: "close <ISS-ID> --resolution fixed" })
-- Execution failed → Skill({ skill: "quality-debug", args: "<failure description>" }) then retry
-- Want verification → Skill({ skill: "maestro-verify", args: "{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 → Skill({ skill: "manage-issue", args: "close <ISS-ID> --resolution fixed" })
-  - Execution failed → Skill({ skill: "quality-debug", args: "<failure description>" }) then retry
-  - Want verification → Skill({ skill: "maestro-verify", args: "{phase}" })
-</success_criteria>
+---
+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 cli` 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 → Skill({ skill: "manage-issue", args: "close <ISS-ID> --resolution fixed" })
+- Execution failed → Skill({ skill: "quality-debug", args: "<failure description>" }) then retry
+- Want verification → Skill({ skill: "maestro-verify", args: "{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 → Skill({ skill: "manage-issue", args: "close <ISS-ID> --resolution fixed" })
+  - Execution failed → Skill({ skill: "quality-debug", args: "<failure description>" }) then retry
+  - Want verification → Skill({ skill: "maestro-verify", args: "{phase}" })
+</success_criteria>