maestro-flow 0.3.3 → 0.3.5

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

@@ -0,0 +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
+- `.workflow/phases/{NN}-{slug}/index.json` -- Phase metadata, success_criteria
+- `.workflow/phases/{NN}-{slug}/plan.json` -- Task overview (degraded mode)
+- `.workflow/phases/{NN}-{slug}/verification.json` -- Cross-reference for must_haves
+- `.workflow/phases/{NN}-{slug}/.tests/business/` -- Previous business test artifacts
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/business-test.md' completely.
+
+**Next-step routing on completion:**
+- All requirements verified → Skill({ skill: "maestro-phase-transition", args: "{phase}" })
+- Failures found → Skill({ skill: "quality-debug", args: "--from-business-test {phase}" })
+- Re-run all pass → Skill({ skill: "maestro-verify", args: "{phase}" })
+- Low coverage → Skill({ skill: "quality-test-gen", args: "{phase}" })
+- Need integration tests → Skill({ skill: "quality-integration-test", args: "{phase}" })
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Phase number required | Prompt user for phase number |
+| E002 | error | Phase directory not found | Verify phase exists in .workflow/phases/ |
+| 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>

package/.codex/skills/maestro-init/SKILL.md

@@ -1,167 +1,167 @@
----
-name: maestro-init
-description: Initialize project with auto state detection — creates .workflow/ directory, project.md, state.json, config.json, and specs/
-argument-hint: "[--auto] [--from-brainstorm SESSION-ID]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
----
-
-## Auto Mode
-
-When `--auto`: After config questions, run research without further interaction. Expects idea document via @ reference.
-
-# Maestro Init (Single Agent)
-
-## Usage
-
-```bash
-$maestro-init ""
-$maestro-init "--auto"
-$maestro-init "--from-brainstorm brainstorm-auth-20260318"
-```
-
-**Flags**:
-- `--auto`: Skip interactive questioning; extract from provided document
-- `--from-brainstorm SESSION-ID`: Import vision/goals/constraints from brainstorm guidance-specification.md
-
-**Output**: `.workflow/` directory with project.md, state.json, config.json, specs/
-
----
-
-## Overview
-
-Sequential project setup skill. Detects project state (empty/code/existing), gathers project information through deep questioning or document extraction, then creates the `.workflow/` directory structure. No parallel agents — single sequential flow.
-
----
-
-## Implementation
-
-### Step 1: Parse Arguments
-
-Extract flags from arguments:
-- `--auto` flag presence
-- `--from-brainstorm SESSION-ID` value
-- Remaining text as project description
-
-### Step 2: Detect Project State
-
-```bash
-# Check existing state
-ls .workflow/state.json 2>/dev/null
-ls package.json pyproject.toml Cargo.toml go.mod 2>/dev/null
-```
-
-Classify as:
-- **existing**: `.workflow/state.json` found — warn and exit (E002)
-- **code**: Source files present but no `.workflow/` — onboarding existing codebase
-- **empty**: Greenfield project
-
-### Step 3: Gather Project Information
-
-**If `--from-brainstorm`**:
-- Read `.workflow/.brainstorm/{SESSION-ID}/guidance-specification.md`
-- Extract: vision, goals, constraints, terminology, tech decisions
-- Skip interactive questioning
-
-**If `--auto`**:
-- Extract project info from provided document/@ reference
-- Minimal interactive questions (confirm core value only)
-
-**Otherwise (interactive)**:
-- Deep questioning flow:
-  1. What is the core value proposition?
-  2. Who are the target users?
-  3. What are the key requirements? (follow threads, don't rush)
-  4. What are known constraints/limitations?
-  5. What tech stack preferences exist?
-- Follow each thread with clarifying questions until satisfied
-
-### Step 4: Read Templates
-
-Read the following templates:
-- `~/.maestro/templates/project.md`
-- `~/.maestro/templates/state.json`
-- `~/.maestro/templates/config.json`
-
-### Step 5: Create .workflow/ Structure
-
-```bash
-mkdir -p .workflow/specs .workflow/phases .workflow/scratch .workflow/codebase
-```
-
-### Step 6: Write project.md
-
-Populate template with gathered information:
-- Project name, core value proposition
-- Requirements: Validated / Active / Out of Scope
-- Key decisions and constraints
-- Tech stack (detected or specified)
-
-Write to `.workflow/project.md`.
-
-### Step 7: Write state.json
-
-Initialize state from template:
-- `current_phase`: null
-- `current_milestone`: null
-- `status`: "initialized"
-
-Write to `.workflow/state.json`.
-
-### Step 8: Write config.json
-
-Configuration questions (or defaults for --auto):
-- Granularity: fine / medium / coarse
-- Workflow agents: enable/disable optional agents
-- Gate preferences: verification strictness
-
-Write to `.workflow/config.json`.
-
-### Step 9: Initialize specs/
-
-Create convention files in `.workflow/specs/`:
-- `conventions.md` — detected or specified coding conventions
-- `learnings.md` — empty, populated during phase transitions
-
-### Step 10: Completion Report
-
-```
-=== WORKFLOW INITIALIZED ===
-Project: {project_name}
-State:   .workflow/state.json (active)
-
-Created:
-  .workflow/project.md
-  .workflow/state.json
-  .workflow/config.json
-  .workflow/specs/
-
-Next steps (choose one path to create roadmap):
-  $maestro-spec-generate "<idea>"   -- Full spec package + roadmap (heavy)
-  $maestro-roadmap "<requirement>"  -- Direct interactive roadmap (light)
-
-Other commands:
-  $maestro-status                   -- View project dashboard
-  $maestro-brainstorm "<topic>"     -- Explore ideas first
-  $maestro-quick "<task>"           -- Quick ad-hoc task
-```
-
----
-
-## Error Handling
-
-| Code | Severity | Description | Recovery |
-|------|----------|-------------|----------|
-| E001 | error | No arguments when --auto requires document | Ask user for document reference |
-| E002 | error | .workflow/ already exists | Show status, suggest manage-status |
-| E003 | error | Brainstorm session not found | List available sessions |
-| W001 | warning | Could not detect tech stack | Continue with manual input |
-
----
-
-## Core Rules
-
-1. **Never create roadmap** — init only creates .workflow/ structure; roadmap is a separate step
-2. **Deep questioning over speed** — follow threads, ask clarifying questions (unless --auto)
-3. **Detect, don't assume** — scan for existing files, package managers, frameworks before asking
-4. **Templates are source of truth** — always read templates before writing files
-5. **Idempotent check** — if .workflow/ exists, refuse to overwrite (E002)
+---
+name: maestro-init
+description: Initialize project with auto state detection — creates .workflow/ directory, project.md, state.json, config.json, and specs/
+argument-hint: "[--auto] [--from-brainstorm SESSION-ID]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+## Auto Mode
+
+When `--auto`: After config questions, run research without further interaction. Expects idea document via @ reference.
+
+# Maestro Init (Single Agent)
+
+## Usage
+
+```bash
+$maestro-init ""
+$maestro-init "--auto"
+$maestro-init "--from-brainstorm brainstorm-auth-20260318"
+```
+
+**Flags**:
+- `--auto`: Skip interactive questioning; extract from provided document
+- `--from-brainstorm SESSION-ID`: Import vision/goals/constraints from brainstorm guidance-specification.md
+
+**Output**: `.workflow/` directory with project.md, state.json, config.json, specs/
+
+---
+
+## Overview
+
+Sequential project setup skill. Detects project state (empty/code/existing), gathers project information through deep questioning or document extraction, then creates the `.workflow/` directory structure. No parallel agents — single sequential flow.
+
+---
+
+## Implementation
+
+### Step 1: Parse Arguments
+
+Extract flags from arguments:
+- `--auto` flag presence
+- `--from-brainstorm SESSION-ID` value
+- Remaining text as project description
+
+### Step 2: Detect Project State
+
+```bash
+# Check existing state
+ls .workflow/state.json 2>/dev/null
+ls package.json pyproject.toml Cargo.toml go.mod 2>/dev/null
+```
+
+Classify as:
+- **existing**: `.workflow/state.json` found — warn and exit (E002)
+- **code**: Source files present but no `.workflow/` — onboarding existing codebase
+- **empty**: Greenfield project
+
+### Step 3: Gather Project Information
+
+**If `--from-brainstorm`**:
+- Read `.workflow/.brainstorm/{SESSION-ID}/guidance-specification.md`
+- Extract: vision, goals, constraints, terminology, tech decisions
+- Skip interactive questioning
+
+**If `--auto`**:
+- Extract project info from provided document/@ reference
+- Minimal interactive questions (confirm core value only)
+
+**Otherwise (interactive)**:
+- Deep questioning flow:
+  1. What is the core value proposition?
+  2. Who are the target users?
+  3. What are the key requirements? (follow threads, don't rush)
+  4. What are known constraints/limitations?
+  5. What tech stack preferences exist?
+- Follow each thread with clarifying questions until satisfied
+
+### Step 4: Read Templates
+
+Read the following templates:
+- `~/.maestro/templates/project.md`
+- `~/.maestro/templates/state.json`
+- `~/.maestro/templates/config.json`
+
+### Step 5: Create .workflow/ Structure
+
+```bash
+mkdir -p .workflow/specs .workflow/phases .workflow/scratch .workflow/codebase
+```
+
+### Step 6: Write project.md
+
+Populate template with gathered information:
+- Project name, core value proposition
+- Requirements: Validated / Active / Out of Scope
+- Key decisions and constraints
+- Tech stack (detected or specified)
+
+Write to `.workflow/project.md`.
+
+### Step 7: Write state.json
+
+Initialize state from template:
+- `current_phase`: null
+- `current_milestone`: null
+- `status`: "initialized"
+
+Write to `.workflow/state.json`.
+
+### Step 8: Write config.json
+
+Configuration questions (or defaults for --auto):
+- Granularity: fine / medium / coarse
+- Workflow agents: enable/disable optional agents
+- Gate preferences: verification strictness
+
+Write to `.workflow/config.json`.
+
+### Step 9: Initialize specs/
+
+Create convention files in `.workflow/specs/`:
+- `conventions.md` — detected or specified coding conventions
+- `learnings.md` — empty, populated during phase transitions
+
+### Step 10: Completion Report
+
+```
+=== WORKFLOW INITIALIZED ===
+Project: {project_name}
+State:   .workflow/state.json (active)
+
+Created:
+  .workflow/project.md
+  .workflow/state.json
+  .workflow/config.json
+  .workflow/specs/
+
+Next steps (choose one path to create roadmap):
+  $maestro-spec-generate "<idea>"   -- Full spec package + roadmap (heavy)
+  $maestro-roadmap "<requirement>"  -- Direct interactive roadmap (light)
+
+Other commands:
+  $manage-status                   -- View project dashboard
+  $maestro-brainstorm "<topic>"     -- Explore ideas first
+  $maestro-quick "<task>"           -- Quick ad-hoc task
+```
+
+---
+
+## Error Handling
+
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | No arguments when --auto requires document | Ask user for document reference |
+| E002 | error | .workflow/ already exists | Show status, suggest manage-status |
+| E003 | error | Brainstorm session not found | List available sessions |
+| W001 | warning | Could not detect tech stack | Continue with manual input |
+
+---
+
+## Core Rules
+
+1. **Never create roadmap** — init only creates .workflow/ structure; roadmap is a separate step
+2. **Deep questioning over speed** — follow threads, ask clarifying questions (unless --auto)
+3. **Detect, don't assume** — scan for existing files, package managers, frameworks before asking
+4. **Templates are source of truth** — always read templates before writing files
+5. **Idempotent check** — if .workflow/ exists, refuse to overwrite (E002)