maestro-flow 0.3.37 → 0.3.39

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

@@ -1,103 +1,103 @@
----
-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, artifact context resolution, and output directory format defined in workflow test.md.
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/test.md' completely.
-
-**Command-specific extensions (not in workflow):**
-
-**Review findings integration** (from related review artifacts):
-- Extract critical/high findings as additional test scenarios, marked `source: "review_finding"`
-- When review verdict is "BLOCK" and review-finding tests fail, auto-enter gap-fix loop
-
-**Debug root cause integration** (from related debug artifacts):
-- Generate regression test scenarios from confirmed root causes, marked `source: "debug_root_cause"`
-
-**Register artifact on completion:**
-```
-Append to state.json.artifacts[]:
-{
-  id: nextArtifactId(artifacts, "test"),  // TST-001
-  type: "test",
-  milestone: current_milestone,
-  phase: target_phase,
-  scope: "phase",
-  path: "scratch/{YYYYMMDD}-test-P{N}-{slug}",
-  status: issues == 0 ? "completed" : "failed",
-  depends_on: exec_art.id,
-  harvested: false,
-  created_at: start_time,
-  completed_at: now()
-}
-```
-
-**Next-step routing on completion:**
-- All tests pass → `/maestro-milestone-audit`
-- Issues found, --auto-fix ran and succeeded → `/maestro-verify {phase}`
-- Issues found, --auto-fix ran but gaps remain → `/quality-debug --from-uat {phase}`
-- Issues found, manual fix needed → `/quality-debug --from-uat {phase}`
-- Coverage below threshold → `/quality-auto-test {phase}`
-- Need integration tests → `/quality-auto-test {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 `/maestro-verify` first |
-| E003 | error | Smoke test failed (app won't start) | Suggest `/quality-debug` |
-| W001 | warning | One or more test scenarios failed | Auto-diagnose, suggest fix options |
-| W002 | warning | Coverage below threshold | Suggest `/quality-auto-test` |
-</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>
+---
+name: quality-test
+description: Conversational UAT with auto-diagnosis and gap closure
+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, artifact context resolution, and output directory format defined in workflow test.md.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/test.md' completely.
+
+**Command-specific extensions (not in workflow):**
+
+**Review findings integration** (from related review artifacts):
+- Extract critical/high findings as additional test scenarios, marked `source: "review_finding"`
+- When review verdict is "BLOCK" and review-finding tests fail, auto-enter gap-fix loop
+
+**Debug root cause integration** (from related debug artifacts):
+- Generate regression test scenarios from confirmed root causes, marked `source: "debug_root_cause"`
+
+**Register artifact on completion:**
+```
+Append to state.json.artifacts[]:
+{
+  id: nextArtifactId(artifacts, "test"),  // TST-001
+  type: "test",
+  milestone: current_milestone,
+  phase: target_phase,
+  scope: "phase",
+  path: "scratch/{YYYYMMDD}-test-P{N}-{slug}",
+  status: issues == 0 ? "completed" : "failed",
+  depends_on: exec_art.id,
+  harvested: false,
+  created_at: start_time,
+  completed_at: now()
+}
+```
+
+**Next-step routing on completion:**
+- All tests pass → `/maestro-milestone-audit`
+- Issues found, --auto-fix ran and succeeded → `/maestro-verify {phase}`
+- Issues found, --auto-fix ran but gaps remain → `/quality-debug --from-uat {phase}`
+- Issues found, manual fix needed → `/quality-debug --from-uat {phase}`
+- Coverage below threshold → `/quality-auto-test {phase}`
+- Need integration tests → `/quality-auto-test {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 `/maestro-verify` first |
+| E003 | error | Smoke test failed (app won't start) | Suggest `/quality-debug` |
+| W001 | warning | One or more test scenarios failed | Auto-diagnose, suggest fix options |
+| W002 | warning | Coverage below threshold | Suggest `/quality-auto-test` |
+</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

@@ -1,49 +1,49 @@
----
-name: spec-add
-description: Add a spec entry to the appropriate specs file by category
-argument-hint: "[--scope project|global|team|personal] <category> <content>"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
----
-<purpose>
-Add a knowledge entry to the specs system using `<spec-entry>` closed-tag format.
-Each category maps 1:1 to a single target file — no dual-write.
-Supports 4 scopes: project (default), global, team, personal.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/specs-add.md
-</required_reading>
-
-<context>
-$ARGUMENTS -- expects `[--scope <scope>] [--uid <uid>] <category> <content>`
-
-Scope-to-directory mapping, category-to-file mapping, and entry format defined in workflow specs-add.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 | parse_input |
-| E002 | fatal | Specs directory not initialized -- run `maestro spec init --scope <scope>` | validate_entry |
-| E003 | fatal | Invalid category -- must be one of: coding, arch, quality, debug, test, review, learning | parse_input |
-| E004 | fatal | Invalid scope -- must be one of: project, global, team, personal | parse_input |
-| E005 | fatal | Personal scope requires uid -- use `--uid` or run `maestro collab join` first | parse_input |
-</error_codes>
-
-<success_criteria>
-- [ ] Scope and category parsed and validated
-- [ ] Keywords auto-extracted from content (3-5 relevant terms)
-- [ ] Entry written in `<spec-entry>` closed-tag format
-- [ ] Entry appended to correct target file for scope
-- [ ] Confirmation report displayed with scope, path, keywords
-- [ ] Next step: `maestro spec load --scope <scope> --keyword {keyword}` to verify
-</success_criteria>
+---
+name: spec-add
+description: Add spec entry by category
+argument-hint: "[--scope project|global|team|personal] <category> <content>"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+---
+<purpose>
+Add a knowledge entry to the specs system using `<spec-entry>` closed-tag format.
+Each category maps 1:1 to a single target file — no dual-write.
+Supports 4 scopes: project (default), global, team, personal.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/specs-add.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- expects `[--scope <scope>] [--uid <uid>] <category> <content>`
+
+Scope-to-directory mapping, category-to-file mapping, and entry format defined in workflow specs-add.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 | parse_input |
+| E002 | fatal | Specs directory not initialized -- run `maestro spec init --scope <scope>` | validate_entry |
+| E003 | fatal | Invalid category -- must be one of: coding, arch, quality, debug, test, review, learning | parse_input |
+| E004 | fatal | Invalid scope -- must be one of: project, global, team, personal | parse_input |
+| E005 | fatal | Personal scope requires uid -- use `--uid` or run `maestro collab join` first | parse_input |
+</error_codes>
+
+<success_criteria>
+- [ ] Scope and category parsed and validated
+- [ ] Keywords auto-extracted from content (3-5 relevant terms)
+- [ ] Entry written in `<spec-entry>` closed-tag format
+- [ ] Entry appended to correct target file for scope
+- [ ] Confirmation report displayed with scope, path, keywords
+- [ ] Next step: `maestro spec load --scope <scope> --keyword {keyword}` to verify
+</success_criteria>

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

@@ -1,51 +1,51 @@
----
-name: spec-load
-description: Load relevant specs and lessons for current context (used by agents before execution)
-argument-hint: "[--category <type>] [--keyword <word>] [--with-lessons]"
-allowed-tools:
-  - Read
-  - Bash
-  - Glob
-  - Grep
----
-<purpose>
-Load and display relevant spec files for the current working context.
-Supports filtering by category (file-level) and keyword (entry-level via `<spec-entry>` tags).
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/specs-load.md
-</required_reading>
-
-<context>
-$ARGUMENTS -- optional flags and keyword
-
-Category-to-file mapping (1:1) and flag details defined in workflow specs-load.md.
-
-**Examples:**
-```
-/spec-load --keyword auth
-/spec-load --category coding --keyword naming
-/spec-load --category arch
-```
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/specs-load.md' completely.
-</execution>
-
-<error_codes>
-| Code | Severity | Description | Stage |
-|------|----------|-------------|-------|
-| E001 | fatal | `.workflow/specs/` not initialized -- run `/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 and/or keyword parsed from arguments
-- [ ] Spec files loaded per category mapping
-- [ ] Keyword filtering applied at entry level (via `<spec-entry>` keywords attribute)
-- [ ] Legacy entries filtered by text grep fallback
-- [ ] Results displayed with file:category references
-</success_criteria>
-</output>
+---
+name: spec-load
+description: Load specs and lessons for current context
+argument-hint: "[--category <type>] [--keyword <word>] [--with-lessons]"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+---
+<purpose>
+Load and display relevant spec files for the current working context.
+Supports filtering by category (file-level) and keyword (entry-level via `<spec-entry>` tags).
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/specs-load.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- optional flags and keyword
+
+Category-to-file mapping (1:1) and flag details defined in workflow specs-load.md.
+
+**Examples:**
+```
+/spec-load --keyword auth
+/spec-load --category coding --keyword naming
+/spec-load --category arch
+```
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/specs-load.md' completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | fatal | `.workflow/specs/` not initialized -- run `/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 and/or keyword parsed from arguments
+- [ ] Spec files loaded per category mapping
+- [ ] Keyword filtering applied at entry level (via `<spec-entry>` keywords attribute)
+- [ ] Legacy entries filtered by text grep fallback
+- [ ] Results displayed with file:category references
+</success_criteria>
+</output>

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

@@ -1,51 +1,51 @@
----
-name: spec-remove
-description: Remove a spec entry from a specs file by entry ID
-argument-hint: "<entry-id>"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - AskUserQuestion
----
-<purpose>
-Remove a `<spec-entry>` from a specs file. Symmetric with `/spec-add`.
-Uses `maestro wiki remove-entry` for atomic removal with index auto-update.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/specs-remove.md
-</required_reading>
-
-<context>
-$ARGUMENTS -- expects `<entry-id>` (e.g., `spec-learnings-003`, `spec-coding-conventions-001`)
-
-**Entry ID format**: `spec-{file-stem}-{NNN}` — the sub-node ID assigned by WikiIndexer when indexing `<spec-entry>` blocks.
-
-**Discovery**: Use `maestro wiki list --type spec --json` or `/spec-load --keyword <term>` to find entry IDs.
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/specs-remove.md' completely.
-</execution>
-
-<error_codes>
-| Code | Severity | Description | Stage |
-|------|----------|-------------|-------|
-| E001 | fatal | Entry ID is required -- usage: `/spec-remove <entry-id>` | parse_input |
-| E002 | fatal | `.workflow/specs/` not initialized -- run `/spec-setup` first | validate |
-| E003 | fatal | Entry ID not found in wiki index | lookup |
-| E004 | fatal | Entry is not a spec sub-node (wrong type) | validate |
-</error_codes>
-
-<success_criteria>
-- [ ] Entry ID parsed and validated
-- [ ] Entry found in wiki index (type=spec, is sub-node)
-- [ ] User confirmed removal (unless -y flag)
-- [ ] Entry removed from container file via `maestro wiki remove-entry`
-- [ ] Wiki index auto-updated
-- [ ] Confirmation displayed with removed entry details
-</success_criteria>
+---
+name: spec-remove
+description: Remove spec entry by ID
+argument-hint: "<entry-id>"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<purpose>
+Remove a `<spec-entry>` from a specs file. Symmetric with `/spec-add`.
+Uses `maestro wiki remove-entry` for atomic removal with index auto-update.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/specs-remove.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- expects `<entry-id>` (e.g., `spec-learnings-003`, `spec-coding-conventions-001`)
+
+**Entry ID format**: `spec-{file-stem}-{NNN}` — the sub-node ID assigned by WikiIndexer when indexing `<spec-entry>` blocks.
+
+**Discovery**: Use `maestro wiki list --type spec --json` or `/spec-load --keyword <term>` to find entry IDs.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/specs-remove.md' completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | fatal | Entry ID is required -- usage: `/spec-remove <entry-id>` | parse_input |
+| E002 | fatal | `.workflow/specs/` not initialized -- run `/spec-setup` first | validate |
+| E003 | fatal | Entry ID not found in wiki index | lookup |
+| E004 | fatal | Entry is not a spec sub-node (wrong type) | validate |
+</error_codes>
+
+<success_criteria>
+- [ ] Entry ID parsed and validated
+- [ ] Entry found in wiki index (type=spec, is sub-node)
+- [ ] User confirmed removal (unless -y flag)
+- [ ] Entry removed from container file via `maestro wiki remove-entry`
+- [ ] Wiki index auto-updated
+- [ ] Confirmation displayed with removed entry details
+</success_criteria>

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

@@ -1,51 +1,51 @@
----
-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.
-Core files (coding, arch, learning) are always created. Optional files (quality, debug, test, review) are created only when relevant signals are detected.
-All output lands in `.workflow/specs/`.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/specs-setup.md
-</required_reading>
-
-<deferred_reading>
-</deferred_reading>
-
-<context>
-$ARGUMENTS (no arguments expected)
-
-**Preconditions:**
-- `.workflow/` directory must exist (created by `/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 `/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
-- [ ] Core files always created: `coding-conventions.md`, `architecture-constraints.md`, `learnings.md`
-- [ ] Optional files created when detected: `quality-rules.md` (linter/CI), `test-conventions.md` (test framework), `debug-notes.md` (on demand), `review-standards.md` (on demand)
-- [ ] Report displayed with summary and next steps
-</success_criteria>
-</output>
+---
+name: spec-setup
+description: Initialize specs from project structure
+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.
+Core files (coding, arch, learning) are always created. Optional files (quality, debug, test, review) are created only when relevant signals are detected.
+All output lands in `.workflow/specs/`.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/specs-setup.md
+</required_reading>
+
+<deferred_reading>
+</deferred_reading>
+
+<context>
+$ARGUMENTS (no arguments expected)
+
+**Preconditions:**
+- `.workflow/` directory must exist (created by `/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 `/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
+- [ ] Core files always created: `coding-conventions.md`, `architecture-constraints.md`, `learnings.md`
+- [ ] Optional files created when detected: `quality-rules.md` (linter/CI), `test-conventions.md` (test framework), `debug-notes.md` (on demand), `review-standards.md` (on demand)
+- [ ] Report displayed with summary and next steps
+</success_criteria>
+</output>