maestro-flow 0.1.0

package/.claude/commands/manage-memory-capture.md

@@ -0,0 +1,61 @@
+---
+name: manage-memory-capture
+description: Capture session memory (compact or tips) into .workflow/memory/ with JSON index
+argument-hint: "[compact|tip] [description] [--tag tag1,tag2]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<purpose>
+Capture session working memory into `.workflow/memory/` for cross-session recovery. Supports two modes: compact (full session compression for recovery) and tip (quick note-taking with tags). Maintains a `memory-index.json` for search and retrieval. Invoked when saving session state before context loss or recording insights during work.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/memory.md
+</required_reading>
+
+<context>
+Arguments: $ARGUMENTS
+
+**Modes:**
+- `compact` — Full session memory compression (files, decisions, plan state, pending work)
+- `tip` — Quick note with optional tags and context
+- No arguments — Auto-detect or ask user
+
+**Flags:**
+- `--tag tag1,tag2` — Categorization tags (tip mode)
+
+**Storage:**
+- `.workflow/memory/` — Memory entries directory
+- `.workflow/memory/memory-index.json` — Searchable index of all entries
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/memory.md' Part B (Memory Capture) completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | error | `.workflow/` not initialized — run Skill({ skill: "maestro-init" }) first | parse_input |
+| E002 | error | Empty note content in tip mode — provide text to save | parse_input |
+| W001 | warning | No active workflow session found — compact will capture conversation only | analyze_session |
+| W002 | warning | Plan detection found no explicit plan — using inferred plan | analyze_session |
+</error_codes>
+
+<success_criteria>
+- [ ] Mode correctly detected (compact or tip)
+- [ ] Entry markdown file written to `.workflow/memory/`
+- [ ] `memory-index.json` updated with new entry metadata
+- [ ] Compact: all session fields populated (objective, files, decisions, plan)
+- [ ] Compact: execution plan preserved VERBATIM (not summarized)
+- [ ] Compact: all file paths are ABSOLUTE
+- [ ] Tip: content, tags, and context captured
+- [ ] Confirmation banner displayed with entry ID
+- [ ] Next step: Skill({ skill: "manage-status" }) to resume workflow, or Skill({ skill: "manage-memory", args: "view <entry_id>" }) to verify captured memory
+</success_criteria>

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

@@ -0,0 +1,88 @@
+---
+name: manage-memory
+description: Manage memory entries — workflow memory (.workflow/memory/) and system memory (~/.claude/projects/*/memory/)
+argument-hint: "[list|search|view|edit|delete|prune] [query|id|file] [--store workflow|system|all] [--tag tag] [--type compact|tip]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<purpose>
+Unified memory management across two stores:
+1. **Workflow memory** (`.workflow/memory/`) — Session compacts and tips with JSON index, created by `manage-memory-capture`
+2. **System memory** (`~/.claude/projects/{project}/memory/`) — Claude Code auto-memory (MEMORY.md + topic files), persists across conversations
+
+Provides list/search/view/edit/delete/prune operations. Default store is `all` (show both).
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/memory.md
+</required_reading>
+
+<context>
+Arguments: $ARGUMENTS
+
+**Stores:**
+
+| Store | Path | Format | Index |
+|-------|------|--------|-------|
+| `workflow` | `.workflow/memory/` | `MEM-*.md`, `TIP-*.md` | `memory-index.json` |
+| `system` | `~/.claude/projects/{project}/memory/` | `MEMORY.md` + topic `.md` files | None (flat files) |
+
+**System memory path detection:**
+```bash
+# Derive from project root — replace path separators with '--', prefix drive letter
+# e.g., D:\maestro2 → ~/.claude/projects/D--maestro2/memory/
+```
+
+**Subcommands:**
+- `list` — List entries from both stores (default if no arguments)
+- `search <query>` — Full-text search across both stores
+- `view <id|file>` — Display a workflow entry by ID or system file by name
+- `edit <file>` — Edit a system memory file (MEMORY.md or topic file)
+- `delete <id|file>` — Remove an entry/file (with confirmation)
+- `prune` — Bulk cleanup by criteria
+
+**Flags:**
+- `--store <workflow|system|all>` — Target store (default: `all` for list/search, inferred for other ops)
+- `--tag <tag>` — Filter by tag (workflow store)
+- `--type <compact|tip>` — Filter by entry type (workflow store)
+- `--before <YYYY-MM-DD>` — Entries before date
+- `--after <YYYY-MM-DD>` — Entries after date
+- `--dry-run` — Preview destructive ops without executing
+- `--confirm` — Skip confirmation prompt
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/memory.md' Part A (Memory Management) completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | error | No memory stores found — run Skill({ skill: "manage-memory-capture" }) or create MEMORY.md | resolve_paths |
+| E002 | error | Entry ID or filename not found | execute_view, execute_delete |
+| E003 | error | Prune requires at least one filter (--tag, --type, --before, --after) | execute_prune |
+| E004 | error | Cannot delete MEMORY.md — use `edit` subcommand instead | execute_delete |
+| W001 | warning | Workflow index has orphaned files or dangling references | integrity_check |
+| W002 | warning | MEMORY.md references non-existent topic file | integrity_check |
+| W003 | warning | MEMORY.md exceeds 200 lines — content will be truncated at load | execute_edit |
+</error_codes>
+
+<success_criteria>
+- [ ] Both store paths correctly resolved
+- [ ] Subcommand correctly detected from arguments
+- [ ] Store auto-detected from argument format (MEM-*/TIP-* vs filename)
+- [ ] List: both stores displayed with appropriate formatting
+- [ ] Search: results from both stores, ranked by relevance
+- [ ] View: correct store selected, full content displayed
+- [ ] Edit: system memory files editable, MEMORY.md kept under 200 lines
+- [ ] Delete: MEMORY.md protected, confirmation required, references checked
+- [ ] Prune: workflow-only, filters validated, index updated
+- [ ] Integrity check catches orphans and broken links
+- [ ] Next step: Skill({ skill: "manage-memory-capture", args: "compact" }) to save new memory, or Skill({ skill: "manage-status" }) to continue workflow
+</success_criteria>

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

@@ -0,0 +1,69 @@
+---
+name: manage-status
+description: Display project dashboard with phase progress, active tasks, and next steps
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+---
+<purpose>
+Display a unified project dashboard showing phase progress, task counts, active work, and intelligent next-step suggestions.
+Reads all state files from `.workflow/` and renders a formatted overview with progress bars and status tables.
+Provides situational awareness before continuing work.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/status.md
+</required_reading>
+
+<context>
+$ARGUMENTS (no arguments required)
+
+**State files read:**
+- `.workflow/state.json` -- project-level state machine
+- `.workflow/roadmap.md` -- milestone and phase structure
+- `.workflow/phases/*/index.json` -- per-phase metadata and progress
+- `.workflow/phases/*/.task/TASK-*.json` -- individual task statuses
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/status.md' completely.
+
+**Next-step decision table:**
+| Current state | Suggested command | Reason |
+|---------------|-------------------|--------|
+| No phases planned | Skill({ skill: "maestro-brainstorm", args: "1" }) or Skill({ skill: "maestro-plan", args: "1" }) | Explore ideas or start planning first phase |
+| Phase pending, needs analysis | Skill({ skill: "maestro-analyze", args: "<N>" }) | Evaluate feasibility before planning |
+| Phase pending, needs decisions | Skill({ skill: "maestro-analyze", args: "<N> -q" }) | Quick decision extraction |
+| Phase planned, not executed | Skill({ skill: "maestro-execute", args: "<N>" }) | Execute the planned phase |
+| Phase executing, tasks blocked | Skill({ skill: "quality-debug", args: "<N>" }) | Unblock stuck tasks |
+| Phase executed, not verified | Skill({ skill: "maestro-verify", args: "<N>" }) | Verify execution results |
+| Phase verified with gaps | Skill({ skill: "maestro-plan", args: "<N> --gaps" }) | Plan gap fixes |
+| Phase verified, not reviewed | Skill({ skill: "quality-review", args: "<N>" }) | Code quality review before UAT |
+| Phase reviewed, verdict BLOCK | Skill({ skill: "maestro-plan", args: "<N> --gaps" }) | Fix critical review findings first |
+| Phase reviewed, verdict PASS/WARN | Skill({ skill: "quality-test", args: "<N>" }) | Proceed to UAT testing |
+| Phase verified, low test coverage | Skill({ skill: "quality-test-gen", args: "<N>" }) | Generate missing automated tests |
+| UAT passed | Skill({ skill: "maestro-phase-transition" }) | Move to next phase |
+| UAT has failures | Skill({ skill: "quality-debug", args: "--from-uat <N>" }) | Debug UAT gaps with parallel agents |
+| Need integration test cycle | Skill({ skill: "quality-integration-test", args: "<N>" }) | Self-iterating integration tests |
+| All phases in milestone complete | Skill({ skill: "maestro-milestone-audit" }) | Cross-phase integration check |
+| Milestone audit passed | Skill({ skill: "maestro-milestone-complete" }) | Archive milestone, advance |
+| Ad-hoc small task | Skill({ skill: "maestro-quick", args: "<task>" }) | Quick execute without full pipeline |
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | fatal | `.workflow/` not initialized -- run Skill({ skill: "maestro-init" }) first | parse_input |
+| E002 | fatal | `state.json` missing or corrupt -- project state unrecoverable | parse_input |
+</error_codes>
+
+<success_criteria>
+- [ ] Project state loaded from `state.json`
+- [ ] Roadmap parsed with milestone/phase structure
+- [ ] Per-phase progress calculated (task counts, completion %)
+- [ ] Dashboard rendered with progress bars and status table
+- [ ] Active work section shows current phase details
+- [ ] Next steps suggested based on current state analysis
+</success_criteria>

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

@@ -0,0 +1,83 @@
+---
+name: quality-debug
+description: Parallel hypothesis-driven debugging with UAT integration and structured root cause collection
+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. Supports three entry modes:
+
+1. **Standalone**: User describes an issue, gather symptoms interactively
+2. **From UAT**: `--from-uat` reads uat.md gaps as pre-filled symptoms (skip gathering)
+3. **Parallel**: `--parallel` spawns one debug agent per gap cluster concurrently
+
+When root causes are found, updates the originating uat.md with diagnosis artifacts (root_cause, fix_direction, affected_files) so the UAT -> debug -> fix pipeline stays connected.
+
+Key mechanisms from GSD diagnose-issues:
+- **Pre-filled symptoms from UAT**: Skip 5-question gathering when gaps already documented
+- **Parallel debug agents**: One agent per gap cluster for concurrent investigation
+- **Structured root cause collection**: Standardized output format across all agents
+- **UAT feedback loop**: Auto-update uat.md gaps with diagnosis results
+</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)
+
+**State files:**
+- `.workflow/phases/{NN}-{slug}/uat.md` -- UAT gaps (if --from-uat)
+- `.workflow/phases/{NN}-{slug}/.debug/` -- Phase-scoped debug sessions
+- `.workflow/scratch/debug-*/` -- Standalone debug sessions
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/debug.md' completely.
+
+**Next-step routing on completion:**
+- Root cause found, fix needed → Skill({ skill: "maestro-plan", args: "{phase} --gaps" })
+- Root cause found (from UAT), auto-fix → Skill({ skill: "quality-test", args: "{phase} --auto-fix" })
+- Inconclusive, need more info → Skill({ skill: "quality-debug", args: "{issue} -c" }) (resume session)
+- Standalone fix already applied → Skill({ skill: "maestro-verify", args: "{phase}" })
+
+Note: Debug output (.debug/) is auto-loaded by maestro-plan --gaps.
+</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
+- [ ] If --from-uat: uat.md gaps updated with diagnosis artifacts
+- [ ] Results unified into diagnosis summary
+- [ ] Next step routed (plan --gaps + execute if fix needed, verify if fix applied, resume if inconclusive)
+</success_criteria>

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

@@ -0,0 +1,87 @@
+---
+name: quality-integration-test
+description: Self-iterating integration test cycle with reflection-driven strategy and L0-L3 progressive layers
+argument-hint: "<phase> [--max-iter <N>] [--layer <L0|L1|L2|L3>]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Run a self-iterating integration test cycle that combines exploration, test design, test execution, reflection, and adaptive strategy adjustment. Unlike quality-test (UAT with user) or quality-test-gen (generate missing tests), this command runs automated integration tests in a closed loop that self-corrects until convergence.
+
+Key mechanisms from DMS3 integration-test-cycle:
+- **6-phase cycle**: Explore -> Design -> Develop -> Test -> Reflect -> Adjust
+- **Reflection-driven**: After each iteration, reflect on what worked/failed and adjust strategy
+- **Adaptive strategy engine**: Conservative (iter 1-2) -> Aggressive (>80% similar) -> Surgical (regression) -> Reflective (stuck 3+)
+- **L0-L3 progressive layers**: Static Analysis -> Unit -> Integration -> E2E
+- **Self-iterating**: Loop continues until pass rate threshold met or max iterations reached
+- **State persistence**: state.json + reflection-log.md survive context resets
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/integration-test.md
+</required_reading>
+
+<context>
+Phase: $ARGUMENTS (required -- phase number)
+
+**Flags:**
+- `--max-iter <N>` -- Maximum iterations (default: 5)
+- `--layer <L0|L1|L2|L3>` -- Start from specific layer (default: auto-detect)
+
+**L0-L3 Progressive Test Layers:**
+
+| Layer | Name | What | Tools |
+|-------|------|------|-------|
+| L0 | Static Analysis | Type checking, lint, dead code | `tsc --noEmit`, `eslint`, `ruff` |
+| L1 | Unit Tests | Function-level isolation tests | jest, vitest, pytest |
+| L2 | Integration Tests | Cross-module, API, DB tests | supertest, pytest + fixtures |
+| L3 | E2E Tests | Full user flow tests | playwright, cypress, selenium |
+
+**State files (in `.tests/integration/`):**
+- `state.json` -- iteration state, pass rates, strategy
+- `reflection-log.md` -- per-iteration reflections
+- `test-results-iter-{N}.json` -- results per iteration
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/integration-test.md' completely.
+
+**Next-step routing on completion:**
+- Converged (pass rate met) → Skill({ skill: "maestro-phase-transition", args: "{phase}" })
+- Max iterations, pass rate close → Skill({ skill: "quality-debug", args: "{phase}" }) (investigate remaining failures)
+- Regressions detected → Skill({ skill: "quality-debug", args: "{phase}" })
+- Stuck 3+ iterations → Skill({ skill: "maestro-analyze", args: "{phase} -q" }) (reassess approach)
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Phase number 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 test framework detected | Install test framework or verify project setup |
+| W001 | warning | Max iterations reached without convergence | Review reflection log, consider manual intervention |
+| W002 | warning | Regression detected, switching to Surgical strategy | Review reflection log, consider manual intervention |
+| W003 | warning | Stuck 3+ iterations, switching to Reflective strategy | Review reflection log, consider manual intervention |
+</error_codes>
+
+<success_criteria>
+- [ ] Integration test session initialized with state.json
+- [ ] Codebase explored for integration points
+- [ ] Test plan designed with L0-L3 layers
+- [ ] Tests written following existing patterns
+- [ ] Tests executed with results recorded per iteration
+- [ ] Reflection logged with pattern analysis
+- [ ] Strategy adapted based on results (conservative/aggressive/surgical/reflective)
+- [ ] Iterations continue until convergence or max_iter
+- [ ] summary.json written with final results
+- [ ] reflection-log.md contains full iteration history
+- [ ] index.json updated with integration test status
+- [ ] Next step routed (phase-transition if converged, debug if failures, analyze -q if stuck)
+</success_criteria>

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

@@ -0,0 +1,55 @@
+---
+name: quality-refactor
+description: Tech debt reduction with reflection-driven iteration
+argument-hint: "[scope: module path, feature area, or 'all']"
+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 → Skill({ skill: "quality-sync" }) (update codebase docs)
+- Test failures after refactor → Skill({ skill: "quality-debug", args: "{scope}" })
+- No test suite available → Skill({ skill: "quality-test-gen", args: "{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/.claude/commands/quality-review.md

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

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

@@ -0,0 +1,43 @@
+---
+name: quality-sync
+description: Sync codebase docs after code changes - traces git diff through component/feature/requirement impact chain
+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 → Skill({ skill: "manage-status" })
+- Major structural changes detected → Skill({ skill: "manage-codebase-rebuild" }) (full rebuild recommended)
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | .workflow/ not initialized | Suggest running Skill({ skill: "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-tech.json refreshed if dependency manifests changed
+</success_criteria>