maestro-flow-one 0.2.4 → 0.2.6

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

@@ -43,19 +43,11 @@ Each artifact's type determines its outputs at `.workflow/{a.path}/`:
 
 Extract conclusions from related artifacts that may affect this debug session — review findings guide investigation direction, prior debug avoids redundant work.
 
-### Pre-load context (before hypothesis formation)
-
-1. **Codebase docs**: If `.workflow/codebase/ARCHITECTURE.md` exists, load module boundaries to scope impact analysis and inform hypothesis formation.
-2. **Wiki prior knowledge**: Run `maestro wiki search "<symptom keywords>" --json 2>/dev/null`. If results found, check for prior investigations on similar issues to avoid re-investigation.
-3. Both are optional — proceed without if unavailable.
-
-### Role Knowledge
-1. Browse accumulated knowledge for this role:
-   `maestro wiki list --category debug`
-2. Analyze the index, identify entries relevant to the current task
-3. Load selected documents:
-   `maestro wiki load <id1> [id2] [id3...]`
-4. Review loaded knowledge before proceeding
+### Pre-load (optional, proceed without)
+- Codebase docs: `.workflow/codebase/ARCHITECTURE.md` → module boundaries
+- Wiki: `maestro wiki search "<symptom keywords>" --json` → prior investigations
+- Specs: `maestro spec load --category debug --keyword "<symptom>"` → known issues/workarounds
+- Role knowledge: `maestro wiki list --category debug` → select relevant → `maestro wiki load`
 
 **Output**: `DEBUG_DIR = .workflow/scratch/{YYYYMMDD}-debug-P{N}-{slug}/` (P{N} = phase number when phase-scoped; omit for standalone). Output directory rules defined in workflow debug.md Step 4.
 </context>
@@ -83,18 +75,13 @@ Append to state.json.artifacts[]:
 
 ### Post-debug Knowledge Inquiry
 
-After root cause is confirmed, evaluate inquiry triggers:
-
-1. **Recurring pattern**: If root cause matches a recurring pattern (similar to prior debug sessions):
-   → Ask: "This root cause pattern has appeared before. Should it be documented in `debug-notes.md` to prevent recurrence? (`/spec-add debug`)"
-
-2. **Non-obvious fix**: If fix involved a non-obvious approach or workaround:
-   → Ask: "This fix used a non-obvious strategy. Should it be recorded as a learning? (`/spec-add learning`)"
-
-3. **Architectural gap**: If root cause traces to architectural boundary violation or missing constraint:
-   → Ask: "Root cause points to an architectural gap. Should `architecture-constraints.md` be updated? (`/spec-add arch`)"
+| Condition | Ask | Route |
+|-----------|-----|-------|
+| Recurring root cause pattern (seen in prior debug) | "Document in debug-notes.md?" | spec-add debug |
+| Non-obvious fix / workaround | "Record as learning?" | spec-add learning |
+| Root cause = architectural boundary violation | "Update architecture-constraints.md?" | spec-add arch |
 
-If user confirms, invoke `Skill({ skill: "spec-add", args: "<category> <content>" })`.
+On confirm → `Skill("spec-add", "<category> <content>")`.
 
 **Next-step routing on completion:**
 - Root cause found, fix needed → `/maestro-plan {phase} --gaps`

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

@@ -27,6 +27,15 @@ Scope: $ARGUMENTS (required)
 - "all" - full codebase scan
 
 If not provided, prompt user for scope.
+
+### Pre-load context (before refactoring)
+
+1. **Coding specs**: Run `maestro spec load --category coding` to load coding conventions. Apply conventions to all refactored code.
+2. **Review specs**: Run `maestro spec load --category review` to load review standards. Use as quality gate for refactored code.
+3. **Role Knowledge**:
+   - Browse: `maestro wiki list --category coding`
+   - Identify task-relevant entries, then load: `maestro wiki load <id1> [id2...]`
+4. All are optional — proceed without if unavailable.
 </context>
 
 <execution>

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

@@ -48,19 +48,11 @@ Each artifact's type determines its outputs at `.workflow/{a.path}/`:
 
 Extract conclusions from related artifacts that may affect this review. Pass as prior quality context to reviewer agents — avoid redundant work, focus on gaps and regressions.
 
-### Pre-load context (before dispatching reviewer agents)
-
-1. **Codebase docs**: If `.workflow/codebase/ARCHITECTURE.md` exists, load component boundaries and layer rules. Pass as `codebase_context` to reviewer agents (especially architecture dimension).
-2. **Wiki constraints**: Run `maestro wiki search "architecture constraint" --json 2>/dev/null`. If results found, pass as `wiki_context` to reviewer agents for evaluating code against documented decisions.
-3. Both are optional — proceed without if unavailable.
-
-### Role Knowledge
-1. Browse accumulated knowledge for this role:
-   `maestro wiki list --category review`
-2. Analyze the index, identify entries relevant to the current task
-3. Load selected documents:
-   `maestro wiki load <id1> [id2] [id3...]`
-4. Review loaded knowledge before proceeding
+### Pre-load (optional, proceed without)
+- Codebase docs: `.workflow/codebase/ARCHITECTURE.md` → component boundaries, layer rules
+- Wiki constraints: `maestro wiki search "architecture constraint" --json` → documented decisions
+- Specs: `maestro spec load --category review` → review standards, checklists, knowhow tools
+- Role knowledge: `maestro wiki list --category review` → select relevant → `maestro wiki load`
 
 **Output**: `REVIEW_DIR = .workflow/scratch/{YYYYMMDD}-review-P{N}-{slug}/` (P{N} = phase number, enables directory-level identification as state.json fallback)
 </context>

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

@@ -40,6 +40,11 @@ Follow '~/.maestro/workflows/test.md' completely.
 
 **Command-specific extensions (not in workflow):**
 
+**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

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

@@ -50,7 +50,7 @@ Follow '~/.maestro/workflows/specs-add.md' completely.
 |------|----------|-------------|-------|
 | 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 | parse_input |
+| 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>

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

@@ -21,7 +21,7 @@ Category-based loading: loads the category's primary doc in full + matching entr
 $ARGUMENTS -- optional flags and keyword
 
 **Flags:**
-- `--category <category>` — Load by category: primary category doc (full) + cross-file entries with matching category attr. Categories: coding, arch, test, review, debug, quality, learning.
+- `--category <category>` — Load by category: primary category doc (full) + cross-file entries with matching category attr. Categories: coding, arch, test, review, debug, learning, ui.
 - `--keyword <word>` — Filter by keyword within entries
 
 **File → Primary Category mapping:**
@@ -32,7 +32,8 @@ $ARGUMENTS -- optional flags and keyword
 | test-conventions.md | test |
 | review-standards.md | review |
 | debug-notes.md | debug |
-| quality-rules.md | quality |
+| ui-conventions.md | ui |
+| quality-rules.md | review |
 | learnings.md | learning |
 
 **Examples:**

package/package.json

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

package/maestro-flow/commands/lifecycle/link-coordinate.md

@@ -1,71 +0,0 @@
----
-name: maestro-link-coordinate
-description: Execute command chain nodes step by step
-argument-hint: "\"intent text\" [--list] [-c [sessionId]] [--chain <name>] [--tool <tool>] [-y]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
----
-<purpose>
-Step-mode workflow coordinator using `maestro coordinate` CLI subcommands (start/next/status).
-Walks chain graphs node by node — each command node executed via `maestro delegate` internally.
-Decision/gate/eval nodes auto-resolve between steps. Session persisted for resume.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/maestro-link-coordinate.md
-</required_reading>
-
-<context>
-$ARGUMENTS — user intent text, or flags.
-
-**Flags:**
-- `--list` — List all available chain graphs
-- `-c` / `--continue [sessionId]` — Resume step_paused session via `coordinate next`
-- `--chain <name>` — Force a specific chain graph
-- `--tool <tool>` — CLI tool override (default: claude)
-- `-y` / `--yes` — Auto mode
-
-**CLI endpoints used:**
-- `maestro coordinate list` — enumerate chains
-- `maestro coordinate start "intent" --chain X` — begin step-mode session
-- `maestro coordinate next [sessionId]` — advance one step
-- `maestro coordinate status [sessionId]` — query state
-- `maestro coordinate run "intent"` — autonomous full run
-- `maestro coordinate watch <sessionId> [--follow]` — read-only event tail (separate from driver loop)
-- `maestro coordinate report` — agent-invoked command-node result writer (authoritative result channel)
-
-**Internal walker capabilities (invisible to driver loop):**
-- Prompt assembly owned by the walker (main flow) for both command and decision nodes
-- Decision nodes auto-resolve via `strategy: 'expr'` (fast path) with LLM decider fallback when expr has no match and no default edge, or explicit `strategy: 'llm'`
-- Walker events published to a file/SQLite broker for `watch` observers
-- LLM decision in step mode is synchronous — avoid tight per-step deadlines
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/maestro-link-coordinate.md' completely.
-</execution>
-
-<error_codes>
-| Code | Severity | Description | Recovery |
-|------|----------|-------------|----------|
-| E001 | error | No intent and no --list/--chain | Suggest --list |
-| E002 | error | Chain graph not found | Show list output |
-| E003 | error | Step execution failed | Check status, retry next |
-| E004 | error | Resume session not found | List sessions |
-| E005 | error | CLI endpoint unavailable | Check maestro installation |
-</error_codes>
-
-<success_criteria>
-- [ ] Chain graph loaded via `maestro coordinate start`
-- [ ] Each step executed via `maestro coordinate next` loop
-- [ ] JSON output parsed for session tracking
-- [ ] Decision nodes auto-resolved between steps
-- [ ] Session persisted and resumable via `-c`
-- [ ] Completion summary displayed
-</success_criteria>