maestro-flow 0.3.19 → 0.3.20

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

@@ -1,77 +1,77 @@
----
-name: manage-knowhow
-description: Manage memory entries — workflow memory (.workflow/knowhow/) 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 knowhow** (`.workflow/knowhow/`) — Session compacts and tips with JSON index, created by `manage-knowhow-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/knowhow.md
-</required_reading>
-
-<context>
-Arguments: $ARGUMENTS
-
-Dual store architecture (paths, formats, index) defined in workflow knowhow.md.
-
-**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/knowhow.md' Part A (KnowHow Management) completely.
-</execution>
-
-<error_codes>
-| Code | Severity | Description | Stage |
-|------|----------|-------------|-------|
-| E001 | error | No memory stores found — run `/manage-knowhow-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 (KNW-*/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: `/manage-knowhow-capture compact` to save new knowhow, or `/manage-status` to continue workflow
-</success_criteria>
+---
+name: manage-knowhow
+description: Manage memory entries — workflow memory (.workflow/knowhow/) 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 knowhow** (`.workflow/knowhow/`) — Session compacts and tips with JSON index, created by `manage-knowhow-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/knowhow.md
+</required_reading>
+
+<context>
+Arguments: $ARGUMENTS
+
+Dual store architecture (paths, formats, index) defined in workflow knowhow.md.
+
+**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/knowhow.md' Part A (KnowHow Management) completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | error | No memory stores found — run `/manage-knowhow-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 (KNW-*/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: `/manage-knowhow-capture compact` to save new knowhow, or `/manage-status` to continue workflow
+</success_criteria>

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

@@ -1,67 +1,67 @@
----
-name: manage-learn
-description: Capture, search, and review atomic learning insights and tips into .workflow/learning/lessons.jsonl
-argument-hint: "[<text>|tip <text>|list|search|show <id>] [--category ...] [--tag t1,t2] [--phase N] [--confidence ...]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - AskUserQuestion
----
-<purpose>
-Unified atomic knowledge capture for the workflow learning library. Captures two types of knowledge:
-- **Insights**: Timeless "eureka moment" entries (patterns, gotchas, techniques) — the default mode
-- **Tips**: Quick contextual notes for cross-session recovery (formerly in `manage-knowhow-capture tip`)
-
-Both types are stored in `.workflow/learning/lessons.jsonl` with auto-detected phase linkage and keyword-based category inference. Tips are distinguished by `source: "tip"` and implicitly tagged `tip`. Same store as retrospective output, so search and list see the entire knowledge corpus.
-</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) → insight capture mode
-- `tip <text>` → tip capture mode (quick contextual note, auto-tagged `tip`)
-- `list` → list recent entries (default 20)
-- `search <query>` → text search across lessons.jsonl
-- `show <INS-id>` → full detail with phase context
-- empty → AskUserQuestion to prompt for text
-
-Flags, storage paths, and shared store rationale defined in workflow learn.md.
-</context>
-
-<execution>
-Follow `~/.maestro/workflows/learn.md` Stages 1–5 in order.
-</execution>
-
-<error_codes>
-| Code | Severity | Description | Stage |
-|------|----------|-------------|-------|
-| E001 | error | `.workflow/` not initialized — run `/maestro-init` first | parse_input |
-| E002 | error | Unknown `--category` value (allowed: pattern, antipattern, decision, tool, gotcha, technique, tip) | 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 artifact in registry; 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 via artifact registry 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: `/manage-learn list` to browse, or `/manage-learn search <query>` to find related insights
-</success_criteria>
+---
+name: manage-learn
+description: Capture, search, and review atomic learning insights and tips into .workflow/learning/lessons.jsonl
+argument-hint: "[<text>|tip <text>|list|search|show <id>] [--category ...] [--tag t1,t2] [--phase N] [--confidence ...]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<purpose>
+Unified atomic knowledge capture for the workflow learning library. Captures two types of knowledge:
+- **Insights**: Timeless "eureka moment" entries (patterns, gotchas, techniques) — the default mode
+- **Tips**: Quick contextual notes for cross-session recovery (formerly in `manage-knowhow-capture tip`)
+
+Both types are stored in `.workflow/learning/lessons.jsonl` with auto-detected phase linkage and keyword-based category inference. Tips are distinguished by `source: "tip"` and implicitly tagged `tip`. Same store as retrospective output, so search and list see the entire knowledge corpus.
+</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) → insight capture mode
+- `tip <text>` → tip capture mode (quick contextual note, auto-tagged `tip`)
+- `list` → list recent entries (default 20)
+- `search <query>` → text search across lessons.jsonl
+- `show <INS-id>` → full detail with phase context
+- empty → AskUserQuestion to prompt for text
+
+Flags, storage paths, and shared store rationale defined in workflow learn.md.
+</context>
+
+<execution>
+Follow `~/.maestro/workflows/learn.md` Stages 1–5 in order.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | error | `.workflow/` not initialized — run `/maestro-init` first | parse_input |
+| E002 | error | Unknown `--category` value (allowed: pattern, antipattern, decision, tool, gotcha, technique, tip) | 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 artifact in registry; 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 via artifact registry 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: `/manage-learn list` to browse, or `/manage-learn search <query>` to find related insights
+</success_criteria>

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

@@ -1,62 +1,62 @@
----
-name: manage-wiki
-description: Wiki knowledge graph management — health dashboard, orphan cleanup, entry search, and graph statistics
-argument-hint: "[health|search|cleanup|stats] [options]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - AskUserQuestion
----
-<purpose>
-Unified wiki graph management command. Provides interactive access to wiki health monitoring, entry search, orphan cleanup, and graph statistics — the day-to-day operations that keep the knowledge graph healthy.
-
-Complements `/wiki-connect` (link discovery) and `/wiki-digest` (synthesis) with operational tooling.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/wiki-manage.md
-</required_reading>
-
-<context>
-$ARGUMENTS — subcommand and optional flags.
-
-**Subcommands:**
-| Subcommand | Description |
-|-----------|-------------|
-| `health` | Health dashboard — score, broken links, orphans, hubs (default) |
-| `search <query>` | Interactive BM25 search with follow-up actions |
-| `cleanup` | Find and resolve orphans, broken links, stale entries |
-| `stats` | Graph statistics — type distribution, tag frequency, growth trends |
-| No args | Same as `health` |
-
-**Flags:**
-- `--type <type>` — Filter by wiki type: spec, knowhow, note, lesson, issue
-- `--fix` — Auto-fix issues found during cleanup (remove broken links, suggest connections)
-- `--json` — Output in JSON format
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/wiki-manage.md' completely.
-</execution>
-
-<error_codes>
-| Code | Severity | Description | Stage |
-|------|----------|-------------|-------|
-| E001 | fatal | `.workflow/` not initialized — run `/maestro-init` first | validate |
-| E002 | fatal | No wiki entries found — create content first | load |
-| E003 | error | Invalid subcommand | parse_input |
-| W001 | warning | Health score below 50 — graph needs attention | health |
-| W002 | warning | Orphan cleanup had partial failures | cleanup |
-</error_codes>
-
-<success_criteria>
-- [ ] Subcommand parsed (health/search/cleanup/stats)
-- [ ] Wiki data loaded via `maestro wiki` CLI
-- [ ] Results displayed in formatted output
-- [ ] If cleanup --fix: issues resolved and delta reported
-- [ ] Next-step suggestions provided
-</success_criteria>
+---
+name: manage-wiki
+description: Wiki knowledge graph management — health dashboard, orphan cleanup, entry search, and graph statistics
+argument-hint: "[health|search|cleanup|stats] [options]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<purpose>
+Unified wiki graph management command. Provides interactive access to wiki health monitoring, entry search, orphan cleanup, and graph statistics — the day-to-day operations that keep the knowledge graph healthy.
+
+Complements `/wiki-connect` (link discovery) and `/wiki-digest` (synthesis) with operational tooling.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/wiki-manage.md
+</required_reading>
+
+<context>
+$ARGUMENTS — subcommand and optional flags.
+
+**Subcommands:**
+| Subcommand | Description |
+|-----------|-------------|
+| `health` | Health dashboard — score, broken links, orphans, hubs (default) |
+| `search <query>` | Interactive BM25 search with follow-up actions |
+| `cleanup` | Find and resolve orphans, broken links, stale entries |
+| `stats` | Graph statistics — type distribution, tag frequency, growth trends |
+| No args | Same as `health` |
+
+**Flags:**
+- `--type <type>` — Filter by wiki type: spec, knowhow, note, lesson, issue
+- `--fix` — Auto-fix issues found during cleanup (remove broken links, suggest connections)
+- `--json` — Output in JSON format
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/wiki-manage.md' completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | fatal | `.workflow/` not initialized — run `/maestro-init` first | validate |
+| E002 | fatal | No wiki entries found — create content first | load |
+| E003 | error | Invalid subcommand | parse_input |
+| W001 | warning | Health score below 50 — graph needs attention | health |
+| W002 | warning | Orphan cleanup had partial failures | cleanup |
+</error_codes>
+
+<success_criteria>
+- [ ] Subcommand parsed (health/search/cleanup/stats)
+- [ ] Wiki data loaded via `maestro wiki` CLI
+- [ ] Results displayed in formatted output
+- [ ] If cleanup --fix: issues resolved and delta reported
+- [ ] Next-step suggestions provided
+</success_criteria>

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

@@ -1,110 +1,110 @@
----
-name: quality-business-test
-description: PRD-forward business testing with requirement traceability, fixture generation, and multi-layer execution
-argument-hint: "<phase> [--spec SPEC-xxx] [--layer L1|L2|L3] [--gen-code] [--dry-run] [--re-run] [--auto]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Validate built features against PRD acceptance criteria through automated multi-layer business testing. Unlike quality-test (interactive UAT from code gaps) and quality-test-gen (generate tests from coverage gaps), this command starts from REQ-*.md acceptance criteria and works forward to verify business rules are satisfied.
-
-Key mechanisms:
-- **PRD-forward extraction**: Parse REQ-*.md acceptance criteria with RFC 2119 priority mapping
-- **Three-tier fixture generation**: Schema-derived (valid/invalid/boundary), criteria-derived (expected outcomes), scenario-derived (multi-entity packs)
-- **Progressive L1-L3 layers**: Interface Contract -> Business Rule -> Business Scenario (fail-fast on critical)
-- **Generator-Critic loop**: Max 3 iterations per layer to distinguish test defects from code defects
-- **Requirement traceability**: Every failure traces back to REQ-NNN:AC-N
-- **Degraded mode**: Falls back to success_criteria + plan.json when no spec package exists
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/business-test.md
-</required_reading>
-
-<context>
-Phase: $ARGUMENTS (required -- phase number)
-
-**Flags:**
-- `--spec SPEC-xxx` -- Explicit spec reference (default: auto-detect from index.json.spec_ref)
-- `--layer L1|L2|L3` -- Run only specific layer (default: progressive L1->L2->L3)
-- `--gen-code` -- Generate framework-specific test classes (JUnit/RestAssured, supertest/vitest, pytest/httpx)
-- `--dry-run` -- Extract scenarios and fixtures only, don't execute
-- `--re-run` -- Re-run only previously failed/blocked scenarios
-- `--auto` -- Skip interactive confirmations
-
-**Layer definitions:**
-
-| Layer | Name | Tests | Source |
-|-------|------|-------|--------|
-| L1 | Interface Contract | Single endpoint request/response, input validation, schema compliance | Architecture API endpoints + REQ AC |
-| L2 | Business Rule | Multi-step logic, state transitions, business constraints, edge cases | REQ acceptance criteria + NFR |
-| L3 | Business Scenario | Full user flows, multi-service chains, error propagation | Epic user stories |
-
-**Priority mapping (RFC 2119):**
-
-| Keyword | Priority | Failure = |
-|---------|----------|-----------|
-| MUST / SHALL | critical | blocker |
-| SHOULD / RECOMMENDED | high | major |
-| MAY / OPTIONAL | medium | minor |
-
-Context files:
-- `.workflow/.spec/SPEC-xxx/requirements/REQ-*.md` -- Functional requirements + acceptance criteria
-- `.workflow/.spec/SPEC-xxx/requirements/NFR-*.md` -- Non-functional requirements
-- `.workflow/.spec/SPEC-xxx/architecture/_index.md` -- API endpoints, data model, state machines
-- `.workflow/.spec/SPEC-xxx/epics/EPIC-*.md` -- User stories for E2E scenarios
-- Phase artifacts (resolve via `state.json.artifacts[]` → `.workflow/scratch/` paths):
-  - plan.json -- Task overview (degraded mode)
-  - verification.json -- Cross-reference for must_haves
-  - .tests/business/ -- Previous business test artifacts
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/business-test.md' completely.
-
-**Next-step routing on completion:**
-- All requirements verified → `/maestro-milestone-audit`
-- Failures found → `/quality-debug --from-business-test {phase}`
-- Re-run all pass → `/maestro-verify {phase}`
-- Low coverage → `/quality-test-gen {phase}`
-- Need integration tests → `/quality-integration-test {phase}`
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Phase number required | Prompt user for phase number |
-| E002 | error | Phase artifacts not found | Verify phase has artifacts in state.json |
-| E003 | error | No spec package AND no success_criteria (can't extract scenarios) | Run maestro-spec-generate or maestro-plan first |
-| E004 | error | L1 critical failures block L2/L3 progression | Fix blockers first via quality-debug |
-| W001 | warning | Degraded mode (no spec package, using success_criteria) | Consider running maestro-spec-generate for full coverage |
-| W002 | warning | Some requirements have no testable acceptance criteria | Note in report, suggest spec refinement |
-| W003 | warning | Generator-Critic loop exhausted (3 iterations) without full convergence | Accept current state, proceed with known defects |
-| W004 | warning | Mock services not available for L3 scenarios | Skip L3 or run with --gen-code for TestContainers |
-</error_codes>
-
-<success_criteria>
-- [ ] Phase resolved and spec package loaded (or degraded mode activated)
-- [ ] Business test scenarios extracted from REQ acceptance criteria
-- [ ] RFC 2119 keywords mapped to test priorities
-- [ ] Test fixtures generated (valid/invalid/boundary per REQ data model)
-- [ ] business-test-plan.json written with layer distribution
-- [ ] User confirmed plan (or --auto skipped confirmation)
-- [ ] Test code generated if --gen-code (framework-appropriate)
-- [ ] L1 executed with Generator-Critic loop (max 3 iterations)
-- [ ] L2 executed if no L1 critical failures
-- [ ] L3 executed if no L2 critical failures
-- [ ] Traceability matrix built (every result -> REQ-NNN:AC-N)
-- [ ] business-test-report.json written with requirement_coverage
-- [ ] business-test-summary.md written (human-readable)
-- [ ] index.json updated with business_test section
-- [ ] Issues auto-created for failures (ISS-* in issues.jsonl with req_ref)
-- [ ] Next step routed based on results
-</success_criteria>
+---
+name: quality-business-test
+description: PRD-forward business testing with requirement traceability, fixture generation, and multi-layer execution
+argument-hint: "<phase> [--spec SPEC-xxx] [--layer L1|L2|L3] [--gen-code] [--dry-run] [--re-run] [--auto]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Validate built features against PRD acceptance criteria through automated multi-layer business testing. Unlike quality-test (interactive UAT from code gaps) and quality-test-gen (generate tests from coverage gaps), this command starts from REQ-*.md acceptance criteria and works forward to verify business rules are satisfied.
+
+Key mechanisms:
+- **PRD-forward extraction**: Parse REQ-*.md acceptance criteria with RFC 2119 priority mapping
+- **Three-tier fixture generation**: Schema-derived (valid/invalid/boundary), criteria-derived (expected outcomes), scenario-derived (multi-entity packs)
+- **Progressive L1-L3 layers**: Interface Contract -> Business Rule -> Business Scenario (fail-fast on critical)
+- **Generator-Critic loop**: Max 3 iterations per layer to distinguish test defects from code defects
+- **Requirement traceability**: Every failure traces back to REQ-NNN:AC-N
+- **Degraded mode**: Falls back to success_criteria + plan.json when no spec package exists
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/business-test.md
+</required_reading>
+
+<context>
+Phase: $ARGUMENTS (required -- phase number)
+
+**Flags:**
+- `--spec SPEC-xxx` -- Explicit spec reference (default: auto-detect from index.json.spec_ref)
+- `--layer L1|L2|L3` -- Run only specific layer (default: progressive L1->L2->L3)
+- `--gen-code` -- Generate framework-specific test classes (JUnit/RestAssured, supertest/vitest, pytest/httpx)
+- `--dry-run` -- Extract scenarios and fixtures only, don't execute
+- `--re-run` -- Re-run only previously failed/blocked scenarios
+- `--auto` -- Skip interactive confirmations
+
+**Layer definitions:**
+
+| Layer | Name | Tests | Source |
+|-------|------|-------|--------|
+| L1 | Interface Contract | Single endpoint request/response, input validation, schema compliance | Architecture API endpoints + REQ AC |
+| L2 | Business Rule | Multi-step logic, state transitions, business constraints, edge cases | REQ acceptance criteria + NFR |
+| L3 | Business Scenario | Full user flows, multi-service chains, error propagation | Epic user stories |
+
+**Priority mapping (RFC 2119):**
+
+| Keyword | Priority | Failure = |
+|---------|----------|-----------|
+| MUST / SHALL | critical | blocker |
+| SHOULD / RECOMMENDED | high | major |
+| MAY / OPTIONAL | medium | minor |
+
+Context files:
+- `.workflow/.spec/SPEC-xxx/requirements/REQ-*.md` -- Functional requirements + acceptance criteria
+- `.workflow/.spec/SPEC-xxx/requirements/NFR-*.md` -- Non-functional requirements
+- `.workflow/.spec/SPEC-xxx/architecture/_index.md` -- API endpoints, data model, state machines
+- `.workflow/.spec/SPEC-xxx/epics/EPIC-*.md` -- User stories for E2E scenarios
+- Phase artifacts (resolve via `state.json.artifacts[]` → `.workflow/scratch/` paths):
+  - plan.json -- Task overview (degraded mode)
+  - verification.json -- Cross-reference for must_haves
+  - .tests/business/ -- Previous business test artifacts
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/business-test.md' completely.
+
+**Next-step routing on completion:**
+- All requirements verified → `/maestro-milestone-audit`
+- Failures found → `/quality-debug --from-business-test {phase}`
+- Re-run all pass → `/maestro-verify {phase}`
+- Low coverage → `/quality-test-gen {phase}`
+- Need integration tests → `/quality-integration-test {phase}`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Phase number required | Prompt user for phase number |
+| E002 | error | Phase artifacts not found | Verify phase has artifacts in state.json |
+| E003 | error | No spec package AND no success_criteria (can't extract scenarios) | Run maestro-spec-generate or maestro-plan first |
+| E004 | error | L1 critical failures block L2/L3 progression | Fix blockers first via quality-debug |
+| W001 | warning | Degraded mode (no spec package, using success_criteria) | Consider running maestro-spec-generate for full coverage |
+| W002 | warning | Some requirements have no testable acceptance criteria | Note in report, suggest spec refinement |
+| W003 | warning | Generator-Critic loop exhausted (3 iterations) without full convergence | Accept current state, proceed with known defects |
+| W004 | warning | Mock services not available for L3 scenarios | Skip L3 or run with --gen-code for TestContainers |
+</error_codes>
+
+<success_criteria>
+- [ ] Phase resolved and spec package loaded (or degraded mode activated)
+- [ ] Business test scenarios extracted from REQ acceptance criteria
+- [ ] RFC 2119 keywords mapped to test priorities
+- [ ] Test fixtures generated (valid/invalid/boundary per REQ data model)
+- [ ] business-test-plan.json written with layer distribution
+- [ ] User confirmed plan (or --auto skipped confirmation)
+- [ ] Test code generated if --gen-code (framework-appropriate)
+- [ ] L1 executed with Generator-Critic loop (max 3 iterations)
+- [ ] L2 executed if no L1 critical failures
+- [ ] L3 executed if no L2 critical failures
+- [ ] Traceability matrix built (every result -> REQ-NNN:AC-N)
+- [ ] business-test-report.json written with requirement_coverage
+- [ ] business-test-summary.md written (human-readable)
+- [ ] index.json updated with business_test section
+- [ ] Issues auto-created for failures (ISS-* in issues.jsonl with req_ref)
+- [ ] Next step routed based on results
+</success_criteria>