maestro-flow-one 0.2.34 → 0.2.35

package/maestro-flow/commands/quality/test.md

@@ -1,117 +1,147 @@
----
-name: quality-test
-description: Use when implementation needs user acceptance testing with interactive verification 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):**
-
-**Knowledge context loading** (before test design):
-- Wiki search: `maestro search "<phase/feature keywords>" --json` → prior test strategies, recipes, decisions
-- Role knowledge: `maestro search --category test` → select relevant → `maestro wiki load <id>`
-- Specs + tools: `maestro spec load --category test` → test conventions + discoverable knowhow tools
-
-**Test tool discovery** (knowhow tools as scenario source):
-- Load registered test tools: `maestro spec load --category test --keyword <feature>`
-- If tools found, extract their steps as additional test scenarios marked `source: "tool"`
-- Each numbered step in a tool becomes a UAT test with its assertion as `expected` behavior
-
-**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-execute {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-execute` first (verification is built-in) |
-| 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
-- [ ] UAT confidence scored with 4-dimension factor model
-- [ ] Readiness gate checked before final report
-- [ ] Pressure pass completed if > 80% pass rate
-- [ ] Confidence summary appended to uat.md
-- [ ] 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: Use when implementation needs user acceptance testing with interactive verification and gap closure
+argument-hint: "[phase] [--smoke] [--auto-fix]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+UAT-style conversational testing for a completed phase. Interactive scenario walk-through with severity inference. Issues trigger parallel debug agents and optional gap-fix loop (--auto-fix).
+</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.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Setup → Test Design**
+- REQUIRED: Target resolved (phase or scratch task). E001 if missing.
+- REQUIRED: Smoke tests pass (if --smoke). E003 if fail.
+- BLOCKED if missing: cannot design tests without resolved target.
+
+**GATE 2: Test Design → Execution**
+- REQUIRED: test-plan.json generated with categorized tests mapped to requirements.
+- REQUIRED: uat.md created or resumed.
+- BLOCKED if plan missing: do not start interactive testing without plan.
+
+**GATE 3: Execution → Completion**
+- REQUIRED: All tests presented and responses processed.
+- REQUIRED: UAT confidence scored with 4-dimension factor model.
+- REQUIRED: Pressure pass completed if > 80% pass rate.
+- BLOCKED if incomplete: finish all scenarios before reporting.
+
+**Command-specific extensions (not in workflow):**
+
+**Knowledge context loading** (before test design):
+- Wiki search: `maestro search "<phase/feature keywords>" --json` → prior test strategies, recipes, decisions
+- Role knowledge: `maestro search --category test` → select relevant → `maestro wiki load <id>`
+- Specs + tools: `maestro spec load --category test` → test conventions + discoverable knowhow tools
+
+**Test tool discovery** (knowhow tools as scenario source):
+- Load registered test tools: `maestro spec load --category test --keyword <feature>`
+- If tools found, extract their steps as additional test scenarios marked `source: "tool"`
+- Each numbered step in a tool becomes a UAT test with its assertion as `expected` behavior
+
+**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()
+}
+```
+
+</execution>
+
+<completion>
+### Standalone report
+
+```
+--- COMPLETION STATUS ---
+STATUS: DONE|DONE_WITH_CONCERNS|NEEDS_RETRY
+CONCERNS: {description if applicable}
+--- END STATUS ---
+```
+
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| All tests pass | `/maestro-milestone-audit` |
+| --auto-fix succeeded | `/maestro-execute {phase}` |
+| --auto-fix gaps remain | `/quality-debug --from-uat {phase}` |
+| Manual fix needed | `/quality-debug --from-uat {phase}` |
+| Coverage below threshold | `/quality-auto-test {phase}` |
+</completion>
+
+<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-execute` first (verification is built-in) |
+| 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
+- [ ] UAT confidence scored with 4-dimension factor model
+- [ ] Readiness gate checked before final report
+- [ ] Pressure pass completed if > 80% pass rate
+- [ ] Confidence summary appended to uat.md
+- [ ] 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/maestro-flow/commands/spec/add.md

@@ -1,70 +1,77 @@
----
-name: spec-add
-description: Add spec entry by category with role tagging
-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.
-Entries use `category` attribute to declare which category they belong to.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/specs-add.md
-</required_reading>
-
-<context>
-$ARGUMENTS -- expects `[--scope <scope>] [--uid <uid>] <category> <content>`
-
-**Options:**
-- `--description <desc>` — One-line description for search results (falls back to content[:240])
-- `--ref <path>` — Create as index entry referencing a knowhow document. If the path exists, only creates the spec index entry. If path doesn't exist, also creates the knowhow file.
-- `--knowhow-type <type>` — Knowhow document type when creating with --ref (asset, blueprint, document, template, recipe, reference, decision)
-
-Scope-to-directory mapping, category-to-file mapping, and entry format defined in workflow specs-add.md.
-
-**Examples:**
-```bash
-# English content → English keywords
-/spec-add coding "Named exports" "Always use named exports" --keywords "exports,naming"
-
-# With description for search results
-/spec-add coding "OAuth PKCE Flow" "完整 PKCE 集成流程" --keywords "oauth,pkce" --description "OAuth 2.0 PKCE 认证流程规范"
-
-# Chinese content → Chinese keywords
-/spec-add coding "命名导出规范" "始终使用命名导出" --keywords "导出,命名,模块"
-
-# Ref mode
-/spec-add arch "OAuth PKCE 集成" "完整流程设计" --ref knowhow/AST-oauth-flow.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, tools, ui | 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 with role tagging
+argument-hint: "[--scope project|global|team|personal] <category> <content>"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+---
+<purpose>
+Add `<spec-entry>` to specs by category. 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>`
+
+**Options:**
+- `--description <desc>` — One-line description for search results (falls back to content[:240])
+- `--ref <path>` — Create as index entry referencing a knowhow document. If the path exists, only creates the spec index entry. If path doesn't exist, also creates the knowhow file.
+- `--knowhow-type <type>` — Knowhow document type when creating with --ref (asset, blueprint, document, template, recipe, reference, decision)
+
+Scope-to-directory mapping, category-to-file mapping, and entry format defined in workflow specs-add.md.
+
+**Examples:**
+```bash
+# English content → English keywords
+/spec-add coding "Named exports" "Always use named exports" --keywords "exports,naming"
+
+# With description for search results
+/spec-add coding "OAuth PKCE Flow" "完整 PKCE 集成流程" --keywords "oauth,pkce" --description "OAuth 2.0 PKCE 认证流程规范"
+
+# Chinese content → Chinese keywords
+/spec-add coding "命名导出规范" "始终使用命名导出" --keywords "导出,命名,模块"
+
+# Ref mode
+/spec-add arch "OAuth PKCE 集成" "完整流程设计" --ref knowhow/AST-oauth-flow.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, tools, ui | 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 routed
+</success_criteria>
+
+<completion>
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Verify entry added | `maestro spec load --scope <scope> --keyword {keyword}` |
+| Add more entries | `/spec-add <category>` |
+| View all specs | `/spec-load --category <category>` |
+</completion>

package/maestro-flow/commands/spec/setup.md

@@ -1,52 +1,49 @@
----
-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, learnings) are always created. Optional spec files (quality, test, ui) are created only when relevant signals are detected.
-Additionally, generates recipe-type knowhow docs in `.workflow/knowhow/` for detected operational workflows (test / debug / build / dev / lint) — capturing "how to do X in this project" so future agents can find them via `maestro search`.
-Spec output lands in `.workflow/specs/`; recipe output lands in `.workflow/knowhow/`.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/specs-setup.md
-</required_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 |
-| W002 | warning | Workflow recipe signals detected but commands ambiguous -- recipe skipped | generate_recipes |
-| W003 | warning | Existing recipe slug found -- new content written as `.proposed.md` for manual diff | generate_recipes |
-</error_codes>
-
-<success_criteria>
-- [ ] `.workflow/specs/` directory created
-- [ ] Core spec files always created: `coding-conventions.md`, `architecture-constraints.md`, `learnings.md`
-- [ ] Optional spec files created when detected: `quality-rules.md` (linter/CI), `test-conventions.md` (test framework), `ui-conventions.md` (frontend framework). `debug-notes.md` / `review-standards.md` deferred (on demand via `/spec-add`).
-- [ ] Workflow recipe knowhow created in `.workflow/knowhow/` for each detected operational workflow (test / debug / build / dev / lint). Each recipe matches the `recipe` schema in `~/.maestro/workflows/knowhow.md` Part B and contains at least one runnable command.
-- [ ] Report displayed grouped by destination (specs / recipes / skipped / deferred), with `.proposed.md` files surfaced when an existing recipe slug was preserved.
-</success_criteria>
-</output>
+---
+name: spec-setup
+description: Initialize specs from project structure
+argument-hint: ""
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+---
+<purpose>
+Initialize `.workflow/specs/` by scanning codebase for conventions. Core files always created; optional files created when signals detected. Also generates recipe knowhow for detected workflows.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/specs-setup.md
+</required_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 |
+| W002 | warning | Workflow recipe signals detected but commands ambiguous -- recipe skipped | generate_recipes |
+| W003 | warning | Existing recipe slug found -- new content written as `.proposed.md` for manual diff | generate_recipes |
+</error_codes>
+
+<success_criteria>
+- [ ] `.workflow/specs/` directory created
+- [ ] Core spec files always created: `coding-conventions.md`, `architecture-constraints.md`, `learnings.md`
+- [ ] Optional spec files created when detected: `quality-rules.md` (linter/CI), `test-conventions.md` (test framework), `ui-conventions.md` (frontend framework). `debug-notes.md` / `review-standards.md` deferred (on demand via `/spec-add`).
+- [ ] Workflow recipe knowhow created in `.workflow/knowhow/` for each detected operational workflow (test / debug / build / dev / lint). Each recipe matches the `recipe` schema in `~/.maestro/workflows/knowhow.md` Part B and contains at least one runnable command.
+- [ ] Report displayed grouped by destination (specs / recipes / skipped / deferred), with `.proposed.md` files surfaced when an existing recipe slug was preserved.
+</success_criteria>
+</output>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maestro-flow-one",
-  "version": "0.2.34",
+  "version": "0.2.35",
   "description": "All Maestro workflow commands as a single Claude Code skill — intent routing, decision gates, minimal closed-loop chains",
   "bin": {
     "maestro-flow": "bin/maestro-flow.js"