maestro-flow 0.3.45 → 0.3.47

package/.claude/commands/maestro.md

@@ -14,108 +14,178 @@ allowed-tools:
   - TodoWrite
 ---
 <purpose>
-Orchestrate all maestro commands automatically based on user intent and current project state.
-Two routing modes:
-1. **Intent-based**: User describes a goal → classify task type → select/compose command chain → confirm → execute
-2. **State-based**: Read .workflow/state.json → determine next logical step → suggest/execute (triggered by `continue`/`next`)
+Orchestrate all maestro commands based on user intent and project state.
+Classify intent → select chain → create session → dispatch to `maestro-ralph-execute`.
 
-Per-step type selection (default: auto):
-- **skill**: Execute via Skill() in current session — output visible in conversation, synchronous, user can intervene
-- **cli**: Heavy execution steps via CLI delegate — context isolation, template-driven prompts
+Entry points:
+- **`/maestro "intent"`** — Intent-based: classify → chain → execute
+- **`/maestro -c`** — Resume previous session
+- **`/maestro --dry-run "intent"`** — Show chain, no execution
+- **`/maestro --super "intent"`** — Production-ready mode (read maestro-super.md)
 
-Produces session directory at `.workflow/.maestro/{session_id}/` with status.json tracking chain progress.
-Dispatches to unified executor (`maestro-ralph-execute`) for sequential step execution with artifact propagation.
+Session: `.workflow/.maestro/{session_id}/status.json`
 </purpose>
 
 <deferred_reading>
-- [maestro.md](~/.maestro/workflows/maestro.md) — read at execution start (Steps 1-3: intent analysis, chain selection, session setup; Step 4 dispatches to unified executor)
-- [maestro-super.md](~/.maestro/workflows/maestro-super.md) — read when `--super` flag is active
+- [maestro.md](~/.maestro/workflows/maestro.md) — read at execution start for intent analysis + chain selection
+- [maestro-super.md](~/.maestro/workflows/maestro-super.md) — read when `--super` flag active
 </deferred_reading>
 
 <context>
 $ARGUMENTS — user intent text, or special keywords.
 
-**Special keywords:**
-- `continue` / `next` / `go` — State-based routing: read state.json, determine next step, execute
-- `status` — Shortcut to Skill({ skill: "manage-status" })
+**Keywords:** `continue`/`next`/`go` → state-based routing; `status` → `Skill("manage-status")`
 
 **Flags:**
-- `-y` / `--yes` — Auto mode: skip clarification, skip confirmation, auto-skip on errors. Propagates to downstream commands that support it.
-- `-c` / `--continue` — Resume previous coordinator session from `.workflow/.maestro/*/status.json`
-- `--dry-run` — Show planned chain without executing
-- `--exec <mode>` — Execution engine: `auto` (default), `cli`, `internal`. `internal` = Skill() in current session; `cli` = delegate to external CLI. Auto selects per step based on command complexity.
-- `--tool <name>` — CLI tool for delegate execution (default: claude). Only used when engine=cli.
-- `--super` — Super mode: deliver production-ready complete software system. See Super Mode section below.
-
-**State files read:**
-- `.workflow/state.json` — project state machine + artifact registry
-- `.workflow/roadmap.md` — milestone/phase structure
-- `.workflow/scratch/*/plan.json` — plan metadata (via artifact registry paths)
+- `-y` / `--yes` — Auto mode: skip clarification, skip confirmation, auto-skip on errors
+- `-c` / `--continue` — Resume previous session
+- `--dry-run` — Show chain without executing
+- `--exec <mode>` — `auto` (default), `cli`, `internal`
+- `--tool <name>` — CLI tool for delegates (default: claude)
+- `--super` — Read and follow `maestro-super.md`
 </context>
 
-<execution>
-**Resume mode (`-c`):** Skip selection workflow entirely — scan `.workflow/.maestro/` for latest session, then `Skill({ skill: "maestro-ralph-execute" })`. The unified executor discovers the running session and resumes from the next pending step. **End.**
+<invariants>
+1. **All chains dispatch via maestro-ralph-execute** — maestro never executes steps directly
+2. **Session before execution** — status.json created before any step runs
+3. **Auto flags only to supporting commands** — unlisted commands execute as-is
+</invariants>
 
-**Normal mode:** Read `~/.maestro/workflows/maestro.md` from deferred_reading, then follow it completely.
+<state_machine>
 
-**Auto mode (`-y`) propagation:**
+<states>
+S_PARSE         — 解析参数、检测 flags                PERSIST: —
+S_RESUME        — 扫描已有 session、恢复执行           PERSIST: —
+S_CLASSIFY      — 意图分类、chain 选择                 PERSIST: —
+S_CREATE        — 创建 session + status.json           PERSIST: session (全量)
+S_DRY_RUN       — 显示 chain 后结束                    PERSIST: —
+S_CONFIRM       — 用户确认（auto_mode 跳过）            PERSIST: —
+S_DISPATCH      — 移交 maestro-ralph-execute           PERSIST: —
+S_FALLBACK      — 意图无法分类、请求输入                PERSIST: —
+</states>
 
-When `-y` is active, maestro propagates auto flags to downstream commands. Only commands that explicitly support auto mode receive the flag — others execute normally (no forced flags).
+<transitions>
+
+S_PARSE:
+  → S_RESUME      WHEN: -c / --continue flag
+  → S_CLASSIFY    WHEN: intent text present
+  → S_CLASSIFY    WHEN: keyword "continue"/"next"/"go"    DO: A_STATE_BASED_ROUTE
+  → S_FALLBACK    WHEN: no intent AND no flags
+
+S_RESUME:
+  → S_DISPATCH    WHEN: session found                     DO: A_LOCATE_SESSION
+  → S_FALLBACK    WHEN: no session found
+
+S_CLASSIFY:
+  → S_CREATE      WHEN: chain resolved                    DO: A_CLASSIFY_INTENT
+  → S_FALLBACK    WHEN: no match AND auto_mode
+  → S_CLASSIFY    WHEN: no match AND not auto_mode        DO: A_CLARIFY
+                   GUARD: max 2 clarification rounds → S_FALLBACK
+
+S_CREATE:
+  → S_DRY_RUN     WHEN: --dry-run flag                    DO: A_CREATE_SESSION
+  → S_CONFIRM     WHEN: not auto_mode                     DO: A_CREATE_SESSION
+  → S_DISPATCH    WHEN: auto_mode                         DO: A_CREATE_SESSION
+
+S_DRY_RUN:
+  → END           DO: display chain with step types
+
+S_CONFIRM:
+  → S_DISPATCH    WHEN: user confirms
+  → S_PARSE       WHEN: user wants to modify
+  → END           WHEN: user cancels
+
+S_DISPATCH:
+  → END           DO: Skill({ skill: "maestro-ralph-execute" })
+
+S_FALLBACK:
+  → S_CLASSIFY    WHEN: user provides new intent           DO: AskUserQuestion
+  → END           WHEN: user cancels
+
+</transitions>
+
+<actions>
+
+### A_STATE_BASED_ROUTE
+
+1. Read `.workflow/state.json` → determine next logical step
+2. Convert to equivalent intent for chain classification
+
+### A_LOCATE_SESSION
+
+1. Scan `.workflow/.maestro/*/status.json`, filter `status == "running"`, sort DESC
+2. Take most recent; if not found → S_FALLBACK
+
+### A_CLASSIFY_INTENT
+
+1. Read `~/.maestro/workflows/maestro.md` from deferred_reading
+2. Classify intent via keyword heuristics + detectTaskType/detectNextAction
+3. Select/compose command chain from chainMap
+4. Determine per-step type: `internal` (Skill) or `external` (delegate)
+
+### A_CLARIFY
+
+1. `AskUserQuestion` with parsed intent + available chain options
+2. Re-classify with user response
+
+### A_CREATE_SESSION
+
+1. Read `.workflow/state.json` for project context (phase, milestone)
+2. Create `.workflow/.maestro/maestro-{YYYYMMDD-HHMMSS}/status.json`:
+   ```json
+   { "session_id", "source": "maestro", "intent", "task_type", "chain_name",
+     "phase", "milestone", "auto_mode", "exec_mode", "cli_tool",
+     "context": { ... }, "steps": [{ "index", "skill", "args", "type", "status": "pending" }],
+     "waves": [], "current_step": 0, "status": "running" }
+   ```
+3. Initialize tracking: `create_goal`, `update_plan`
+4. If `--super`: read `maestro-super.md`, follow it completely
+
+</actions>
+
+</state_machine>
+
+<appendix>
+
+### Auto-Yes Flag Map
 
 | Command | Auto Flag | Effect |
 |---------|-----------|--------|
 | maestro-init | `-y` | Skip interactive questioning |
-| maestro-analyze | `-y` | Skip interactive scoping, auto-deepen |
-| maestro-brainstorm | `-y` | Skip interactive questions, use defaults |
-| maestro-roadmap | `-y` | Skip interactive questions, use defaults (create/revise/review) |
-| maestro-ui-design | `-y` | Skip interactive selection, pick top variant |
+| maestro-analyze | `-y` | Skip scoping, auto-deepen |
+| maestro-brainstorm | `-y` | Skip questions, use defaults |
+| maestro-roadmap | `-y` | Skip questions (create/revise/review) |
+| maestro-ui-design | `-y` | Skip selection, pick top variant |
 | maestro-plan | `-y` | Skip confirmations and clarification |
 | maestro-execute | `-y` | Skip confirmations, blocked auto-continue |
-| maestro-verify | *(none)* | No interactive prompts |
 | quality-auto-test | `-y` | Skip plan confirmation |
-| quality-review | *(none)* | No interactive prompts, auto-detects level |
-| quality-test | `-y --auto-fix` | Auto-trigger gap-fix loop on failures |
-| quality-debug | *(none)* | No interactive prompts |
-| quality-retrospective | `-y` | Accept all routing recommendations without prompting |
-| maestro-milestone-audit | *(none)* | No interactive prompts |
-| maestro-milestone-complete | `-y` | Skip knowledge promotion inquiry |
-| manage-learn | *(none)* | No interactive prompts |
+| quality-test | `-y --auto-fix` | Auto-trigger gap-fix loop |
+| quality-retrospective | `-y` | Accept all routing recommendations |
+| maestro-milestone-complete | `-y` | Skip knowledge promotion |
 
-Commands not listed (manage-*, spec-*, milestone-*) have no auto flags and execute as-is.
+Unlisted commands have no auto flags.
 
-In auto mode, maestro also:
-- Skips intent clarification (workflow Step 2d)
-- Skips chain confirmation (workflow Step 3d)
-- Auto-skips on step errors (retry once, then skip and continue)
+### Error Codes
 
-**Super mode (`--super`):** Read `maestro-super.md` from deferred_reading, then follow it completely.
-</execution>
-
-<error_codes>
 | Code | Severity | Description | Recovery |
 |------|----------|-------------|----------|
-| E001 | error | No intent and project not initialized | Prompt for intent or suggest maestro-init |
-| E002 | error | Clarity too low after 2 clarification rounds | Show parsed intent, ask user to rephrase |
-| E003 | error | Chain step failed + user chose abort | Record partial progress, suggest resume with -c |
+| E001 | error | No intent and project not initialized | Prompt or suggest maestro-init |
+| E002 | error | Clarity too low after 2 rounds | Show parsed intent, ask rephrase |
+| E003 | error | Chain step failed + user abort | Record partial, suggest -c resume |
 | E004 | error | Resume session not found | Show available sessions |
-| W001 | warning | Intent ambiguous, multiple chains possible | Present options, let user choose |
-| W002 | warning | Chain step completed with warnings | Log and continue |
-| W003 | warning | State suggests different chain than intent | Show discrepancy, let user decide |
-</error_codes>
+| W001 | warning | Ambiguous intent, multiple chains | Present options |
+| W002 | warning | Step completed with warnings | Log and continue |
+| W003 | warning | State suggests different chain | Show discrepancy |
+
+### Success Criteria
 
-<success_criteria>
 - [ ] Intent classified with task_type, complexity, clarity_score
-- [ ] Project state read and incorporated into routing
-- [ ] Command chain selected and confirmed (or auto-confirmed with -y)
-- [ ] Per-step type selected (auto routes heavy steps to "cli", observable steps to "skill")
-- [ ] Auto flags correctly propagated to supporting commands only
-- [ ] Session directory created at .workflow/.maestro/{session_id}/
-- [ ] status.json created with unified schema (source: "maestro", steps[] with type field)
+- [ ] Chain selected and confirmed (or auto-confirmed)
+- [ ] Session dir created with status.json before execution
+- [ ] Auto flags propagated to supporting commands only
+- [ ] All chains dispatched via maestro-ralph-execute
 - [ ] Low-complexity intents routed to maestro-quick
-- [ ] All chains dispatched via unified executor (maestro-ralph-execute) with status.json tracking
-- [ ] Phase numbers auto-detected and passed to downstream commands
-- [ ] (super mode) Requirements expanded and validated via CLI delegate before roadmap creation
-- [ ] (super mode) Each milestone scored ≥ 80% before advancing
-- [ ] (super mode) All milestones completed with no user intervention
-- [ ] (super mode) Final system builds, starts, and passes all tests
-</success_criteria>
+- [ ] (super) Requirements validated before roadmap
+- [ ] (super) Each milestone scored >= 80%
+
+</appendix>

package/.claude/commands/manage-knowhow-capture.md

@@ -13,8 +13,7 @@ allowed-tools:
 ---
 <purpose>
 Capture reusable knowledge into `.workflow/knowhow/` with type-specific structured fields.
-Six content types, each optimized for a different reuse pattern. All entries are automatically
-indexed by WikiIndexer (type=knowhow) and searchable via `maestro knowhow search`.
+Auto-indexed by WikiIndexer (type=knowhow), searchable via `maestro knowhow search`.
 </purpose>
 
 <required_reading>
@@ -22,172 +21,57 @@ indexed by WikiIndexer (type=knowhow) and searchable via `maestro knowhow search
 </required_reading>
 
 <context>
-Arguments: $ARGUMENTS
-
-**Types:**
-
-| Type | Prefix | Use Case | Key Fields |
-|------|--------|----------|------------|
-| `compact` | KNW- | Session state recovery | objective, files, decisions, plan, pending |
-| `template` | TPL- | Code/config templates | language, code block, usage context |
-| `recipe` | RCP- | Step-by-step how-to | prerequisites, steps, expected outcome |
-| `reference` | REF- | External doc / API quick-ref | source URL, key points, scenarios |
-| `decision` | DCS- | Design decision record | context, alternatives, rationale, consequences |
-| `tip` | TIP- | Quick note / reminder | content, tags |
-
-No arguments: auto-detect type or ask user via AskUserQuestion.
-
-**Flags:**
-- `--lang <lang>` — Language for templates (typescript, python, bash, yaml, etc.)
-- `--source <url>` — Source URL for references
-- `--tag tag1,tag2` — Categorization tags
-- `--title <title>` — Explicit title (auto-generated if omitted)
+$ARGUMENTS — type token + description + optional flags.
+
+**Flags**: `--lang <lang>`, `--source <url>`, `--tag tag1,tag2`, `--title <title>`, `--asset-type <type>`, `--code-paths <paths>`, `--category <cat>`
+
+**Type routing** (first token match):
+
+| Token | Type | Prefix | Key fields |
+|-------|------|--------|------------|
+| `compact`/`session`/`压缩`/`保存` | compact | KNW- | objective, files, decisions, plan, pending |
+| `template`/`tpl`/`模板` | template | TPL- | language, code block, usage, parameters |
+| `recipe`/`rcp`/`配方`/`步骤` | recipe | RCP- | prerequisites, steps, expected outcome, pitfalls |
+| `reference`/`ref`/`参考`/`引用` | reference | REF- | source URL, key points, scenarios, examples |
+| `decision`/`dcs`/`决策`/`adr` | decision | DCS- | context, alternatives table, rationale, consequences |
+| `tip`/`note`/`记录`/`快速` | tip | TIP- | content, tags |
+| `asset`/`ast`/`资产`/`契约` | asset | AST- | assetType, codePaths, category |
+| `blueprint`/`blp`/`蓝图` | blueprint | BLP- | codePaths, category |
+| `document`/`doc`/`文档` | document | DOC- | (general fallback) |
+| Short text + `--tag` | tip | TIP- | — |
+| No args | — | — | AskUserQuestion (9 options) |
+
+**Output**: `.workflow/knowhow/{PREFIX}-{YYYYMMDD}-{HHMM}.md` with YAML frontmatter (title, type, category, created, tags, source, lang, status)
 </context>
 
 <execution>
-
-### Step 1: Detect Type
-
-Parse first token as type. If ambiguous, AskUserQuestion with options:
-
-| Token Match | Type |
-|-------------|------|
-| `compact`, `session`, `压缩`, `保存` | compact |
-| `template`, `tpl`, `模板` | template |
-| `recipe`, `rcp`, `配方`, `步骤` | recipe |
-| `reference`, `ref`, `参考`, `引用` | reference |
-| `decision`, `dcs`, `决策`, `adr` | decision |
-| `tip`, `note`, `记录`, `快速` | tip |
-| No match, short text, `--tag` present | tip |
-| No arguments | AskUserQuestion (6 options) |
-
-### Step 2: Generate Content by Type
-
-#### compact (KNW-{YYYYMMDD}-{HHMM}.md)
-
-Extract from conversation history:
-- **Session ID** — WFS-* if workflow session active, else `manual-{date}`
-- **Project Root** — Absolute path
-- **Objective** — High-level goal
-- **Execution Plan** — Source + complete verbatim content (never summarize)
-- **Working Files** — Modified files with roles (absolute paths, 3-8 files)
-- **Reference Files** — Read-only context files
-- **Last Action** — Final action + result
-- **Decisions** — Table: decision | reasoning
-- **Constraints** — User-specified limitations
-- **Dependencies** — Added/changed packages
-- **Known Issues** — Deferred bugs
-- **Changes Made** — Completed modifications
-- **Pending** — Next steps
-- **Notes** — Unstructured thoughts
-
-Plan detection priority: workflow session IMPL_PLAN.md > TodoWrite items > user-stated > inferred.
-
-#### template (TPL-{YYYYMMDD}-{HHMM}.md)
-
-Ask for or extract:
-- **Language / Tech** — `--lang` flag or inferred from context
-- **Usage** — When/how to use this template
-- **Code** — The template content (ask user to provide or select from conversation)
-- **Parameters** — Placeholders to replace (e.g. `{{name}}`, `{{port}}`)
-- **Dependencies** — Required packages/config
-- **Tags** — From `--tag` flag
-
-If code not provided explicitly, prompt user: "Paste the template code:"
-
-#### recipe (RCP-{YYYYMMDD}-{HHMM}.md)
-
-Ask for or extract:
-- **Goal** — What this recipe accomplishes
-- **Prerequisites** — Tools, access, config needed
-- **Steps** — Numbered step-by-step instructions
-- **Expected Outcome** — What success looks like
-- **Common Pitfalls** — Known issues / gotchas
-- **Related** — Links to templates, references, decisions used
-- **Tags** — From `--tag` flag
-
-If steps not clear, prompt user: "Describe the steps (numbered list):"
-
-#### reference (REF-{YYYYMMDD}-{HHMM}.md)
-
-Ask for or extract:
-- **Source** — `--source` flag (URL, doc title, API endpoint)
-- **Key Points** — Bullet list of essential info
-- **Applicable Scenarios** — When to consult this reference
-- **Quick Examples** — Copy-paste ready code snippets
-- **Last Verified** — Date (today)
-- **Tags** — From `--tag` flag
-
-If `--source` provided, offer to fetch and summarize via WebFetch.
-
-#### decision (DCS-{YYYYMMDD}-{HHMM}.md)
-
-Ask for or extract:
-- **Context** — Background and problem statement
-- **Decision** — What was decided
-- **Alternatives Considered** — Table: alternative | pros | cons | rejected because
-- **Rationale** — Why this choice over alternatives
-- **Consequences** — Positive and negative impact
-- **Related** — Links to affected specs, recipes, templates
-- **Date** — Decision date
-- **Status** — proposed | accepted | superseded
-
-#### tip (TIP-{YYYYMMDD}-{HHMM}.md)
-
-Simple note:
-- **Content** — Everything after type token (or full $ARGUMENTS)
-- **Context** — Auto-detected from recent conversation files
-- **Tags** — From `--tag` flag
-- **Timestamp** — ISO format
-
-### Step 3: Write File
-
-Write to `.workflow/knowhow/{PREFIX}-{YYYYMMDD}-{HHMM}.md` with YAML frontmatter:
-
-```yaml
----
-title: {auto or --title}
-type: {type}
-category: {type}
-created: {ISO timestamp}
-tags: [{tags}]
-source: {url if reference}
-lang: {language if template}
-status: {status if decision}
----
-{markdown body}
-```
-
-### Step 4: Confirm
-
-```
-=== KNOWHOW CAPTURED ===
-Type: {type}
-ID:   knowhow-{slug}
-File: .workflow/knowhow/{filename}
-
-{type-specific summary line}
-```
+Follow '~/.maestro/workflows/knowhow.md' completely.
+
+**Type-specific content rules**:
+
+| Type | Content extraction |
+|------|-------------------|
+| compact | Extract from conversation: session ID, objective, execution plan (verbatim), working files (3-8), decisions, constraints, pending. Plan priority: workflow IMPL_PLAN.md > TodoWrite > user-stated > inferred. |
+| template | Ask for: language, code block, parameters (placeholders), usage context, dependencies |
+| recipe | Ask for: goal, prerequisites, numbered steps, expected outcome, common pitfalls |
+| reference | From --source URL or ask. Key points, applicable scenarios, quick examples. Offer WebFetch if URL provided. |
+| decision | Context, alternatives (table: alt/pros/cons/rejected-because), rationale, consequences. Status: proposed/accepted/superseded. |
+| tip | Content = everything after type token. Auto-detect context from recent files. |
+| asset | assetType (api-contract/data-model/prompt/config), codePaths, category for agent discovery |
+| blueprint | Architecture design with codePaths and category |
 </execution>
 
 <error_codes>
-| Code | Severity | Description | Stage |
-|------|----------|-------------|-------|
-| E001 | error | `.workflow/` not initialized — run `/maestro-init` first | validate |
-| E002 | error | Template: no code provided after prompt | template |
-| E003 | error | Recipe: no steps provided after prompt | recipe |
-| W001 | warning | No active workflow session — compact captures conversation only | compact |
-| W002 | warning | Plan detection found no explicit plan — using inferred plan | compact |
-| W003 | warning | `--source` URL could not be fetched — proceeding with manual entry | reference |
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| E002 | Template: no code provided after prompt | Ask again or cancel |
+| E003 | Recipe: no steps provided after prompt | Ask again or cancel |
+| W001 | No active workflow session (compact) | Captures conversation only |
+| W002 | Plan detection found no explicit plan (compact) | Uses inferred plan |
 </error_codes>
 
 <success_criteria>
-- [ ] Type correctly detected or selected
-- [ ] All type-specific fields populated (not empty)
-- [ ] YAML frontmatter written with correct fields
-- [ ] Markdown body follows type structure
-- [ ] File written to `.workflow/knowhow/` with correct prefix
-- [ ] Auto-indexed by WikiIndexer (type=knowhow)
-- [ ] Confirmation displayed with ID, type, file path
-- [ ] Next step hint appropriate to type shown
+- [ ] Type detected or selected, all type-specific fields populated
+- [ ] File written to .workflow/knowhow/ with correct prefix and YAML frontmatter
+- [ ] Confirmation displayed with ID, type, path
 </success_criteria>

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

@@ -50,6 +50,15 @@ Phase or task: $ARGUMENTS (required — phase number)
 | 5 | Default | code | quality-integration-test |
 
 Flags, artifact context resolution, and output formats defined in workflow auto-test.md.
+
+### Pre-load context (before test generation)
+
+1. **Test specs + tools**: Run `maestro spec load --category test` to load test conventions (framework, patterns, naming). Apply to all generated tests.
+2. **Coding specs**: Run `maestro spec load --category coding` to understand coding patterns for accurate test targeting.
+3. **Role Knowledge**:
+   - Browse: `maestro wiki list --category test`
+   - Load task-relevant entries: `maestro wiki load <id1> [id2...]`
+4. All are optional — proceed without if unavailable.
 </context>
 
 <execution>

package/.claude/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/.claude/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/.claude/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/.claude/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/.claude/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/.claude/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:**