maestro-flow 0.1.0

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

@@ -0,0 +1,76 @@
+---
+name: quality-test-gen
+description: Generate missing tests with TDD/E2E classification and RED-GREEN methodology
+argument-hint: "<phase> [--layer <unit|e2e|all>]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Generate missing automated tests for a phase based on gap analysis from maestro-verify (Nyquist audit) and quality-test (UAT coverage gaps). Classifies changed files into unit test vs E2E vs skip categories, discovers existing test infrastructure, generates a test plan for user approval, then writes tests using RED-GREEN methodology.
+
+Key mechanisms from GSD add-tests:
+- **TDD/E2E/Skip classification**: Categorize changed files by appropriate test type
+- **Test structure discovery**: Find existing test patterns, frameworks, conventions
+- **Test plan with user approval**: Present plan before writing any tests
+- **RED-GREEN generation**: Write failing test first, verify it targets the right behavior
+- **Bug discovery, not fix**: Tests expose bugs; fixing is for quality-debug or maestro-execute
+
+This command is the "test gap filler" -- it bridges the gap between verification (maestro-verify finds MISSING coverage) and testing (quality-test runs UAT). It produces the automated tests that make Nyquist coverage pass.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/test-gen.md
+</required_reading>
+
+<context>
+Phase: $ARGUMENTS (required -- phase number)
+
+**Flags:**
+- `--layer <unit|e2e|all>` -- Generate only specific test layer (default: all)
+
+Context files:
+- `.workflow/phases/{NN}-{slug}/verification.json` -- Nyquist gaps (MISSING/PARTIAL)
+- `.workflow/phases/{NN}-{slug}/validation.json` -- requirement-to-test mapping
+- `.workflow/phases/{NN}-{slug}/.tests/coverage-report.json` -- UAT coverage gaps
+- `.workflow/phases/{NN}-{slug}/.summaries/TASK-*.md` -- what was built
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/test-gen.md' completely.
+
+**Next-step routing on completion:**
+- All tests pass → Skill({ skill: "quality-test", args: "{phase}" })
+- Bugs discovered (failing tests) → Skill({ skill: "quality-debug", args: "{phase}" })
+- Regressions in existing tests → Skill({ skill: "quality-debug", args: "{phase}" })
+- Coverage still low → Skill({ skill: "quality-test-gen", args: "{phase} --layer {missing_layer}" })
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Phase number required | Check arguments format, re-run with correct input |
+| E002 | error | No verification results found (run maestro-verify first) | Check arguments format, re-run with correct input |
+| E003 | error | No test framework detected | Install test framework or configure test runner |
+| W001 | warning | Some generated tests fail (bugs discovered) | Investigate test failures, fix source code |
+| W002 | warning | Regression in existing tests | Investigate test failures, fix source code |
+</error_codes>
+
+<success_criteria>
+- [ ] Test infrastructure discovered (framework, patterns, conventions)
+- [ ] Gaps identified from verification.json and coverage-report.json
+- [ ] Changed files classified into unit/integration/e2e/skip
+- [ ] Test plan generated and approved by user
+- [ ] Tests written following existing patterns (RED-GREEN methodology)
+- [ ] Tests run and results categorized (passing/failing/regression)
+- [ ] test-gen-report.json written with full results
+- [ ] validation.json updated with new coverage status
+- [ ] Bugs discovered documented (not fixed)
+- [ ] Next step routed (quality-test if pass, quality-debug if bugs discovered)
+</success_criteria>

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

@@ -0,0 +1,86 @@
+---
+name: quality-test
+description: Conversational UAT with session persistence, auto-diagnosis, and gap-plan closure loop
+argument-hint: "[phase] [--smoke] [--auto-fix]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Run UAT-style conversational testing for a completed phase. Designs test scenarios from verification criteria, walks through each scenario interactively one at a time with plain text responses, and records pass/fail results with severity inference.
+
+When issues are found, spawns parallel debug agents (one per gap cluster) to diagnose root causes, then optionally triggers the gap-fix loop (plan --gaps -> execute -> re-verify) to auto-close gaps.
+
+Key mechanisms from GSD verify-work:
+- **Session persistence**: uat.md survives context resets, resume from any point
+- **Severity inference**: Natural language -> blocker/major/minor/cosmetic (never ask)
+- **Cold-start smoke tests**: --smoke flag injects basic sanity tests before UAT
+- **Parallel auto-diagnosis**: Spawn debug agents per gap cluster with pre-filled symptoms
+- **Gap-plan closure loop**: --auto-fix triggers verify -> plan --gaps -> execute -> re-verify
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/test.md
+</required_reading>
+
+<context>
+Phase or task: $ARGUMENTS (optional)
+
+**Flags:**
+- `--smoke` -- Run cold-start smoke tests before UAT (basic sanity: app starts, routes respond, no crash)
+- `--auto-fix` -- After diagnosis, auto-trigger gap-fix loop instead of asking user
+
+Context files resolved from target directory:
+- verification.json (must_haves, gaps from maestro-verify)
+- validation.json (coverage, requirement mapping)
+- index.json (success_criteria, execution results)
+- plan.json (task overview)
+- .summaries/TASK-*.md (execution summaries)
+- uat.md (existing session, if resuming)
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/test.md' completely.
+
+**Next-step routing on completion:**
+- All tests pass → Skill({ skill: "maestro-phase-transition", args: "{phase}" })
+- Issues found, --auto-fix ran and succeeded → Skill({ skill: "maestro-verify", args: "{phase}" })
+- Issues found, --auto-fix ran but gaps remain → Skill({ skill: "quality-debug", args: "--from-uat {phase}" })
+- Issues found, manual fix needed → Skill({ skill: "quality-debug", args: "--from-uat {phase}" })
+- Coverage below threshold → 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 or task target required (no active sessions) | Prompt user for phase number |
+| E002 | error | Phase not verified yet (no verification.json) | Suggest Skill({ skill: "maestro-verify" }) first |
+| E003 | error | Smoke test failed (app won't start) | Suggest Skill({ skill: "quality-debug" }) |
+| W001 | warning | One or more test scenarios failed | Auto-diagnose, suggest fix options |
+| W002 | warning | Coverage below threshold | Suggest Skill({ skill: "quality-test-gen" }) |
+</error_codes>
+
+<success_criteria>
+- [ ] Target resolved (phase or scratch task)
+- [ ] Active sessions checked, resume offered if applicable
+- [ ] Smoke tests run if --smoke flag set
+- [ ] test-plan.json generated with categorized tests mapped to requirements
+- [ ] uat.md created/resumed with all tests
+- [ ] Tests presented one at a time with expected behavior
+- [ ] User responses processed as pass/issue/skip
+- [ ] Severity inferred from natural language (never asked)
+- [ ] Batched writes: on issue, every 5 passes, or completion
+- [ ] test-results.json and coverage-report.json written
+- [ ] index.json uat fields updated
+- [ ] If issues: parallel debug agents spawned per gap cluster
+- [ ] Gaps updated with root_cause, fix_direction, affected_files
+- [ ] Gap-fix loop triggered if --auto-fix (max 2 iterations)
+- [ ] Next step routed (phase-transition if pass, verify if auto-fix success, debug --from-uat if issues, test-gen if low coverage)
+</success_criteria>

package/.claude/commands/spec-add.md

@@ -0,0 +1,56 @@
+---
+name: spec-add
+description: Add a spec entry (bug, pattern, decision, or rule) to the appropriate specs file
+argument-hint: "<type> <content>"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+---
+<purpose>
+Add a knowledge entry to the project specs system, routing it to the correct file by category.
+Each entry is timestamped and appended to learnings.md, then the relevant spec file is updated if the entry warrants a convention or rule change.
+Supports four categories: bug fixes, patterns, architectural decisions, and quality rules.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/specs-add.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- expects `<type> <content>` where type is one of: bug, pattern, decision, rule, debug, test, review, validation
+
+**Type-to-file mapping:**
+| Type | Primary file | Secondary update |
+|------|-------------|-----------------|
+| `bug` | `learnings.md` | -- |
+| `pattern` | `learnings.md` | `coding-conventions.md` |
+| `decision` | `learnings.md` | `architecture-constraints.md` |
+| `rule` | `learnings.md` | `quality-rules.md` |
+| `debug` | `learnings.md` | `debug-notes.md` |
+| `test` | `learnings.md` | `test-conventions.md` |
+| `review` | `learnings.md` | `review-standards.md` |
+| `validation` | `learnings.md` | `validation-rules.md` |
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/specs-add.md' completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | fatal | Category and content are both required -- usage: `<type> <content>` | parse_input |
+| E002 | fatal | `.workflow/specs/` not initialized -- run Skill({ skill: "spec-setup" }) first | validate_entry |
+| E003 | fatal | Invalid category -- must be one of: bug, pattern, decision, rule, debug, test, review, validation | parse_input |
+</error_codes>
+
+<success_criteria>
+- [ ] Category parsed and validated as bug/pattern/decision/rule
+- [ ] Entry appended to `.workflow/specs/learnings.md` with timestamp
+- [ ] Relevant spec file updated (if type is pattern/decision/rule)
+- [ ] Confirmation report displayed
+- [ ] Next step: Skill({ skill: "spec-load", args: "--category {type}" }) to verify, or continue current task
+</success_criteria>

package/.claude/commands/spec-load.md

@@ -0,0 +1,59 @@
+---
+name: spec-load
+description: Load relevant specs for current context (used by agents before execution)
+argument-hint: "[--category <type>] [keyword]"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+---
+<purpose>
+Load and display relevant spec files for the current working context, optionally filtered by category.
+Designed for agents to call before execution to internalize project conventions, constraints, and learnings.
+Returns matched sections with file references ranked by relevance.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/specs-load.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- optional `--category <type>` flag and/or keyword to filter specs
+
+**Category filter** (matches frontmatter `category` field):
+| Category | Files loaded |
+|----------|-------------|
+| `general` | `learnings.md` |
+| `exploration` | _(reserved)_ |
+| `planning` | `architecture-constraints.md` |
+| `execution` | `coding-conventions.md`, `quality-rules.md` |
+| `debug` | `debug-notes.md` |
+| `test` | `test-conventions.md` |
+| `review` | `review-standards.md` |
+| `validation` | `validation-rules.md` |
+| `all` (default) | All spec files |
+
+**Keyword:** If provided, search within loaded files for matching sections.
+If no arguments, loads all specs for the active phase/task context.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/specs-load.md' completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | fatal | `.workflow/specs/` not initialized -- run Skill({ skill: "spec-setup" }) first | detect_context |
+| W001 | warning | No matching specs found for keyword -- showing all specs in category instead | load_specs |
+</error_codes>
+
+<success_criteria>
+- [ ] Category filter parsed correctly (or defaults to all)
+- [ ] Spec files resolved and read
+- [ ] Keyword filtering applied if provided
+- [ ] Results displayed with file:line references
+- [ ] Relevant specs loaded into agent context
+- [ ] Next step: proceed with current task using loaded specs as context
+</success_criteria>

package/.claude/commands/spec-map.md

@@ -0,0 +1,82 @@
+---
+name: spec-map
+description: Analyze codebase with parallel mapper agents to produce .workflow/codebase/ documents
+argument-hint: "[optional: focus area, e.g., 'api' or 'auth']"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+---
+<purpose>
+Analyze the existing codebase using 4 parallel mapper agents, each focused on a different dimension.
+Produces structured documents in `.workflow/codebase/` that downstream commands consume for planning and execution.
+Can run before or after Skill({ skill: "maestro-init" }) -- works on any codebase with source files.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/map.md
+@~/.maestro/agents/workflow-codebase-mapper.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- optional focus area (e.g., "api", "auth", "database") to scope mapper agents
+
+**Load project state if exists:**
+Check for `.workflow/state.json` -- loads context if project already initialized.
+
+**This command can run:**
+- Before Skill({ skill: "maestro-init" }) (brownfield codebases) -- creates codebase map first
+- After Skill({ skill: "maestro-init" }) (greenfield codebases) -- updates codebase map as code evolves
+- Anytime to refresh codebase understanding
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/map.md' completely.
+
+**Mapper agent assignments:**
+| Agent | Focus | Output file |
+|-------|-------|-------------|
+| Mapper 1 | **Tech stack** -- languages, frameworks, dependencies, build system | `tech-stack.md` |
+| Mapper 2 | **Architecture** -- layers, module boundaries, data flow, entry points | `architecture.md` |
+| Mapper 3 | **Features** -- capabilities, API surface, user-facing functionality | `features.md` |
+| Mapper 4 | **Cross-cutting concerns** -- error handling, logging, auth, config, testing | `concerns.md` |
+
+**Report format on completion:**
+```
+== map complete ==
+Output: .workflow/codebase/
+  tech-stack.md     [OK|MISSING]
+  architecture.md   [OK|MISSING]
+  features.md       [OK|MISSING]
+  concerns.md       [OK|MISSING]
+
+Focus: <focus_area or "full codebase">
+Agents: <N>/4 completed
+
+Next: Skill({ skill: "maestro-init" }) (if not initialized)
+      Skill({ skill: "manage-status" }) (if initialized)
+      Skill({ skill: "manage-codebase-refresh" }) (to update specific docs)
+```
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | fatal | `.workflow/` directory not initialized -- run Skill({ skill: "maestro-init" }) first or create manually | parse_input |
+| W001 | warning | Mapper agent failed for one dimension -- remaining docs still valid | spawn_mappers |
+| W002 | warning | `.workflow/codebase/` already exists -- user prompted for refresh/skip/merge | check_existing |
+</error_codes>
+
+<success_criteria>
+- [ ] `.workflow/codebase/` directory created
+- [ ] All 4 mapper agents spawned in parallel
+- [ ] `tech-stack.md` written with language/framework/dependency analysis
+- [ ] `architecture.md` written with structural analysis
+- [ ] `features.md` written with capability inventory
+- [ ] `concerns.md` written with cross-cutting concern analysis
+- [ ] All output docs verified as non-empty
+- [ ] Report displayed with next steps
+</success_criteria>

package/.claude/commands/spec-setup.md

@@ -0,0 +1,57 @@
+---
+name: spec-setup
+description: Initialize system specs by scanning project structure and generating conventions
+argument-hint: ""
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+---
+<purpose>
+Initialize the project-level specs directory by scanning the codebase for conventions, patterns, and tech stack.
+Produces four spec files plus a tech profile JSON that downstream agents and commands consume for consistent coding.
+All output lands in `.workflow/specs/` and `.workflow/project-tech.json`.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/specs-setup.md
+</required_reading>
+
+<deferred_reading>
+- [project-tech.json](~/.maestro/templates/project-tech.json) — read when generating project-tech configuration
+</deferred_reading>
+
+<context>
+$ARGUMENTS (no arguments expected)
+
+**Preconditions:**
+- `.workflow/` directory must exist (created by Skill({ skill: "maestro-init" }))  # (see code: E001)
+- Project must contain source files to scan  # (see code: E002)
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/specs-setup.md' completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | fatal | `.workflow/` directory not initialized -- run Skill({ skill: "maestro-init" }) first | parse_input |
+| E002 | fatal | No source files found in project -- nothing to scan | scan_codebase |
+| W001 | warning | Convention detection uncertain for one or more categories -- marked `[UNCERTAIN]` | generate_specs |
+</error_codes>
+
+<success_criteria>
+- [ ] `.workflow/specs/` directory created
+- [ ] `coding-conventions.md` written with detected patterns
+- [ ] `architecture-constraints.md` written with structural rules
+- [ ] `quality-rules.md` written with auto-detected and manual sections
+- [ ] `learnings.md` initialized with format instructions
+- [ ] `project-tech.json` written with detected tech stack
+- [ ] Report displayed with summary and next steps:
+  - Build codebase docs → Skill({ skill: "spec-map" })
+  - Load specs for task → Skill({ skill: "spec-load" })
+  - Add new knowledge → Skill({ skill: "spec-add", args: "<type> <content>" })
+</success_criteria>