maestro-flow 0.1.4 → 0.2.1

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>

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

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

@@ -0,0 +1,86 @@
+---
+name: manage-learn
+description: Capture, search, and review atomic learning insights into .workflow/learning/lessons.jsonl
+argument-hint: "[<text>|list|search|show <id>] [--category ...] [--tag t1,t2] [--phase N] [--confidence ...]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<purpose>
+Atomic insight capture for the workflow learning library. Lightweight gstack-style "eureka moment" log that complements `quality-retrospective`: where retrospective extracts insights from a completed phase in bulk, `manage-learn` captures one timeless insight at a time during active work. Insights are appended to `.workflow/learning/lessons.jsonl` with auto-detected phase linkage and a simple keyword-based category inference. Same store as retrospective output, so search and list see both manual captures and retrospective-distilled insights.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/learn.md
+</required_reading>
+
+<context>
+Arguments: $ARGUMENTS
+
+**Modes (auto-detected from first token):**
+- `"<insight text>"` (or any non-keyword text) → capture mode
+- `list` → list recent insights (default 20)
+- `search <query>` → text search across lessons.jsonl
+- `show <INS-id>` → full insight detail with phase context
+- empty → AskUserQuestion to prompt for insight text
+
+**Capture flags:**
+- `--category <name>` — pattern | antipattern | decision | tool | gotcha | technique. Default: inferred from text via keyword heuristics.
+- `--tag t1,t2` — comma-separated tags. Always implicitly adds `manual`.
+- `--phase <N>` — override auto-detected current phase. Use `--phase 0` to force "no phase".
+- `--confidence <level>` — high | medium | low. Default: medium.
+
+**List/search flags:**
+- `--tag t1,t2` — filter by tag
+- `--category <name>` — filter by category
+- `--phase <N>` — filter by phase
+- `--lens <name>` — filter by retrospective lens (technical | process | quality | decision)
+- `--limit <N>` — list mode row limit (default 20)
+
+**Storage:**
+- `.workflow/learning/lessons.jsonl` — append-only JSONL row per insight (shared with `quality-retrospective` output)
+- `.workflow/learning/learning-index.json` — searchable index (mirrors `memory-index.json` schema)
+
+**Shared store rationale:** Manual captures (`source: "manual"`, `lens: null`) and retrospective-distilled insights (`source: "retrospective"`, `lens: <name>`) live side by side so search and list see the entire knowledge corpus. The `source` and `lens` fields disambiguate.
+</context>
+
+<execution>
+Follow `~/.maestro/workflows/learn.md` Stages 1–5 in order. Key invariants:
+
+1. **No agent or CLI calls** — this is a pure file operation: parse → infer → append → confirm. Category inference is keyword-based, not LLM-based.
+2. **Auto-link phase** — read `.workflow/state.json` for `current_phase` and resolve the matching directory slug. `--phase 0` forces no link.
+3. **Match memory-index pattern** — `learning-index.json` schema mirrors `memory-index.json` from `workflows/memory.md` (entries[] with id, type, timestamp, file, summary, tags, plus learn-specific fields: lens, category, phase, phase_slug, confidence, routed_to, routed_id).
+4. **Stable INS ids** — `INS-{8 lowercase hex}` from `hash(insight_text + timestamp)`.
+5. **Append-only lessons.jsonl** — never rewrite existing rows; duplicate detection is the user's job at search time.
+6. **Bootstrap on demand** — create `.workflow/learning/`, `lessons.jsonl`, `learning-index.json` on first use; do not require them to exist upfront.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | error | `.workflow/` not initialized — run `Skill({ skill: "maestro-init" })` first | parse_input |
+| E002 | error | Unknown `--category` value (allowed: pattern, antipattern, decision, tool, gotcha, technique) | parse_input |
+| E003 | error | `show` mode requires an INS-id argument | show |
+| E004 | error | Insight id not found in lessons.jsonl | show |
+| W001 | warning | Auto-phase detection found a current_phase but no matching directory; phase set to null | capture |
+| W002 | warning | learning-index.json out of sync with lessons.jsonl (different row count); offer to rebuild | list/search |
+</error_codes>
+
+<success_criteria>
+- [ ] Mode correctly routed (capture / list / search / show)
+- [ ] Capture: `lessons.jsonl` row appended with valid JSON and all required fields
+- [ ] Capture: `learning-index.json` updated with matching entry
+- [ ] Capture: phase auto-link resolves correctly when `state.json` has `current_phase`
+- [ ] Capture: category inference produces a sensible default when `--category` absent
+- [ ] List: filters apply, output sorted newest-first, default limit 20
+- [ ] Search: results ranked by title (3) > tags (2) > summary (1) match
+- [ ] Show: full insight displayed with phase context and routed-artifact link if any
+- [ ] No file modifications outside `.workflow/learning/`
+- [ ] Confirmation banner displayed with INS-id and next-step hints
+- [ ] Next step: `Skill({ skill: "manage-learn", args: "list" })` to browse, or `Skill({ skill: "manage-learn", args: "search <query>" })` to find related insights
+</success_criteria>

package/.claude/commands/manage-status.md

@@ -66,4 +66,5 @@ Follow '~/.maestro/workflows/status.md' completely.
 - [ ] Dashboard rendered with progress bars and status table
 - [ ] Active work section shows current phase details
 - [ ] Next steps suggested based on current state analysis
+- [ ] Wiki health score displayed (or graceful unavailable message)
 </success_criteria>

package/.claude/commands/quality-retrospective.md

@@ -0,0 +1,103 @@
+---
+name: quality-retrospective
+description: Multi-lens 复盘 of completed phase(s); routes insights to spec/note/issue stores and the lessons library
+argument-hint: "[phase|N..M] [--lens technical|process|quality|decision] [--all] [--no-route] [--compare N] [--auto-yes]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Post-execution multi-perspective retrospective (复盘) for completed phases. Consumes existing execution artifacts (verification.json, review.json, issues.jsonl, plan.json, .summaries/, uat.md, state.json) and runs four parallel lenses — technical, process, quality, decision — to distill reusable insights. Routes each insight into the appropriate store: spec stub for reusable patterns, memory tip for process notes, issue for recurring gaps. Auto-scans for unreviewed completed phases and reports the backlog. Every insight is also persisted to `.workflow/learning/lessons.jsonl` for cross-phase queryability.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/retrospective.md
+</required_reading>
+
+<deferred_reading>
+- @~/.maestro/workflows/issue.md (issues.jsonl schema for auto-creation)
+- @~/.maestro/workflows/memory.md (Part B for note routing via manage-memory-capture)
+- @~/.maestro/workflows/verify.md (verification.json schema for quality lens parsing)
+- @~/.maestro/workflows/review.md (review.json schema for quality lens parsing)
+</deferred_reading>
+
+<context>
+Arguments: $ARGUMENTS
+
+**Modes (auto-detected from first non-flag token):**
+- No phase argument → `scan` mode: report unreviewed completed phases, prompt selection
+- `<N>` → `single` mode: retrospect phase N
+- `<N>..<M>` → `range` mode: retrospect phases N through M (inclusive)
+- `--all` → batch mode: re-run for every completed phase (archives existing retrospective.json)
+
+**Flags:**
+- `--lens <name>` — restrict to one lens; allowed: technical, process, quality, decision (repeatable)
+- `--no-route` — produce retrospective.{md,json} only; skip auto-creation of spec/note/issue
+- `--compare <M>` — emit a delta section vs phase M's prior retrospective
+- `--auto-yes` — accept all routing recommendations without prompting
+
+**Storage written:**
+- `.workflow/phases/{NN}-{slug}/retrospective.md` — human-readable record
+- `.workflow/phases/{NN}-{slug}/retrospective.json` — structured record
+- `.workflow/specs/SPEC-retro-*.md` — spec stubs (one per spec-routed insight)
+- `.workflow/issues/issues.jsonl` — appended issue rows (`source: "retrospective"`)
+- `.workflow/memory/TIP-*.md` — memory tips (via `manage-memory-capture` skill)
+- `.workflow/learning/lessons.jsonl` — append-only insight log
+- `.workflow/learning/learning-index.json` — searchable index
+
+**Storage read (never modified):**
+- `.workflow/phases/{NN}-{slug}/index.json`, `plan.json`, `verification.json`, `review.json`, `uat.md`
+- `.workflow/phases/{NN}-{slug}/.task/TASK-*.json`, `.summaries/TASK-*-summary.md`
+- `.workflow/issues/issues.jsonl`, `.workflow/issues/issue-history.jsonl`
+- `.workflow/state.json`
+</context>
+
+<execution>
+Follow `~/.maestro/workflows/retrospective.md` Stages 1–8 in order. Key invariants:
+
+1. **Read-only until Stage 6** — Stages 1–5 must not write anything except the in-memory retrospective record.
+2. **Parallel lens dispatch** — Stage 4 spawns one Agent per active lens in a single message (multiple Agent tool calls). All agents use `subagent_type: "general-purpose"` and `run_in_background: false`.
+3. **Match canonical issues schema** — Stage 6 issue routing must produce rows that pass `jq` parsing and match the schema in `workflows/issue.md` Step 4 exactly (status `"open"`, full `issue_history` entry, all required fields).
+4. **Reuse `manage-memory-capture` for note routing** — do not duplicate the memory pipeline; invoke via `Skill()`.
+5. **Backward-compat with phase-transition** — append a one-line summary per insight to `.workflow/specs/learnings.md` if and only if that file already exists. Never create it.
+6. **Stable insight IDs** — `INS-{8 hex}` from `hash(phase_num + lens + title)` so re-runs do not duplicate.
+7. **Archive before overwrite** — if existing `retrospective.{md,json}` are being replaced, move them to `{phase_dir}/.history/` with a timestamp suffix first.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | error | `.workflow/` not initialized — run `Skill({ skill: "maestro-init" })` first | parse_input |
+| E002 | error | Unknown `--lens` name (allowed: technical, process, quality, decision) | parse_input |
+| E003 | error | `--compare` requires a single phase argument | parse_input |
+| E004 | error | Phase has not executed yet — no `.task/` or `.summaries/` artifacts | load_artifacts |
+| E005 | error | Phase argument out of range / phase directory not found | scan_unreviewed |
+| W001 | warning | One or more lens agents failed — proceeding with partial coverage | multi_lens_analysis |
+| W002 | warning | Existing retrospective.json found and not `--all` — prompted user to overwrite | scan_unreviewed |
+| W003 | warning | `manage-memory-capture` did not return parseable TIP id; fell back to direct write | route_outputs |
+| W004 | warning | `--compare` target phase has no retrospective.json; delta omitted | load_artifacts |
+</error_codes>
+
+<success_criteria>
+- [ ] Mode correctly resolved (scan / single / range / all)
+- [ ] At least one phase selected and validated (status == "completed", artifacts exist)
+- [ ] All requested lens agents returned valid JSON, or W001 logged for partial coverage
+- [ ] `retrospective.json` written with metrics, findings_by_lens, distilled_insights, routing_recommendations
+- [ ] `retrospective.md` written and human-readable (tweetable, metrics table, per-lens findings, insights, routing table)
+- [ ] Each insight has a stable `INS-{8hex}` id
+- [ ] If routing enabled (default): every recommendation either created an artifact or was explicitly skipped by user
+- [ ] Spec stubs (if any) written to `.workflow/specs/SPEC-retro-*.md` with proper frontmatter
+- [ ] Issue rows (if any) match canonical issues.jsonl schema (status "open", full issue_history, all required fields)
+- [ ] Note tips (if any) created via `Skill({ skill: "manage-memory-capture", args: "tip ..." })`
+- [ ] `lessons.jsonl` appended with one row per insight regardless of routing target
+- [ ] `learning-index.json` updated and parseable
+- [ ] No existing phase artifacts modified (verification.json, review.json, plan.json untouched)
+- [ ] Confirmation banner displays routing counts and next-step suggestions
+- [ ] Next step: `Skill({ skill: "manage-status" })` to review state, or `Skill({ skill: "manage-issue", args: "list --source retrospective" })` to triage created issues, or `Skill({ skill: "manage-learn", args: "list" })` to browse the lessons library
+</success_criteria>