maestro-flow 0.3.42 → 0.3.44

package/.claude/commands/maestro-ralph-execute.md

@@ -13,18 +13,9 @@ allowed-tools:
 ---
 <purpose>
 Single-step executor for ralph (adaptive) and maestro (static) sessions.
-Sessions stored at `.workflow/.maestro/*/status.json` with unified JSON schema.
+Sessions stored at `.workflow/.maestro/*/status.json`.
 
-Each invocation: find next pending step → execute → update status → hand off to next iteration.
-
-Three node types:
-- **decision** (ralph-only): `Skill("maestro-ralph")` — ralph re-evaluates, may expand chain
-- **internal**: `Skill({ skill, args })` — synchronous in-session → self-invoke next
-- **external**: `maestro delegate --to claude` → new Claude Code session executing `/{skill} {args}` → STOP → callback → self-invoke next
-
-Session sources:
-- **source: "ralph"** — Adaptive chain with decision nodes. Primary use case.
-- **source: "maestro"** — Static chain, internal/external only. No decision callbacks.
+Each invocation: locate session → find next pending step → resolve args → execute → update status → hand off to next iteration.
 
 Mutual invocation with `/maestro-ralph` forms a self-perpetuating work loop.
 </purpose>
@@ -39,15 +30,35 @@ Remaining  → session_id (if matches maestro-* or ralph-* pattern)
 ```
 
 Also read `session.auto_mode` from status.json — if `true`, treat as `-y` even without flag.
+
+**Session sources:**
+- **ralph** — Adaptive chain with decision nodes (primary)
+- **maestro** — Static chain, internal/external only, no decision callbacks
+
+**Node types:**
+
+| Type | Execution | Flow after |
+|------|-----------|------------|
+| decision (ralph-only) | `Skill("maestro-ralph")` — ralph re-evaluates, may expand chain | Ralph handles handoff, this execution ends |
+| internal | `Skill({ skill, args })` — synchronous in-session | Self-invoke next |
+| external | `maestro delegate --to claude` — new Claude Code session | STOP → callback → self-invoke next |
+
+**Auto flag map** (appended to skill args when auto mode is active):
+
+All lifecycle skills: `-y`. Exception: `quality-test` → `-y --auto-fix`.
+
+Fallback for unlisted skills: internal → no flag, external → `-y`.
+
+HARD RULE: External nodes ALWAYS append `-y` **to the skill's args inside the prompt** (not as a `maestro delegate` CLI argument), regardless of auto mode — delegate sessions are non-interactive and cannot confirm prompts.
 </context>
 
 <execution>
 
-## Step 1: Locate Session
+## Step 1: Locate Session + Find Next Step
 
 ```
-If $ARGUMENTS matches maestro-* or ralph-* pattern:
-  session_path = .workflow/.maestro/{$ARGUMENTS}/status.json
+If session_id provided (matches maestro-* or ralph-*):
+  session_path = .workflow/.maestro/{session_id}/status.json
 Else:
   Scan .workflow/.maestro/*/status.json
   Filter: status == "running"
@@ -61,16 +72,14 @@ If no session found:
 
 Read status.json → extract: `session_id`, `source`, `steps[]`, `current_step`, `status`, `phase`, `milestone`, `intent`, `auto_mode`, `context`, `cli_tool`.
 
-## Step 2: Find Next Pending Step
-
 ```
 next = steps.find(step => step.status == "pending")
-If no pending step → Step 6 (Complete)
+If no pending step → Step 5 (Complete Session)
 ```
 
-## Step 3: Resolve Args (context propagation)
+## Step 2: Resolve Args
 
-Before execution, enrich `next.args` with session context and prior outputs.
+Enrich `next.args` with session context before execution.
 
 **Placeholder substitution:**
 
@@ -109,8 +118,9 @@ For execute commands: find latest type=="plan" artifact → --dir .workflow/scra
 
 Write enriched args back to status.json (resume-safe).
 
-## Step 4: Mark Running
+## Step 3: Execute
 
+Mark step as running:
 ```
 next.status = "running"
 next.started_at = ISO timestamp
@@ -119,7 +129,7 @@ status.updated_at = ISO timestamp
 Write status.json
 ```
 
-Display step banner:
+Display banner:
 ```
 ------------------------------------------------------------
   [{next.index}/{steps.length - 1}] {next.skill} [{next.type}]
@@ -127,75 +137,40 @@ Display step banner:
   Session: {session_id} [{source}]
   Args: {next.args}
 ```
+If decision node: also show `Retry: {retry_count}/{max_retries}`.
 
-If decision node: also show `Retry: {retry_count}/{max_retries}` from parsed args.
-
-## Step 5: Execute by Type
-
-### 5a. decision node (ralph-only)
-
-Hand control back to ralph for re-evaluation.
+### decision node
 
 ```
 Skill({ skill: "maestro-ralph" })
 ```
 
-Ralph will: detect running decision → evaluate results → optionally expand steps[] → mark completed → call ralph-execute to resume.
-
-**After Skill("maestro-ralph") returns, this execution ends.** Ralph handles the handoff.
-
-### 5b. internal node
-
-HARD RULE: Every internal step MUST be executed via `Skill({ skill, args })`.
-Never "simulate" or "inline" a skill's work. If Skill() is not called, the step has NOT been executed.
+Ralph detects the running decision → evaluates → optionally expands steps[] → marks completed → calls ralph-execute. **This execution ends here — ralph handles the handoff.**
 
-**Auto flag propagation** (when `auto == true`):
+### internal node
 
-| Skill | Flag appended |
-|-------|---------------|
-| maestro-init | `-y` |
-| maestro-analyze | `-y` |
-| maestro-brainstorm | `-y` |
-| maestro-roadmap | `-y` |
-| maestro-ui-design | `-y` |
-| maestro-plan | `-y` |
-| maestro-execute | `-y` |
-| quality-auto-test | `-y` |
-| quality-test | `-y --auto-fix` |
-| quality-retrospective | `-y` |
-| maestro-milestone-complete | `-y` |
-| maestro-verify | `-y` |
-| quality-review | `-y` |
-| quality-debug | `-y` |
-| maestro-milestone-audit | `-y` |
+HARD RULE: Every step MUST be executed via `Skill({ skill, args })`. Never simulate or inline a skill's work.
 
 ```
-flag = auto_flag_map[next.skill] || ""
+flag = auto ? (auto_flag_map[next.skill] || "") : ""
 effective_args = flag ? `${next.args} ${flag}` : next.args
 
 Skill({ skill: next.skill, args: effective_args })
 ```
 
-**On success** → Step 5d (Mark Complete).
-**On failure** → Step 5e (Handle Failure).
+→ On success: Step 4a. On failure: Step 4b.
 
-### 5c. external node
+### external node
 
-Context-isolated skill execution via new Claude Code session.
-
-HARD RULE: external nodes ALWAYS delegate to `claude` — only Claude Code can execute slash-command skills.
-`session.cli_tool` is for analysis-mode delegates (e.g., decision evaluation in ralph), NOT for external node execution.
-
-HARD RULE: Delegate sessions are non-interactive and cannot confirm prompts. External nodes MUST always append `-y`, regardless of whether the user passed `-y`. Without it, delegate hangs indefinitely waiting for confirmation.
+HARD RULE: External nodes ALWAYS delegate to `claude` — only Claude Code can execute slash-command skills. `session.cli_tool` is for analysis-mode delegates (e.g., decision evaluation in ralph), NOT for external node execution.
 
 ```
-// Always apply auto flag — delegate sessions are non-interactive and cannot confirm
+// Always append -y to skill args inside the prompt — delegate sessions cannot confirm
 flag = auto_flag_map[next.skill] || "-y"
 effective_args = `${next.args} ${flag}`
 
 Bash({
-  command: `maestro delegate "Execute: Skill({ skill: \"${next.skill}\", args: \"${effective_args}\" })
-Do NOT reimplement — invoke the skill command directly." --to claude --mode write`,
+  command: `maestro delegate "/${next.skill} ${effective_args}" --to claude --mode write`,
   run_in_background: true,
   timeout: 600000
 })
@@ -203,12 +178,12 @@ Do NOT reimplement — invoke the skill command directly." --to claude --mode wr
 STOP — wait for background callback.
 ```
 
-**On callback:**
-- Retrieve output: `maestro delegate output <exec_id>`
-- **On success** → Step 5d (Mark Complete)
-- **On failure** → Step 5e (Handle Failure)
+On callback: retrieve output via `maestro delegate output <exec_id>`.
+→ On success: Step 4a. On failure: Step 4b.
+
+## Step 4: Post-Execution
 
-### 5d. Mark Complete (shared)
+### 4a. Mark Complete
 
 ```
 next.status = "completed"
@@ -223,12 +198,9 @@ Write status.json
 Display: [{next.index}/{total}] ✓ {next.skill} completed {next.type == "external" ? "[external]" : ""}
 ```
 
-Then hand off:
-```
-Skill({ skill: "maestro-ralph-execute" })
-```
+→ `Skill({ skill: "maestro-ralph-execute" })` (next iteration)
 
-### 5e. Handle Failure (shared)
+### 4b. Handle Failure
 
 ```
 next.status = "failed"
@@ -251,7 +223,7 @@ Else:
   End.
 ```
 
-**Interactive mode (non-auto):**
+**Interactive mode:**
 ```
 AskUserQuestion: "retry / skip / abort"
   retry → next.status = "pending", next.error = null → Skill("maestro-ralph-execute")
@@ -259,7 +231,7 @@ AskUserQuestion: "retry / skip / abort"
   abort → status.status = "paused" → Write status.json → End.
 ```
 
-## Step 6: Complete Session
+## Step 5: Complete Session
 
 When no pending steps remain:
 
@@ -312,7 +284,7 @@ Type badges: `◆` decision, `⚡` external, (none) internal.
 - [ ] Artifact dir resolution finds latest artifact for --dir args
 - [ ] decision nodes hand off to maestro-ralph via Skill() (ralph sessions only)
 - [ ] internal nodes execute via Skill() with auto flag propagation
-- [ ] external nodes use maestro delegate --to claude with run_in_background + STOP pattern
+- [ ] external nodes delegate to claude with `-y` in prompt args (not CLI args), run_in_background + STOP
 - [ ] Context propagation: output signals update status.json.context
 - [ ] status.json updated after every status change (resume-safe)
 - [ ] Auto mode: retry once then pause; interactive: AskUserQuestion retry/skip/abort

package/.claude/commands/maestro-ralph.md

@@ -190,7 +190,7 @@ Generate steps from `lifecycle_position` to target (default: `milestone-complete
 
 IMPORTANT: `external` ≠ single CLI tool call. It spawns a full Claude Code session that executes the skill command — the delegate session has complete skill access.
 
-HARD RULE: Delegate sessions are non-interactive. All skills executed via delegate MUST always append `-y`, regardless of user flags. This is enforced by ralph-execute in Step 5c — ralph does not preset flags in steps.
+HARD RULE: Delegate sessions are non-interactive. All skills executed via delegate MUST always append `-y` **to the skill's args inside the prompt** (not as a `maestro delegate` CLI argument). This is enforced by ralph-execute in Step 5c — ralph does not preset flags in steps.
 
 **Build rules:**
 1. Start from inferred position, skip completed stages
@@ -237,7 +237,7 @@ HARD RULE: Delegate sessions are non-interactive. All skills executed via delega
   "target": "milestone-complete",
   "phase": null | N,
   "milestone": "{M}",
-  "auto_mode": false,
+  "auto_mode": auto_confirm,
   "cli_tool": "claude",
   "quality_mode": "standard",
   "passed_gates": [],

package/.claude/commands/maestro-tools-execute.md

@@ -0,0 +1,117 @@
+---
+name: maestro-tools-execute
+description: Load and execute tool specs by role or name
+argument-hint: "[tool-name | --role <role>]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+  - Agent
+---
+<purpose>
+Load registered tool specs and execute them step-by-step. Two invocation modes:
+
+1. **Direct** — Specify tool name, load full steps, execute sequentially
+2. **Role-based** — List available tools for a role, user selects, then execute
+
+Execution follows the tool definition steps in order, reporting progress per step and asking user on blockers.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/tools-spec.md
+</required_reading>
+
+<context>
+$ARGUMENTS — Tool name, keyword, or --role filter
+
+**Examples**:
+```
+/maestro-tools-execute integration-test
+/maestro-tools-execute --role implement
+/maestro-tools-execute --role review --keyword api
+/maestro-tools-execute
+```
+
+Empty arguments enters interactive mode: list all tools for user selection.
+</context>
+
+<execution>
+
+### Step 1: Load Tool
+
+**By name**:
+```bash
+maestro spec load --role implement --keyword <name>
+```
+Match entries in tools.md whose title or keywords contain the name.
+
+**By role**:
+```bash
+maestro spec load --role <role>
+```
+Extract tools.md entries from output, list available tools.
+
+**Empty args**:
+Load all tools.md entries, present to user with AskUserQuestion for selection.
+
+### Step 2: Display Tool
+
+Show tool information:
+- Name, roles, keywords
+- Steps overview (for ref entries, expand knowhow detail first)
+
+Expand ref entries:
+```bash
+maestro wiki load <knowhow-id>
+```
+
+### Step 3: Confirm Execution
+
+Ask user:
+- Execute steps as-is?
+- Adjust parameters/scope?
+- View only, do not execute?
+
+### Step 4: Step-by-Step Execution
+
+Follow the tool definition steps in order:
+1. Read current step description
+2. Execute step action (file ops, commands, code changes, etc.)
+3. Verify step completion
+4. Report progress: `[Step N/M] done — <step_name>`
+5. Proceed to next step
+
+**Blocker handling**:
+- Step fails → report error, ask user: retry / skip / abort
+- Needs user input → AskUserQuestion for parameters
+- Prerequisites unmet → show missing items, ask how to proceed
+
+### Step 5: Report Results
+
+After completion, output:
+- Completed steps list
+- Skipped/failed steps (if any)
+- Artifacts produced (generated files, test results, etc.)
+- Suggested next actions
+
+</execution>
+
+<error_codes>
+| Code | Severity | Description |
+|------|----------|-------------|
+| E001 | fatal | No matching tool found — check name/keyword |
+| E002 | warning | Multiple tools match — list options for user selection |
+| E003 | warning | Step execution failed — ask user how to proceed |
+</error_codes>
+
+<success_criteria>
+- [ ] Tool correctly loaded (ref expanded if applicable)
+- [ ] User confirmed before execution starts
+- [ ] Each step has progress feedback
+- [ ] Blockers handled interactively
+- [ ] Results reported clearly
+</success_criteria>

package/.claude/commands/maestro-tools-register.md

@@ -0,0 +1,137 @@
+---
+name: maestro-tools-register
+description: Register tool specs - extract, generate, or optimize
+argument-hint: "[description]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+  - Agent
+---
+<purpose>
+Codify reusable business processes as tool specs into `.workflow/specs/tools.md`. Once registered, entries are auto-discovered by downstream agents via `spec load --role` and spec-injector — plan agents pick up design/architecture flows, test agents pick up verification methods, implement agents pick up execution steps.
+
+When to register: during planning to standardize a business process (e.g. payment reconciliation, OAuth integration steps); after execution to capture a validated procedure (e.g. database migration rollback); before testing to register verification methods for test agents (e.g. E2E checkout flow, API idempotency verification); during retrospective/harvest to extract reusable process knowledge from artifacts.
+
+Three modes: Extract (from code/docs), Generate (from description), Optimize (improve existing).
+Short processes (<10 steps) inline; long processes (>=10 steps) use ref mode with knowhow detail doc.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/tools-spec.md
+</required_reading>
+
+<context>
+$ARGUMENTS — Intent description
+
+**Examples**:
+```
+/maestro-tools-register extract OAuth PKCE token exchange flow from src/auth/
+/maestro-tools-register generate Stripe webhook idempotency verification --roles implement,test
+/maestro-tools-register generate E2E checkout flow with payment gateway mock setup --roles test
+/maestro-tools-register optimize e2e-checkout tool
+```
+</context>
+
+<execution>
+
+### Step 1: Intent Detection
+
+Parse $ARGUMENTS to determine mode:
+- Contains "extract" → extract mode
+- Contains "optimize/improve" → optimize mode
+- Other → generate mode
+- Empty → ask user with AskUserQuestion
+
+### Step 2: Gather Information
+
+**Extract mode**:
+- Identify source (current conversation, specified files, codebase scan)
+- Extract step sequence, prerequisites, expected outputs
+
+**Generate mode**:
+- Confirm tool name, applicable roles, target scenario
+- If unclear, ask user with AskUserQuestion
+
+**Optimize mode**:
+- Load existing tool: `maestro spec load --role implement --keyword <name>`
+- Analyze improvement points (step splitting, prerequisites, error handling)
+
+**For all modes** — identify the usage timing: when should an agent or user invoke this tool? This becomes the first line of the entry description (see Step 5).
+
+### Step 3: Determine Roles
+
+Infer applicable roles from context, or ask user:
+- implement — execution tools (build, deploy, integrate)
+- test — testing tools (test flows, verification steps)
+- review — review tools (checklists, audit standards)
+- plan — planning tools (design flows, analysis steps)
+- analyze — analysis tools (diagnostic flows, investigation steps)
+
+### Step 4: Decide Inline vs Ref
+
+- Steps <10 and no code blocks → **inline mode**
+- Steps >=10 or contains code examples/config → **ref mode**
+
+### Step 5: Write
+
+**Description format**: First line after `### Title` must state **when to use** this tool (the usage timing from Step 2). This is critical for ref entries — `spec load` only shows the first 200 chars after the heading as the summary.
+
+```
+### {Title}
+
+Use when {timing/trigger condition}.
+
+1. Step one ...
+```
+
+**Inline mode**:
+```bash
+maestro spec add tools "<title>" "Use when <timing>.\n\n1. <step1>\n2. <step2>" --roles "<csv>" --keywords "<csv>"
+```
+
+**Ref mode**:
+1. Generate knowhow detail document (RCP- or DOC- prefix). YAML frontmatter must include `summary` with usage timing — this is what `wiki list` and wiki-role-loader show to agents:
+```yaml
+---
+title: <Title>
+type: recipe
+summary: "Use when <timing>. <scope description>"
+tags: [<keywords>]
+roles: [<roles>]
+---
+```
+2. Register spec index entry — description must also include usage timing within 200 chars (this is what `spec load` shows):
+```bash
+maestro spec add tools "<title>" "Use when <timing>. <scope summary>" --roles "<csv>" --keywords "<csv>" \
+  --ref "knowhow/RCP-<slug>.md" --knowhow-type recipe
+```
+
+### Step 6: Verify
+
+- `maestro spec load --role <role> --keyword <keyword>` to confirm loadable
+- Display result: title, roles, keywords, storage location
+
+</execution>
+
+<error_codes>
+| Code | Severity | Description |
+|------|----------|-------------|
+| E001 | fatal | `.workflow/specs/` does not exist — run `maestro spec init` |
+| E002 | warning | Duplicate tool name detected — confirm overwrite/optimize |
+| E003 | fatal | roles parameter empty — tools must declare applicable roles |
+</error_codes>
+
+<success_criteria>
+- [ ] Tool definition written to tools.md (or ref to knowhow)
+- [ ] roles attribute correctly set
+- [ ] keywords auto-extracted (3-5 terms)
+- [ ] Description starts with "Use when ..." (usage timing)
+- [ ] Loadable via `spec load --role <role>`
+- [ ] Long processes use ref mode with knowhow file created
+- [ ] Ref knowhow YAML includes `summary` with usage timing
+</success_criteria>

package/.claude/commands/maestro-ui-codify.md

@@ -0,0 +1,67 @@
+---
+name: maestro-ui-codify
+description: Extract design system from code, generate reference package, persist as knowledge assets
+argument-hint: "<source-path> [--package-name <name>] [--output-dir <path>] [--overwrite]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - Skill
+---
+<purpose>
+Codify UI design system from existing source code. 4-phase pipeline:
+
+1. **Validate** (inline): Parameter validation, workspace setup, file discovery
+2. **Extract** (3 parallel agents): Style Agent + Animation Agent + Layout Agent produce design-tokens.json, animation-tokens.json, layout-templates.json
+3. **Package** (agent): Copy tokens to package directory, generate preview.html + preview.css
+4. **Knowhow** (manifest + skill): Build knowhow-manifest.json, call codify-to-knowhow to persist as knowledge assets
+
+Position in pipeline: code -> **ui-codify** -> knowhow + specs
+</purpose>
+
+<deferred_reading>
+- [ui-codify.md](~/.maestro/workflows/ui-codify.md) — read always (main workflow orchestrator)
+- [ui-codify-extract.md](~/.maestro/workflows/ui-codify-extract.md) — read when Phase 2 starts (style extraction with 3 agents)
+- [ui-codify-package.md](~/.maestro/workflows/ui-codify-package.md) — read when Phase 3 starts (reference package generation)
+- [ui-codify-knowhow.md](~/.maestro/workflows/ui-codify-knowhow.md) — read when Phase 4 starts (knowledge asset generation)
+</deferred_reading>
+
+<context>
+$ARGUMENTS — source path (required) with optional flags.
+
+Flags:
+- `<source-path>` (positional, required): Directory containing CSS/SCSS/JS/TS/HTML source files
+- `--package-name <name>`: Package name for reference output (default: auto-generated from source directory)
+- `--output-dir <path>`: Output directory for reference package (default: `.workflow/reference_style`)
+- `--overwrite`: Allow overwriting existing package directory
+</context>
+
+<execution>
+Route to `~/.maestro/workflows/ui-codify.md` and follow completely.
+
+The workflow orchestrates 4 phases with deferred loading of phase-specific workflow files. Each phase reads its workflow file only when execution reaches that phase.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | error | Source path argument required | parse_input |
+| E002 | error | Source path not found or not a directory | validate |
+| E003 | error | Package directory exists without --overwrite flag | validate |
+| W001 | warning | animation-tokens.json not found (optional, extraction continues) | extract |
+</error_codes>
+
+<success_criteria>
+- [ ] Source path validated and file discovery completed
+- [ ] design-tokens.json generated with color, typography, spacing tokens
+- [ ] layout-templates.json generated with component patterns (universal/specialized)
+- [ ] animation-tokens.json generated (optional, W001 if missing)
+- [ ] preview.html + preview.css generated as interactive showcase
+- [ ] knowhow-manifest.json created with AST/DCS assets and spec entries
+- [ ] codify-to-knowhow called and completed successfully
+- [ ] Temporary workspace cleaned up
+</success_criteria>

package/.claude/commands/manage-harvest.md

@@ -54,7 +54,7 @@ Extraction patterns, classification rules, routing infrastructure, and fragment
 - Review wiki entries → `maestro wiki list --type note`
 - Connect wiki graph → `/wiki-connect --fix`
 - Triage issues → `/manage-issue list --source harvest`
-- View specs → `/spec-load --category learning`
+- View specs → `/spec-load --role implement`
 - Full retrospective → `/quality-retrospective`
 </execution>
 

package/.claude/commands/manage-learn.md

@@ -16,7 +16,7 @@ Unified atomic knowledge capture for the workflow learning library. Captures two
 - **Insights**: Timeless "eureka moment" entries (patterns, gotchas, techniques) — the default mode
 - **Tips**: Quick contextual notes for cross-session recovery (formerly in `manage-knowhow-capture tip`)
 
-Both types are stored in `.workflow/learning/lessons.jsonl` with auto-detected phase linkage and keyword-based category inference. Tips are distinguished by `source: "tip"` and implicitly tagged `tip`. Same store as retrospective output, so search and list see the entire knowledge corpus.
+Both types are stored in `.workflow/specs/learnings.md` as `<spec-entry>` blocks with auto-detected phase linkage and keyword-based category inference. Tips are distinguished by `source: "tip"` and implicitly tagged `tip`. Same store as retrospective output, so search and list see the entire knowledge corpus.
 </purpose>
 
 <required_reading>
@@ -30,7 +30,7 @@ Arguments: $ARGUMENTS
 - `"<insight text>"` (or any non-keyword text) → insight capture mode
 - `tip <text>` → tip capture mode (quick contextual note, auto-tagged `tip`)
 - `list` → list recent entries (default 20)
-- `search <query>` → text search across lessons.jsonl
+- `search <query>` → `maestro spec load --category learning` or text search across `specs/learnings.md`
 - `show <INS-id>` → full detail with phase context
 - empty → AskUserQuestion to prompt for text
 
@@ -47,21 +47,19 @@ Follow `~/.maestro/workflows/learn.md` Stages 1–5 in order.
 | E001 | error | `.workflow/` not initialized — run `/maestro-init` first | parse_input |
 | E002 | error | Unknown `--category` value (allowed: pattern, antipattern, decision, tool, gotcha, technique, tip) | parse_input |
 | E003 | error | `show` mode requires an INS-id argument | show |
-| E004 | error | Insight id not found in lessons.jsonl | show |
+| E004 | error | Insight id not found in `specs/learnings.md` | show |
 | W001 | warning | Auto-phase detection found a current_phase but no matching artifact in registry; phase set to null | capture |
-| W002 | warning | learning-index.json out of sync with lessons.jsonl (different row count); offer to rebuild | list/search |
 </error_codes>
 
 <success_criteria>
 - [ ] Mode correctly routed (capture / list / search / show)
-- [ ] Capture: `lessons.jsonl` row appended with valid JSON and all required fields
-- [ ] Capture: `learning-index.json` updated with matching entry
+- [ ] Capture: `<spec-entry>` block appended to `specs/learnings.md` with all required fields
 - [ ] Capture: phase auto-link resolves correctly via artifact registry when `state.json` has `current_phase`
 - [ ] Capture: category inference produces a sensible default when `--category` absent
 - [ ] List: filters apply, output sorted newest-first, default limit 20
 - [ ] Search: results ranked by title (3) > tags (2) > summary (1) match
 - [ ] Show: full insight displayed with phase context and routed-artifact link if any
-- [ ] No file modifications outside `.workflow/learning/`
+- [ ] No file modifications outside `.workflow/knowhow/`
 - [ ] Confirmation banner displayed with INS-id and next-step hints
 - [ ] Next step: `/manage-learn list` to browse, or `/manage-learn search <query>` to find related insights
 </success_criteria>

package/.claude/commands/manage-wiki.md

@@ -34,7 +34,7 @@ $ARGUMENTS — subcommand and optional flags.
 | No args | Same as `health` |
 
 **Flags:**
-- `--type <type>` — Filter by wiki type: spec, knowhow, note, lesson, issue
+- `--type <type>` — Filter by wiki type: spec, knowhow, note, issue
 - `--fix` — Auto-fix issues found during cleanup (remove broken links, suggest connections)
 - `--json` — Output in JSON format
 </context>

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

@@ -85,7 +85,7 @@ Append to state.json.artifacts[]:
 **Next-step routing on completion:**
 - Converged (>=95%) → `/maestro-verify {phase}`
 - All requirements verified (spec source) → `/maestro-milestone-audit`
-- Bugs discovered → `/quality-debug --from-auto-test {phase}`
+- Bugs discovered → `/quality-debug --from-uat {phase}`
 - Max iter, >80% → `/quality-test {phase}` for manual UAT
 - Max iter, <80% → `/quality-debug {phase}`
 - Coverage still low → `/quality-auto-test {phase} --layer {missing}`

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

@@ -49,6 +49,14 @@ Extract conclusions from related artifacts that may affect this debug session
 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 --role analyze`
+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
+
 **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>