maestro-flow-one 0.2.0 → 0.2.2

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

@@ -0,0 +1,107 @@
+---
+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
+- [ ] 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

@@ -0,0 +1,49 @@
+---
+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/maestro-flow/commands/spec/load.md

@@ -0,0 +1,51 @@
+---
+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/maestro-flow/commands/spec/remove.md

@@ -0,0 +1,51 @@
+---
+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/maestro-flow/commands/spec/setup.md

@@ -0,0 +1,51 @@
+---
+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>

package/maestro-flow/commands/wiki/connect.md

@@ -0,0 +1,62 @@
+---
+name: wiki-connect
+description: Find and link hidden connections in wiki graph
+argument-hint: "[--scope <type>] [--min-similarity N] [--fix] [--max N]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<required_reading>
+@~/.maestro/workflows/wiki-connect.md
+</required_reading>
+
+<purpose>
+Knowledge graph link discovery and health improvement. Analyzes the wiki index to find orphaned entries, missing connections, and transitive link gaps, then suggests or auto-applies new `related` links to improve graph connectivity.
+
+Leverages maestro's unique wiki graph infrastructure (BM25 search, backlinks, health scoring) — no equivalent in gstack. Directly improves the quality of all downstream wiki consumers (search, digest, follow-along).
+</purpose>
+
+<context>
+Arguments: $ARGUMENTS
+
+Flags, storage paths, and CLI commands defined in workflow wiki-connect.md.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/wiki-connect.md' completely (Stages 1-6).
+
+**Next-step routing:**
+- Generate knowledge digest → `/wiki-digest <topic>`
+- Follow-along on orphan → `/learn-follow <wiki-id>`
+- View full graph → `maestro wiki graph`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No wiki entries found (empty index) | Initialize wiki content first, or run `/maestro-init` |
+| E002 | error | `maestro wiki` CLI not available | Check maestro installation |
+| W001 | warning | No connection candidates found above threshold | Lower --min-similarity or check if graph is already well-connected |
+| W002 | warning | Some wiki update calls failed during --fix | Partial application; retry failed entries manually |
+| W003 | warning | Health score unchanged after fix | Connections may not have improved the specific health metrics |
+</error_codes>
+
+<success_criteria>
+- [ ] Wiki index loaded with entry count and type distribution
+- [ ] Baseline health score recorded
+- [ ] Orphans identified and rescue candidates generated
+- [ ] Connection candidates scored and ranked
+- [ ] Results filtered by --min-similarity and limited by --max
+- [ ] Suggestions displayed with scores and reasons
+- [ ] If --fix: entries updated with new `related` links
+- [ ] If --fix: new health score computed and delta reported
+- [ ] Report written to `wiki-connections-{date}.md`
+- [ ] Graph insights appended to `lessons.jsonl`
+- [ ] No unintended entry modifications (only `related` field changed)
+- [ ] Summary displayed with next-step routing
+</success_criteria>

package/maestro-flow/commands/wiki/digest.md

@@ -0,0 +1,69 @@
+---
+name: wiki-digest
+description: Generate wiki digest with theme clustering and gap analysis
+argument-hint: "[<topic>|--recent N] [--type <type>] [--format brief|full]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Knowledge synthesis command that generates actionable digests from the wiki knowledge graph. Clusters entries by semantic theme, identifies knowledge gaps, and produces a coverage heatmap. Unique to maestro — leverages the wiki graph (BM25 search, backlinks, health) to surface trends and missing knowledge.
+
+Unlike `maestro wiki list` which shows raw entries, this command synthesizes and interprets the knowledge base, producing a curated summary with gap analysis and recommended next actions.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/wiki-digest.md
+</required_reading>
+
+<deferred_reading>
+- @~/.maestro/workflows/issue.md (issues.jsonl canonical schema for `--create-issues` routing)
+</deferred_reading>
+
+<context>
+Arguments: $ARGUMENTS
+
+Flags, scope resolution, storage paths, and CLI commands defined in workflow wiki-digest.md.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/wiki-digest.md' completely (Stages 1-8).
+
+**Next-step routing:**
+- Deep dive on a theme → `/learn-follow <wiki-id>`
+- Fix graph gaps → `/wiki-connect --fix`
+- Decompose code for missing patterns → `/learn-decompose <path>`
+- Create missing entries → `maestro wiki create --type <type> --slug <slug>`
+- Triage gap issues → `/manage-issue list --source wiki-digest`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No wiki entries found (empty index) | Initialize wiki content first |
+| E002 | error | Topic search returned 0 results | Broaden topic or check wiki content |
+| W001 | warning | Too few entries (<5) for meaningful theme clustering | Digest produced but themes may be trivial |
+| W002 | warning | lessons.jsonl not found — skipping cross-reference | Proceed without lesson context |
+| W003 | warning | Some entry bodies failed to load — partial summaries | Note incomplete entries in digest |
+</error_codes>
+
+<success_criteria>
+- [ ] Scope parsed and entries loaded
+- [ ] Baseline health score recorded
+- [ ] Entries clustered into 3-5 semantic themes
+- [ ] Per-theme analysis: summary, key entries, gaps, health
+- [ ] Cross-reference with lessons.jsonl completed
+- [ ] Coverage heatmap generated (type × theme matrix)
+- [ ] Knowledge gaps identified with suggested actions
+- [ ] If `--create-issues`: gap issues created in `issues.jsonl` (deduped)
+- [ ] Digest written to `digest-{slug}-{date}.md`
+- [ ] Meta-insights appended to `lessons.jsonl`
+- [ ] `learning-index.json` updated
+- [ ] No files modified outside `.workflow/learning/` and `.workflow/issues/` (issues only when `--create-issues`)
+- [ ] Summary displayed with key findings and next-step routing
+</success_criteria>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maestro-flow-one",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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"