maestro-flow 0.1.0

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

@@ -0,0 +1,84 @@
+---
+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>

package/.claude/commands/maestro.md

@@ -0,0 +1,116 @@
+---
+name: maestro
+description: Intelligent coordinator - analyze intent + read project state → select optimal command chain → execute via Skill()
+argument-hint: "\"intent text\" [-y] [-c] [--dry-run] [--chain <name>]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Orchestrate all maestro commands automatically based on user intent and current project state.
+Two routing modes:
+1. **Intent-based**: User describes a goal → classify task type → select/compose command chain → confirm → execute
+2. **State-based**: Read .workflow/state.json → determine next logical step → suggest/execute (triggered by `continue`/`next`)
+
+Produces session directory at `.workflow/.maestro/{session_id}/` with status.json tracking chain progress.
+Executes commands sequentially via Skill() with artifact propagation between steps.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/maestro.md
+</required_reading>
+
+<context>
+$ARGUMENTS — user intent text, or special keywords.
+
+**Special keywords:**
+- `continue` / `next` / `go` — State-based routing: read state.json, determine next step, execute
+- `status` — Shortcut to Skill({ skill: "manage-status" })
+
+**Flags:**
+- `-y` / `--yes` — Auto mode: skip clarification, skip confirmation, auto-skip on errors. Propagates to downstream commands that support it.
+- `-c` / `--continue` — Resume previous coordinator session from `.workflow/.maestro/*/status.json`
+- `--dry-run` — Show planned chain without executing
+- `--chain <name>` — Force a specific chain (bypass intent detection). Valid: full-lifecycle, spec-driven, brainstorm-driven, execute-verify, quality-loop, milestone-close, quick, review
+
+**State files read:**
+- `.workflow/state.json` — project state machine
+- `.workflow/roadmap.md` — milestone/phase structure
+- `.workflow/phases/*/index.json` — per-phase metadata and progress
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/maestro.md' completely.
+
+**Auto mode (`-y`) propagation:**
+
+When `-y` is active, maestro propagates auto flags to downstream commands. Only commands that explicitly support auto mode receive the flag — others execute normally (no forced flags).
+
+| Command | Auto Flag | Effect |
+|---------|-----------|--------|
+| maestro-analyze | `-y` | Skip interactive scoping, auto-deepen |
+| maestro-brainstorm | `-y` | Skip interactive questions, use defaults |
+| maestro-ui-design | `-y` | Skip interactive selection, pick top variant |
+| maestro-plan | `--auto` | Skip interactive clarification |
+| maestro-spec-generate | `-y` | Skip interactive questions, use defaults |
+| maestro-execute | *(none)* | No auto flag — executes all tasks normally |
+| maestro-verify | *(none)* | No auto flag — runs full verification |
+| quality-review | *(none)* | No auto flag — auto-detects level, runs fully |
+| 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 |
+| maestro-phase-transition | *(none)* | No auto flag — validates and transitions |
+
+Commands not listed (manage-*, spec-*, milestone-*) have no auto flags and execute as-is.
+
+In auto mode, maestro also:
+- Skips its own clarification (Step 4)
+- Skips chain confirmation (Step 5d)
+- Auto-skips on step errors (retry once, then skip and continue)
+
+**Report format on completion:**
+
+```
+=== MAESTRO SESSION COMPLETE ===
+Session: {session_id}
+Chain:   {chain_name} ({steps_completed}/{steps_total} steps)
+Phase:   {current_phase} (if applicable)
+Mode:    {auto | interactive}
+
+Steps:
+  [{status_icon}] {N}. {command_name} — {duration}
+
+Next: {suggested_next_action}
+```
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | No intent and project not initialized | Prompt for intent or suggest maestro-init |
+| E002 | error | Clarity too low after 2 clarification rounds | Show parsed intent, ask user to rephrase |
+| E003 | error | Chain step failed + user chose abort | Record partial progress, suggest resume with -c |
+| E004 | error | Resume session not found | Show available sessions |
+| W001 | warning | Intent ambiguous, multiple chains possible | Present options, let user choose |
+| W002 | warning | Chain step completed with warnings | Log and continue |
+| E005 | error | Invalid chain name provided with --chain | Show valid chain names and exit |
+| W003 | warning | State suggests different chain than intent | Show discrepancy, let user decide |
+</error_codes>
+
+<success_criteria>
+- [ ] Intent classified with task_type, complexity, clarity_score
+- [ ] Project state read and incorporated into routing
+- [ ] Command chain selected and confirmed (or auto-confirmed with -y)
+- [ ] Auto flags correctly propagated to supporting commands only
+- [ ] Session directory created at .workflow/.maestro/{session_id}/
+- [ ] status.json tracks per-step progress
+- [ ] All chain steps executed via Skill() with proper argument propagation
+- [ ] Phase numbers auto-detected and passed to downstream commands
+- [ ] Error handling: retry/skip/abort per step (auto-skip in -y mode)
+- [ ] Session summary displayed on completion
+</success_criteria>

package/.claude/commands/manage-codebase-rebuild.md

@@ -0,0 +1,50 @@
+---
+name: manage-codebase-rebuild
+description: Full rebuild of codebase documentation - scans project, builds doc-index.json, generates all tech-registry and feature-maps
+argument-hint: "[--force] [--skip-commit]"
+allowed-tools: [Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion]
+---
+
+<purpose>
+Perform a full rebuild of the .workflow/codebase/ documentation system from scratch. Scans the entire project source to identify components, features, requirements, and ADRs, then spawns parallel workflow-codebase-mapper agents to generate all documentation artifacts. This is a destructive operation that overwrites existing codebase docs.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/codebase-rebuild.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- optional flags.
+
+**Flags:**
+- `--force` -- Skip confirmation prompt and proceed directly
+- `--skip-commit` -- Do not auto-commit after rebuild
+
+**State files:**
+- `.workflow/` -- must be initialized (project.md, state.json exist)
+- `.workflow/codebase/` -- target directory (will be cleared and rebuilt)
+- `.workflow/codebase/doc-index.json` -- generated documentation index
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/codebase-rebuild.md' completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | .workflow/ not initialized | Run maestro-init first to create .workflow/ |
+| W001 | warning | A mapper agent failed (partial results) | Retry failed mapper or accept partial results |
+</error_codes>
+
+<success_criteria>
+- [ ] User confirmed rebuild (or --force used)
+- [ ] .workflow/codebase/ cleared and rebuilt from scratch
+- [ ] All 4 mapper agents spawned (failures logged as W001)
+- [ ] doc-index.json generated and valid
+- [ ] All documentation files regenerated
+- [ ] state.json updated with rebuild timestamp
+- [ ] project-tech.json refreshed with detected tech stack
+- [ ] project.md Tech Stack section updated if changes detected
+- [ ] Next step routing: Skill({ skill: "manage-status" }) or Skill({ skill: "manage-codebase-refresh" }) for incremental updates later
+</success_criteria>

package/.claude/commands/manage-codebase-refresh.md

@@ -0,0 +1,49 @@
+---
+name: manage-codebase-refresh
+description: Incremental refresh of codebase docs based on recent changes
+argument-hint: "[--since <date>] [--deep]"
+allowed-tools: [Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion]
+---
+
+<purpose>
+Incrementally refresh .workflow/codebase/ documentation based on changes since the last rebuild or refresh. Detects which files have changed (via git diff), identifies which codebase docs are affected, selectively re-runs mapper agents on those areas only, and updates timestamps. Much faster than a full rebuild for ongoing maintenance.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/codebase-refresh.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- optional flags.
+
+**Flags:**
+- `--since <date>` -- Override change detection window (ISO date or relative like "3d")
+- `--deep` -- Force deeper re-scan even for files with minor changes
+
+**State files:**
+- `.workflow/` -- must be initialized
+- `.workflow/codebase/` -- must contain existing docs (from prior rebuild)
+- `.workflow/codebase/doc-index.json` -- documentation index with timestamps
+- `.workflow/state.json` -- contains `codebase_last_rebuilt` timestamp
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/codebase-refresh.md' completely.
+</execution>
+
+<error_codes>
+| Code | Meaning                                                  |
+|------|----------------------------------------------------------|
+| E001 | .workflow/ not initialized                               |
+| E002 | No codebase/ docs exist, use codebase-rebuild instead    |
+| W001 | No changes detected since last refresh                   |
+</error_codes>
+
+<success_criteria>
+- [ ] Changed files detected via git diff since last refresh
+- [ ] Affected documentation entries identified from doc-index.json
+- [ ] Only affected docs refreshed (selective mapper re-run)
+- [ ] doc-index.json timestamps updated per affected entry
+- [ ] state.json updated with codebase_last_refreshed timestamp
+- [ ] Next step routing: Skill({ skill: "manage-status" }) or Skill({ skill: "spec-load" }) to use updated docs
+</success_criteria>

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

@@ -0,0 +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>

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

@@ -0,0 +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>

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

@@ -0,0 +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>

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

@@ -0,0 +1,62 @@
+---
+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/.claude/commands/manage-issue.md

@@ -0,0 +1,73 @@
+---
+name: manage-issue
+description: Issue CRUD operations -- create, query, update, close, and link issues to tasks
+argument-hint: "<create|list|status|update|close|link> [options]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<purpose>
+Issue lifecycle management for the project issue tracker. Supports create, list, status, update, close, and link (bidirectional issue-task cross-reference). All issues stored in `.workflow/issues/issues.jsonl` using the issue.json schema.
+
+For automated issue discovery, use `/manage-issue-discover`.
+
+**Closed-loop workflow**: After creating an issue, use `/manage-issue-analyze` for root cause analysis, `/manage-issue-plan` for solution planning, and `/manage-issue-execute` for execution.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/issue.md
+</required_reading>
+
+<deferred_reading>
+- [issue.json template](~/.maestro/templates/issue.json) — read when creating or updating issue records (create, update, close)
+</deferred_reading>
+
+<context>
+$ARGUMENTS -- subcommand + options. Parse first token as subcommand.
+
+**Valid subcommands:**
+- `create` -- create a new issue (--title, --severity, --source, --phase, --description)
+- `list` -- list issues with optional filters (--status, --phase, --severity, --source)
+- `status` -- show full detail for a specific issue (ISS-XXXXXXXX-NNN)
+- `update` -- update issue fields (ISS-XXXXXXXX-NNN --status, --priority, --severity, --tags, ...)
+- `close` -- close an issue with resolution (ISS-XXXXXXXX-NNN --resolution)
+- `link` -- link issue to a task (ISS-XXXXXXXX-NNN --task TASK-NNN)
+
+**State files:**
+- `.workflow/issues/issues.jsonl` -- active issues (one JSON per line)
+- `.workflow/issues/issue-history.jsonl` -- archived/closed issues
+</context>
+
+<execution>
+Parse subcommand from first token of $ARGUMENTS.
+Follow '~/.maestro/workflows/issue.md' completely.
+
+**Next-step routing on completion:**
+- create → Skill({ skill: "manage-issue-analyze", args: "<ISS-ID>" }) or Skill({ skill: "manage-issue-plan", args: "<ISS-ID>" })
+- list → Skill({ skill: "manage-issue-analyze", args: "<ISS-ID>" }) for any open issue
+- close → Skill({ skill: "manage-status" })
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E_NO_SUBCOMMAND | error | No subcommand provided in $ARGUMENTS | Display valid subcommands, prompt user to select |
+| E_INVALID_SUBCOMMAND | error | Unrecognized subcommand | Display valid subcommands with usage hints |
+| E_ISSUES_DIR_MISSING | warning | `.workflow/issues/` directory does not exist | Auto-create directory and empty issues.jsonl |
+</error_codes>
+
+<success_criteria>
+- [ ] Subcommand parsed and routed to correct handler
+- [ ] Issue data read/written to correct JSONL file
+- [ ] Output displayed in appropriate format (table for list, detail for status)
+- [ ] Cross-references maintained (link creates bidirectional references)
+- [ ] Next step routing by subcommand:
+  - create → Skill({ skill: "manage-issue-analyze", args: "<ISS-ID>" }) or Skill({ skill: "manage-issue-plan", args: "<ISS-ID>" })
+  - list → Skill({ skill: "manage-issue-analyze", args: "<ISS-ID>" }) for any open issue
+  - close → Skill({ skill: "manage-status" })
+</success_criteria>