maestro-flow-one 0.1.3 → 0.2.1

package/maestro-flow/commands/milestone/release.md

@@ -0,0 +1,96 @@
+---
+name: maestro-milestone-release
+description: Bump version, generate changelog, tag milestone
+argument-hint: "[<version>] [--bump patch|minor|major] [--dry-run] [--no-tag] [--no-push]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+
+<purpose>
+Package a completed milestone into a releasable version. Bumps the project version (e.g. `package.json`, `pyproject.toml`, or language-specific manifest), generates or appends a changelog entry from phase/milestone summaries and git log, creates an annotated git tag, and optionally pushes to the remote. Runs after `/maestro-milestone-complete` has archived the milestone; serves as the final delivery step in the SDLC loop.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/milestone-release.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- optional explicit version string and flags.
+
+**Flags:**
+- `<version>` -- explicit version (e.g. `1.2.0`). If omitted, version is derived from `--bump` or prompted.
+- `--bump patch|minor|major` -- semver bump relative to the current version (default: `minor`)
+- `--dry-run` -- compute the next version, changelog diff, and tag name without writing files or creating tags
+- `--no-tag` -- skip git tag creation (version bump + changelog only)
+- `--no-push` -- skip `git push --follow-tags` after tagging
+
+**State files:**
+- `.workflow/state.json` -- current_milestone, previous release version
+- `.workflow/milestones/{milestone}/summary.md` -- milestone summary (from `maestro-milestone-complete`)
+- `.workflow/milestones/{milestone}/audit-report.md` -- audit verdict (must be PASS)
+- `CHANGELOG.md` -- release notes file (created if missing)
+- Version manifest -- `package.json` / `pyproject.toml` / `Cargo.toml` / etc. (auto-detected)
+
+**Preconditions:**
+- Current milestone must be completed (audit PASS + `/maestro-milestone-complete` run)
+- Working tree must be clean (no uncommitted changes) unless `--dry-run`
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/release.md' completely.
+
+**High-level flow:**
+1. Validate preconditions (milestone completed, clean tree, audit PASS)
+2. Resolve target version from `<version>` or `--bump` against current manifest
+3. Collect changes since last release tag: milestone summary + phase summaries + git log between tags
+4. Generate `CHANGELOG.md` entry (grouped by phase / change type)
+5. Write version to manifest file(s) + commit with message `chore(release): v{version}`
+6. Create annotated git tag `v{version}` with release notes body (unless `--no-tag`)
+7. Push commit + tag to remote (unless `--no-push`)
+
+**Report format on completion:**
+```
+=== RELEASE COMPLETE ===
+Version:   v{previous} → v{new}
+Milestone: {milestone_name}
+Tag:       v{new} {pushed|local-only}
+Changelog: {N} entries written to CHANGELOG.md
+Manifest:  {file_path} updated
+
+Next steps:
+  /maestro-plan {next_phase}   -- Start next milestone's first phase
+  /manage-status               -- View project dashboard
+```
+
+For `--dry-run`, print the computed version, changelog diff, and tag name without side effects.
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Current milestone not completed (no milestone-complete run) | Run `/maestro-milestone-complete` first |
+| E002 | error | Audit verdict not PASS | Re-run `/maestro-milestone-audit` and resolve findings |
+| E003 | error | Working tree not clean (uncommitted changes) | Commit or stash changes, then retry |
+| E004 | error | Version manifest not found / unsupported | Add supported manifest or pass `<version>` explicitly with `--no-tag` |
+| E005 | error | Target version not greater than current (would break semver monotonicity) | Choose a higher version or run with explicit `<version>` |
+| W001 | warning | No changes detected since last release tag | Confirm whether release is still desired |
+| W002 | warning | Remote push failed (network / auth) | Retry manually with `git push --follow-tags` |
+</error_codes>
+
+<success_criteria>
+- [ ] Preconditions validated (milestone complete, audit PASS, clean tree)
+- [ ] Target version computed and greater than previous
+- [ ] Version manifest(s) updated with new version
+- [ ] CHANGELOG.md contains new entry with milestone summary + grouped changes
+- [ ] Release commit created with conventional message
+- [ ] Annotated git tag created (unless `--no-tag`)
+- [ ] Commit + tag pushed to remote (unless `--no-push` or push failed → W002)
+- [ ] state.json updated with last_release_version + last_release_at timestamp
+</success_criteria>

package/maestro-flow/commands/quality/auto-test.md

@@ -0,0 +1,128 @@
+---
+name: quality-auto-test
+description: Auto-generate and run tests from specs or coverage gaps
+argument-hint: "<phase> [-y] [-c N] [--max-iter <N>] [--layer <L0-L3>] [--strategy <name>] [--dry-run] [--re-run]"
+allowed-tools:
+  - spawn_agents_on_csv
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<purpose>
+Run unified automated testing via CSV layer pipeline. Reads project state to auto-select the optimal scenario source — PRD specs (when spec package exists), coverage gaps (when Nyquist audit found gaps), or code exploration (default). All sources converge into a CSV pipeline: discover infrastructure → plan → build scenarios.csv → write tests per layer (spawn_agents_on_csv parallel) → execute → diagnose failures (spawn_agents_on_csv parallel) → iterate → report.
+
+Key mechanisms:
+- **Intelligent routing**: Reads `.tests/`, `.workflow/.spec/`, `verification.json` to auto-select source — no mode flag needed
+- **CSV parallel test writing**: Per-layer `spawn_agents_on_csv` — each agent writes one test file independently
+- **CSV parallel failure diagnosis**: Failed scenarios dispatched via `spawn_agents_on_csv` for classification + fix
+- **Unified iteration engine**: Nested inner loop (fix test_defects via diagnosis CSV, max 3/layer) + outer loop (adaptive strategy, max N iterations)
+- **Layers as waves**: L0→L1→L2→L3 sequential (fail-fast on critical), scenarios within layer parallel
+- **Discovery board**: `discoveries.ndjson` shared across all agents/iterations (append-only)
+- **Degenerate modes**: `--max-iter 1` = single-pass generation; default = full iterative cycle
+- **Session persistence**: CSV state + state.json survive context resets, resume from any point
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/auto-test.md
+</required_reading>
+
+<context>
+Phase or task: $ARGUMENTS (required — phase number)
+
+**Flags:**
+- `--max-iter N` — Maximum outer iterations (default: 5). Set to 1 for single-pass generation only.
+- `--layer L` — Start from or restrict to specific layer (L0|L1|L2|L3)
+- `--dry-run` — Generate test plan only, do not execute
+- `--re-run` — Re-run only previously failed/blocked scenarios
+
+**Intelligent routing** (auto-detected from project state):
+
+| Priority | Condition | Route | Equivalent to |
+|----------|-----------|-------|---------------|
+| 1 | Active session exists (state.json status=running) | Resume | — |
+| 2 | --re-run flag + previous failures | Re-run | — |
+| 3 | Spec package exists (REQ-*.md) | spec | quality-business-test |
+| 4 | Nyquist gaps exist (verification.json) | gap | quality-test-gen |
+| 5 | Default | code | quality-integration-test |
+
+Flags, artifact context resolution, and output formats defined in workflow auto-test.md.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/auto-test.md' completely.
+
+**Command-specific extensions (not in workflow):**
+
+**Review findings integration** (from related review artifacts):
+- Extract critical/high findings as additional test scenarios, marked `source: "review_finding"`
+- When review verdict is "BLOCK" and review-finding tests fail, suggest quality-debug
+
+**Debug root cause integration** (from related debug artifacts):
+- Generate regression test scenarios from confirmed root causes, marked `source: "debug_root_cause"`
+
+**Register artifact on completion:**
+```
+Append to state.json.artifacts[]:
+{
+  id: nextArtifactId(artifacts, "test"),  // TST-001
+  type: "test",
+  milestone: current_milestone,
+  phase: target_phase,
+  scope: "phase",
+  path: "scratch/{YYYYMMDD}-auto-test-P{N}-{slug}",
+  status: issues == 0 ? "completed" : "failed",
+  depends_on: exec_art.id,
+  harvested: false,
+  created_at: start_time,
+  completed_at: now()
+}
+```
+
+**Next-step routing on completion:**
+- Converged (>=95%) → `/maestro-verify {phase}`
+- All requirements verified (spec source) → `/maestro-milestone-audit`
+- Bugs discovered → `/quality-debug --from-auto-test {phase}`
+- Max iter, >80% → `/quality-test {phase}` for manual UAT
+- Max iter, <80% → `/quality-debug {phase}`
+- Coverage still low → `/quality-auto-test {phase} --layer {missing}`
+- Re-run all pass → `/maestro-verify {phase}`
+- Single pass, all pass → `/quality-test {phase}`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Phase argument required (no active sessions) | Prompt user for phase number |
+| E002 | error | Phase not found in artifact registry | Check state.json artifacts |
+| E003 | error | No test framework detected | Install test framework or configure test runner |
+| W001 | warning | One or more test scenarios failed | Auto-iterate or suggest fix options |
+| W002 | warning | Max iterations reached without convergence | Review reflection-log.md, suggest debug |
+| W003 | warning | Degraded spec mode (no full spec package) | Consider running maestro-roadmap --mode full |
+</error_codes>
+
+<success_criteria>
+- [ ] Phase resolved from artifact registry
+- [ ] Route auto-selected from project state (spec/gap/code)
+- [ ] Active sessions checked, resume offered if applicable
+- [ ] Scenarios extracted and normalized to unified format
+- [ ] Test infrastructure discovered (framework, patterns, conventions)
+- [ ] test-plan.json generated with layer distribution
+- [ ] User confirmed plan (or --dry-run stopped here)
+- [ ] Tests written following RED-GREEN methodology and existing patterns
+- [ ] Tests executed progressively (L0→L3) with fail-fast on critical
+- [ ] Iteration engine ran (inner: test_defect fix, outer: strategy adjust)
+- [ ] state.json, report.json, reflection-log.md written
+- [ ] Test confidence scored per iteration (Step 7.5) with 5-dimension factor model
+- [ ] Convergence check includes confidence >= 60% alongside pass_rate threshold
+- [ ] Pressure pass completed on highest-pass-rate layer before completion
+- [ ] report.json includes confidence section
+- [ ] index.json updated with auto_test section
+- [ ] If spec source: traceability matrix built, traceability.md written
+- [ ] If failures: issues auto-created in issues.jsonl
+- [ ] If gap source: validation.json gaps updated (MISSING→COVERED)
+- [ ] Next step routed based on convergence status
+</success_criteria>

package/maestro-flow/commands/quality/debug.md

@@ -0,0 +1,125 @@
+---
+name: quality-debug
+description: Debug with parallel hypotheses and root cause analysis
+argument-hint: "[issue description] [--from-uat <phase>] [--parallel]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Debug issues using scientific method with subagent isolation and persistent debug state. Three entry modes (standalone, from-UAT, parallel) and structured root cause collection with UAT feedback loop. Full algorithm defined in workflow debug.md.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/debug.md
+</required_reading>
+
+<context>
+User's issue: $ARGUMENTS
+
+**Flags:**
+- `--from-uat <phase>` -- Read gaps from phase's uat.md as pre-filled symptoms
+- `--parallel` -- Spawn parallel debug agents (one per gap cluster)
+
+**All context via state.json.artifacts[]:**
+
+```
+related = artifacts.filter(a =>
+  a.phase === target_phase && a.milestone === current_milestone
+).sort_by(completed_at asc)
+```
+
+Each artifact's type determines its outputs at `.workflow/{a.path}/`:
+- **execute** → .summaries/, .task/ (source of code changes)
+- **review** → review.json (findings guide hypothesis formation)
+- **debug** → understanding.md, evidence.ndjson (prior investigations, avoid re-investigation)
+- **test** → uat.md (--from-uat gap source), .tests/
+
+Extract conclusions from related artifacts that may affect this debug session — review findings guide investigation direction, prior debug avoids redundant work.
+
+### Pre-load context (before hypothesis formation)
+
+1. **Codebase docs**: If `.workflow/codebase/ARCHITECTURE.md` exists, load module boundaries to scope impact analysis and inform hypothesis formation.
+2. **Wiki prior knowledge**: Run `maestro wiki search "<symptom keywords>" --json 2>/dev/null`. If results found, check for prior investigations on similar issues to avoid re-investigation.
+3. Both are optional — proceed without if unavailable.
+
+**Output**: `DEBUG_DIR = .workflow/scratch/{YYYYMMDD}-debug-P{N}-{slug}/` (P{N} = phase number when phase-scoped; omit for standalone). Output directory rules defined in workflow debug.md Step 4.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/debug.md' completely.
+
+**Register artifact on completion (phase-scoped only):**
+```
+Append to state.json.artifacts[]:
+{
+  id: nextArtifactId(artifacts, "debug"),  // DBG-001
+  type: "debug",
+  milestone: current_milestone,
+  phase: target_phase,
+  scope: "phase",
+  path: "scratch/{YYYYMMDD}-debug-P{N}-{slug}",
+  status: all_diagnosed ? "completed" : "failed",
+  depends_on: triggering_review_id || exec_art.id,
+  harvested: false,
+  created_at: start_time,
+  completed_at: now()
+}
+```
+
+### Post-debug Knowledge Inquiry
+
+After root cause is confirmed, evaluate inquiry triggers:
+
+1. **Recurring pattern**: If root cause matches a recurring pattern (similar to prior debug sessions):
+   → Ask: "This root cause pattern has appeared before. Should it be documented in `debug-notes.md` to prevent recurrence? (`/spec-add debug`)"
+
+2. **Non-obvious fix**: If fix involved a non-obvious approach or workaround:
+   → Ask: "This fix used a non-obvious strategy. Should it be recorded as a learning? (`/spec-add learning`)"
+
+3. **Architectural gap**: If root cause traces to architectural boundary violation or missing constraint:
+   → Ask: "Root cause points to an architectural gap. Should `architecture-constraints.md` be updated? (`/spec-add arch`)"
+
+If user confirms, invoke `Skill({ skill: "spec-add", args: "<category> <content>" })`.
+
+**Next-step routing on completion:**
+- Root cause found, fix needed → `/maestro-plan {phase} --gaps`
+- Root cause found (from UAT), auto-fix → `/quality-test {phase} --auto-fix`
+- Inconclusive, need more info → `/quality-debug {issue} -c` (resume session)
+- Standalone fix already applied → `/maestro-verify {phase}`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Issue description required (no arguments, no active sessions) | Check arguments format, re-run with correct input |
+| E002 | error | UAT file not found for --from-uat phase | Verify UAT file exists for specified phase |
+| W001 | warning | Existing debug session found, offer resume | Review existing sessions, choose resume or new |
+| W002 | warning | Checkpoint reached, user input needed | Provide requested input to continue |
+| W003 | warning | Some gaps inconclusive, partial diagnosis | Review partial results, retry inconclusive gaps |
+</error_codes>
+
+<success_criteria>
+- [ ] Input parsed: standalone, --from-uat, or --parallel mode determined
+- [ ] Active sessions checked and resume offered if applicable
+- [ ] Symptoms gathered (interactive) or loaded from UAT (pre-filled)
+- [ ] Debug output directory created (phase .debug/ or scratch/)
+- [ ] Debug agent(s) spawned with full symptom context
+- [ ] If --parallel: one agent per gap cluster, all concurrent
+- [ ] evidence.ndjson written with structured NDJSON entries
+- [ ] understanding.md tracks evolving understanding per cluster
+- [ ] Root causes collected with fix_direction and affected_files
+- [ ] Multi-factor confidence scored per gap (Step 7.0) replacing simple high/medium/low
+- [ ] Readiness gate checked before ROOT CAUSE declaration
+- [ ] Pressure pass completed on confirmed hypothesis
+- [ ] Confidence table appended to understanding.md
+- [ ] If --from-uat: uat.md gaps updated with diagnosis artifacts
+- [ ] Results unified into diagnosis summary with confidence section
+- [ ] Next step routed (plan --gaps + execute if fix needed, verify if fix applied, resume if inconclusive)
+</success_criteria>

package/maestro-flow/commands/quality/refactor.md

@@ -0,0 +1,55 @@
+---
+name: quality-refactor
+description: Reduce tech debt with reflection-driven iteration
+argument-hint: "[<scope>]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Task
+  - AskUserQuestion
+---
+<purpose>
+Plan and execute targeted refactoring with safety guarantees through analysis, planning, and reflection-driven iteration. Identifies affected files and dependencies, creates a refactoring plan, confirms with the user before execution, then applies changes with test verification after every modification to ensure zero regressions. Each refactoring round records strategy, outcome, and adjustments in reflection-log.md.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/refactor.md
+</required_reading>
+
+<context>
+Scope: $ARGUMENTS (required)
+- Module path: "src/auth" - specific directory
+- Feature area: "authentication" - conceptual scope
+- "all" - full codebase scan
+
+If not provided, prompt user for scope.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/refactor.md' completely.
+
+**Next-step routing on completion:**
+- All tests pass → `/quality-sync` (update codebase docs)
+- Test failures after refactor → `/quality-debug {scope}`
+- No test suite available → `/quality-auto-test {phase}`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Refactoring scope/description required | Prompt user for module path, feature area, or "all" |
+| E002 | error | Test suite not available for affected area | Suggest creating tests first, or proceed with manual verification |
+| W001 | warning | Partial test coverage for affected area | Note uncovered areas, proceed with extra caution |
+</error_codes>
+
+<success_criteria>
+- [ ] Refactoring plan created and confirmed by user
+- [ ] Changes implemented according to plan
+- [ ] All tests pass after refactoring
+- [ ] No regressions introduced
+- [ ] reflection-log.md written with strategy and outcomes
+</success_criteria>

package/maestro-flow/commands/quality/retrospective.md

@@ -0,0 +1,78 @@
+---
+name: quality-retrospective
+description: Phase retrospective with insight routing to specs and lessons
+argument-hint: "[phase|N..M] [--lens technical|process|quality|decision] [--all] [--no-route] [--compare N] [-y]"
+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/learn.md (tip routing via manage-learn tip)
+- @~/.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 (scan/single/range/all), flags (--lens, --no-route, --compare, -y), and storage paths defined in workflow retrospective.md Argument Shape and Stages 1-7.
+</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-learn tip` for note routing** — do not duplicate the learning pipeline; invoke via `Skill({ skill: "manage-learn", args: "tip ..." })`.
+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 `{artifact_dir}/.history/` with a timestamp suffix first.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | error | `.workflow/` not initialized — run `/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-learn tip` did not return parseable INS 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 entries (if any) appended as `<spec-entry>` to matching `.workflow/specs/{category-file}.md`
+- [ ] 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-learn", 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: `/manage-status` to review state, or `/manage-issue list --source retrospective` to triage created issues, or `/manage-learn list` to browse the lessons library
+</success_criteria>

package/maestro-flow/commands/quality/review.md

@@ -0,0 +1,114 @@
+---
+name: quality-review
+description: Tiered code review with severity classification
+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?"). Three review levels (quick/standard/deep) scale with task depth, auto-detected from file count. Level definitions, dimension lists, deep-dive rules, and issue creation thresholds defined in workflow review.md.
+</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
+
+**All context via state.json.artifacts[]:**
+
+```
+related = artifacts.filter(a =>
+  a.phase === target_phase && a.milestone === current_milestone
+).sort_by(completed_at asc)
+```
+
+Each artifact's type determines its outputs at `.workflow/{a.path}/`:
+- **execute** → .summaries/, .task/, verification.json, plan.json (source of files to review)
+- **review** → review.json (prior verdict, findings — for delta comparison)
+- **debug** → understanding.md, evidence.ndjson (confirmed root causes)
+- **test** → uat.md, .tests/ (user-observable gaps)
+
+Extract conclusions from related artifacts that may affect this review. Pass as prior quality context to reviewer agents — avoid redundant work, focus on gaps and regressions.
+
+### Pre-load context (before dispatching reviewer agents)
+
+1. **Codebase docs**: If `.workflow/codebase/ARCHITECTURE.md` exists, load component boundaries and layer rules. Pass as `codebase_context` to reviewer agents (especially architecture dimension).
+2. **Wiki constraints**: Run `maestro wiki search "architecture constraint" --json 2>/dev/null`. If results found, pass as `wiki_context` to reviewer agents for evaluating code against documented decisions.
+3. Both are optional — proceed without if unavailable.
+
+**Output**: `REVIEW_DIR = .workflow/scratch/{YYYYMMDD}-review-P{N}-{slug}/` (P{N} = phase number, enables directory-level identification as state.json fallback)
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/review.md' completely.
+
+**Output writes to REVIEW_DIR** (not EXEC_DIR):
+- `REVIEW_DIR/review.json` — findings, severity distribution, verdict
+
+**Register artifact on completion:**
+```
+Append to state.json.artifacts[]:
+{
+  id: nextArtifactId(artifacts, "review"),  // REV-001
+  type: "review",
+  milestone: current_milestone,
+  phase: target_phase,
+  scope: "phase",
+  path: "scratch/{YYYYMMDD}-review-P{N}-{slug}",    // relative to .workflow/
+  status: "completed",
+  depends_on: exec_art.id,                 // or prior debug/review if re-review
+  harvested: false,
+  created_at: start_time,
+  completed_at: now()
+}
+```
+
+Report format and next-step routing by verdict defined in workflow review.md Report Format and Next Step Routing sections.
+
+**Next-step routing summary:**
+- PASS → `/quality-test {phase}`
+- WARN → `/quality-test {phase}` (proceed with caveats)
+- BLOCK → `/maestro-plan {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/maestro-flow/commands/quality/sync.md

@@ -0,0 +1,51 @@
+---
+name: quality-sync
+description: Sync codebase docs by tracing git diff impact
+argument-hint: "[--full] [--since <commit|HEAD~N>] [--dry-run]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Synchronize project state after manual code changes or to refresh codebase documentation. Detects changes via git diff, traces impact through doc-index.json (file -> component -> feature -> requirement), updates state.json and index.json, and refreshes affected `.workflow/codebase/` documentation. Use --full flag for a complete resync of all tracked files regardless of git diff.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/sync.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- optional flags:
+- `--full` -- Complete resync of all tracked files (ignores git diff, rebuilds all docs)
+- `--since <commit|HEAD~N>` -- Diff since specific commit (default: last sync timestamp)
+- `--dry-run` -- Show what would be updated without writing changes
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/sync.md' completely.
+
+**Next-step routing on completion:**
+- Docs refreshed → `/manage-status`
+- Major structural changes detected → `/manage-codebase-rebuild` (full rebuild recommended)
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | .workflow/ not initialized | Suggest running `/maestro-init` first|
+| W001 | warning | No changes detected since last sync | Report clean state, skip updates |
+</error_codes>
+
+<success_criteria>
+- [ ] state.json updated with current sync timestamp
+- [ ] Codebase docs refreshed for all affected components
+- [ ] doc-index.json reflects current file state
+- [ ] Changes tracked and logged
+- [ ] project.md Tech Stack section refreshed if dependency manifests changed
+</success_criteria>