maestro-flow 0.1.4 → 0.2.0

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>

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

@@ -1,125 +1,125 @@
----
-name: quality-review
-description: Tiered code review (quick/standard/deep) with parallel agents, severity classification, and auto-issue creation
-argument-hint: "<phase> [--level quick|standard|deep] [--dimensions security,architecture,...] [--skip-specs]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Run multi-dimensional code review on a completed phase's changed files. Answers the question "is this code good?" — complementing maestro-verify ("is the goal met?") and quality-test ("does it work for users?").
-
-Supports three review levels that scale with task depth:
-
-**Quick** — Single-pass inline scan, no agents. For small changes (≤3 files) or scratch tasks.
-  - Dimensions: correctness + security only
-  - No deep-dive, issues created for critical only
-
-**Standard** — Parallel agent review across all dimensions. Default for most phases.
-  - Dimensions: all 6 (correctness, security, performance, architecture, maintainability, best-practices)
-  - Auto deep-dive if critical findings > 0
-  - Issues created for critical + high
-
-**Deep** — Full agent review with forced multi-iteration deep-dive and cross-file impact analysis. For complex/critical phases.
-  - Dimensions: all 6
-  - Forced deep-dive (max 3 iterations) with impact radius analysis
-  - Issues created for critical + high + medium
-
-Level auto-detection when not specified:
-  - ≤3 changed files → quick
-  - 4-19 changed files → standard
-  - ≥20 changed files OR phase marked critical in index.json → deep
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/review.md
-</required_reading>
-
-<deferred_reading>
-- [index.json](~/.maestro/templates/index.json) — read when updating phase index after review
-</deferred_reading>
-
-<context>
-Phase: $ARGUMENTS (required — phase number or slug)
-
-**Flags:**
-- `--level quick|standard|deep` — Explicit review level (default: auto-detect from file count)
-- `--dimensions <list>` — Comma-separated subset of dimensions to review (overrides level defaults)
-- `--skip-specs` — Skip loading project specs as review context
-
-Context files resolved from `.workflow/phases/{NN}-{slug}/`:
-- index.json (phase metadata, execution results)
-- plan.json (task overview)
-- .task/TASK-{NNN}.json (task definitions with file lists)
-- .summaries/TASK-{NNN}-summary.md (execution results)
-- verification.json (if exists — incorporate verification gaps as review context)
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/review.md' completely.
-
-**Report format on completion:**
-
-```
-=== CODE REVIEW RESULTS ===
-Phase:     {phase_name}
-Level:     {quick | standard | deep}
-Files:     {files_reviewed} files across {dimensions_count} dimensions
-Duration:  {duration}
-
-Severity Distribution:
-  Critical: {critical_count}
-  High:     {high_count}
-  Medium:   {medium_count}
-  Low:      {low_count}
-
-Top Issues:
-  1. [{severity}] {finding_id}: {title} ({file}:{line})
-  2. ...
-
-Verdict: {PASS | WARN | BLOCK}
-Issues Created: {issue_count}
-
-Files:
-  {phase_dir}/review.json
-
-Next steps:
-  {verdict_based_routing}
-```
-
-**Next-step routing by verdict:**
-- PASS → Skill({ skill: "quality-test", args: "{phase}" })
-- PASS + low test coverage → Skill({ skill: "quality-test-gen", args: "{phase}" })
-- WARN → Skill({ skill: "quality-test", args: "{phase}" }) (proceed with caveats)
-- BLOCK → Skill({ skill: "maestro-plan", args: "{phase} --gaps" }) (fix critical findings first)
-</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 (no task summaries) | Verify execution completed with task summaries |
-| E004 | error | No changed files detected in phase | Verify execution completed with task summaries |
-| W001 | warning | Some dimension agents failed, partial results | Retry failed dimensions or accept partial results |
-| W002 | warning | Deep-dive iteration limit reached with unresolved criticals | Accept current findings or escalate manually |
-</error_codes>
-
-<success_criteria>
-- [ ] Phase resolved and changed files collected from task summaries
-- [ ] Review level determined (explicit flag or auto-detected)
-- [ ] Project specs loaded as review context (unless --skip-specs)
-- [ ] Dimension reviews executed (inline for quick, parallel agents for standard/deep)
-- [ ] All dimension results aggregated with severity classification
-- [ ] Deep-dive completed if triggered (standard: auto, deep: forced)
-- [ ] review.json written with complete findings, severity distribution, verdict
-- [ ] Issues auto-created based on level thresholds
-- [ ] index.json updated with review status
-- [ ] Next step routed by verdict (PASS→test, WARN→test with caveats, BLOCK→plan --gaps)
-</success_criteria>
+---
+name: quality-review
+description: Tiered code review (quick/standard/deep) with parallel agents, severity classification, and auto-issue creation
+argument-hint: "<phase> [--level quick|standard|deep] [--dimensions security,architecture,...] [--skip-specs]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Run multi-dimensional code review on a completed phase's changed files. Answers the question "is this code good?" — complementing maestro-verify ("is the goal met?") and quality-test ("does it work for users?").
+
+Supports three review levels that scale with task depth:
+
+**Quick** — Single-pass inline scan, no agents. For small changes (≤3 files) or scratch tasks.
+  - Dimensions: correctness + security only
+  - No deep-dive, issues created for critical only
+
+**Standard** — Parallel agent review across all dimensions. Default for most phases.
+  - Dimensions: all 6 (correctness, security, performance, architecture, maintainability, best-practices)
+  - Auto deep-dive if critical findings > 0
+  - Issues created for critical + high
+
+**Deep** — Full agent review with forced multi-iteration deep-dive and cross-file impact analysis. For complex/critical phases.
+  - Dimensions: all 6
+  - Forced deep-dive (max 3 iterations) with impact radius analysis
+  - Issues created for critical + high + medium
+
+Level auto-detection when not specified:
+  - ≤3 changed files → quick
+  - 4-19 changed files → standard
+  - ≥20 changed files OR phase marked critical in index.json → deep
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/review.md
+</required_reading>
+
+<deferred_reading>
+- [index.json](~/.maestro/templates/index.json) — read when updating phase index after review
+</deferred_reading>
+
+<context>
+Phase: $ARGUMENTS (required — phase number or slug)
+
+**Flags:**
+- `--level quick|standard|deep` — Explicit review level (default: auto-detect from file count)
+- `--dimensions <list>` — Comma-separated subset of dimensions to review (overrides level defaults)
+- `--skip-specs` — Skip loading project specs as review context
+
+Context files resolved from `.workflow/phases/{NN}-{slug}/`:
+- index.json (phase metadata, execution results)
+- plan.json (task overview)
+- .task/TASK-{NNN}.json (task definitions with file lists)
+- .summaries/TASK-{NNN}-summary.md (execution results)
+- verification.json (if exists — incorporate verification gaps as review context)
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/review.md' completely.
+
+**Report format on completion:**
+
+```
+=== CODE REVIEW RESULTS ===
+Phase:     {phase_name}
+Level:     {quick | standard | deep}
+Files:     {files_reviewed} files across {dimensions_count} dimensions
+Duration:  {duration}
+
+Severity Distribution:
+  Critical: {critical_count}
+  High:     {high_count}
+  Medium:   {medium_count}
+  Low:      {low_count}
+
+Top Issues:
+  1. [{severity}] {finding_id}: {title} ({file}:{line})
+  2. ...
+
+Verdict: {PASS | WARN | BLOCK}
+Issues Created: {issue_count}
+
+Files:
+  {phase_dir}/review.json
+
+Next steps:
+  {verdict_based_routing}
+```
+
+**Next-step routing by verdict:**
+- PASS → Skill({ skill: "quality-test", args: "{phase}" })
+- PASS + low test coverage → Skill({ skill: "quality-test-gen", args: "{phase}" })
+- WARN → Skill({ skill: "quality-test", args: "{phase}" }) (proceed with caveats)
+- BLOCK → Skill({ skill: "maestro-plan", args: "{phase} --gaps" }) (fix critical findings first)
+</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 (no task summaries) | Verify execution completed with task summaries |
+| E004 | error | No changed files detected in phase | Verify execution completed with task summaries |
+| W001 | warning | Some dimension agents failed, partial results | Retry failed dimensions or accept partial results |
+| W002 | warning | Deep-dive iteration limit reached with unresolved criticals | Accept current findings or escalate manually |
+</error_codes>
+
+<success_criteria>
+- [ ] Phase resolved and changed files collected from task summaries
+- [ ] Review level determined (explicit flag or auto-detected)
+- [ ] Project specs loaded as review context (unless --skip-specs)
+- [ ] Dimension reviews executed (inline for quick, parallel agents for standard/deep)
+- [ ] All dimension results aggregated with severity classification
+- [ ] Deep-dive completed if triggered (standard: auto, deep: forced)
+- [ ] review.json written with complete findings, severity distribution, verdict
+- [ ] Issues auto-created based on level thresholds
+- [ ] index.json updated with review status
+- [ ] Next step routed by verdict (PASS→test, WARN→test with caveats, BLOCK→plan --gaps)
+</success_criteria>

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

@@ -39,6 +39,7 @@ Phase or task: $ARGUMENTS (optional)
 Context files resolved from target directory:
 - verification.json (must_haves, gaps from maestro-verify)
 - validation.json (coverage, requirement mapping)
+- review.json (findings from quality-review, if exists)
 - index.json (success_criteria, execution results)
 - plan.json (task overview)
 - .summaries/TASK-*.md (execution summaries)
@@ -48,6 +49,11 @@ Context files resolved from target directory:
 <execution>
 Follow '~/.maestro/workflows/test.md' completely.
 
+**Review findings integration (when review.json exists):**
+- Extract critical/high findings from review.json.findings_by_dimension as additional test scenarios
+- These review-derived scenarios are prioritized and marked `source: "review_finding"`
+- When review.json verdict is "BLOCK" and review-finding tests fail, auto-enter gap-fix loop without user confirmation (Step 12 auto-fix condition)
+
 **Next-step routing on completion:**
 - All tests pass → Skill({ skill: "maestro-phase-transition", args: "{phase}" })
 - Issues found, --auto-fix ran and succeeded → Skill({ skill: "maestro-verify", args: "{phase}" })