maestro-flow 0.3.43 → 0.3.44

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>
 

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

@@ -1,6 +1,6 @@
 ---
 name: quality-retrospective
-description: Phase retrospective with insight routing to specs and lessons
+description: Phase retrospective with insight routing to specs and knowhow
 argument-hint: "[phase|N..M] [--lens technical|process|quality|decision] [--all] [--no-route] [--compare N] [-y]"
 allowed-tools:
   - Read
@@ -13,7 +13,7 @@ allowed-tools:
   - AskUserQuestion
 ---
 <purpose>
-Post-execution multi-perspective retrospective (复盘) for completed phases. Consumes existing execution artifacts (verification.json, review.json, issues.jsonl, plan.json, .summaries/, uat.md, state.json) and runs four parallel lenses — technical, process, quality, decision — to distill reusable insights. Routes each insight into the appropriate store: spec stub for reusable patterns, memory tip for process notes, issue for recurring gaps. Auto-scans for unreviewed completed phases and reports the backlog. Every insight is also persisted to `.workflow/learning/lessons.jsonl` for cross-phase queryability.
+Post-execution multi-perspective retrospective (复盘) for completed phases. Consumes existing execution artifacts (verification.json, review.json, issues.jsonl, plan.json, .summaries/, uat.md, state.json) and runs four parallel lenses — technical, process, quality, decision — to distill reusable insights. Routes each insight into the appropriate store: spec stub for reusable patterns, memory tip for process notes, issue for recurring gaps. Auto-scans for unreviewed completed phases and reports the backlog. Every insight is also persisted to `.workflow/knowhow/specs/learnings.md` as `<spec-entry>` blocks for cross-phase queryability.
 </purpose>
 
 <required_reading>
@@ -70,9 +70,8 @@ Follow `~/.maestro/workflows/retrospective.md` Stages 1–8 in order. Key invari
 - [ ] Spec entries (if any) appended as `<spec-entry>` to matching `.workflow/specs/{category-file}.md`
 - [ ] Issue rows (if any) match canonical issues.jsonl schema (status "open", full issue_history, all required fields)
 - [ ] Note tips (if any) created via `Skill({ skill: "manage-learn", args: "tip ..." })`
-- [ ] `lessons.jsonl` appended with one row per insight regardless of routing target
-- [ ] `learning-index.json` updated and parseable
+- [ ] `specs/learnings.md` appended with one `<spec-entry>` per insight regardless of routing target
 - [ ] No existing phase artifacts modified (verification.json, review.json, plan.json untouched)
 - [ ] Confirmation banner displays routing counts and next-step suggestions
-- [ ] Next step: `/manage-status` to review state, or `/manage-issue list --source retrospective` to triage created issues, or `/manage-learn list` to browse the lessons library
+- [ ] Next step: `/manage-status` to review state, or `/manage-issue list --source retrospective` to triage created issues, or `/manage-learn list` to browse the knowhow library
 </success_criteria>

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

@@ -54,6 +54,14 @@ Extract conclusions from related artifacts that may affect this review. Pass as
 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 --role 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
+
 **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/spec-add.md

@@ -1,7 +1,7 @@
 ---
 name: spec-add
-description: Add spec entry by category
-argument-hint: "[--scope project|global|team|personal] <category> <content>"
+description: Add spec entry by category with role tagging
+argument-hint: "[--scope project|global|team|personal] [--roles <csv>] <category> <content>"
 allowed-tools:
   - Read
   - Write
@@ -13,6 +13,7 @@ allowed-tools:
 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 `roles` attribute to declare which agent roles should load them.
 </purpose>
 
 <required_reading>
@@ -20,9 +21,29 @@ Supports 4 scopes: project (default), global, team, personal.
 </required_reading>
 
 <context>
-$ARGUMENTS -- expects `[--scope <scope>] [--uid <uid>] <category> <content>`
+$ARGUMENTS -- expects `[--scope <scope>] [--uid <uid>] [--roles <csv>] <category> <content>`
+
+**Options:**
+- `--roles <csv>` — Comma-separated roles (implement, plan, test, review, analyze, explore). Determines which agents load this entry via `spec load --role`.
+- `--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
+# Tool spec with roles (stored in tools.md)
+/spec-add tools "Integration Test Flow" "## Steps\n1. Setup\n2. Run" --roles "implement,test" --keywords "testing,api"
+
+# Tool spec with ref to detailed knowhow
+/spec-add tools "OAuth PKCE Flow" "完整 PKCE 集成流程" --roles "implement" --ref knowhow/RCP-oauth-pkce.md
+
+# Standard spec with role
+/spec-add coding "Named exports" "Always use named exports" --roles "implement"
+
+# Legacy style (no --roles, backward compat)
+/spec-add arch "OAuth PKCE 集成" "完整流程设计" --ref knowhow/AST-oauth-flow.md
+```
 </context>
 
 <execution>
@@ -34,7 +55,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 | parse_input |
+| E003 | fatal | Invalid category -- must be one of: coding, arch, quality, debug, test, review, learning, tools | 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

@@ -1,7 +1,7 @@
 ---
 name: spec-load
 description: Load specs and lessons for current context
-argument-hint: "[--category <type>] [--keyword <word>] [--with-lessons]"
+argument-hint: "[--role <role>] [--keyword <word>]"
 allowed-tools:
   - Read
   - Bash
@@ -9,8 +9,8 @@ allowed-tools:
   - 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).
+Load relevant specs filtered by role (primary), category (file-level), and/or keyword (entry-level).
+Role-based loading: loads the role's primary doc in full + matching entries from other files.
 </purpose>
 
 <required_reading>
@@ -20,14 +20,34 @@ Supports filtering by category (file-level) and keyword (entry-level via `<spec-
 <context>
 $ARGUMENTS -- optional flags and keyword
 
-Category-to-file mapping (1:1) and flag details defined in workflow specs-load.md.
+**Flags:**
+- `--role <role>` — Load by role: primary role doc (full) + cross-file entries with matching roles attr. Roles: implement, plan, test, review, analyze, explore, brainstorm, research.
+- `--keyword <word>` — Filter by keyword within entries
+
+**File → Primary Role mapping:**
+| File | Role |
+|------|------|
+| coding-conventions.md | implement |
+| architecture-constraints.md | plan |
+| test-conventions.md | test |
+| review-standards.md | review |
+| debug-notes.md | analyze |
+| quality-rules.md | review |
+| learnings.md | implement |
+| tools.md | _(per-entry roles)_ |
 
 **Examples:**
 ```
+/spec-load --role implement             # coding全文 + 跨文件implement条目
+/spec-load --role review                # review-standards + quality-rules + 跨文件review条目
+/spec-load --role implement --keyword auth
 /spec-load --keyword auth
-/spec-load --category coding --keyword naming
-/spec-load --category arch
 ```
+
+**Ref entries:**
+When loading entries with `ref` attribute, only the summary is shown with a load command:
+  → Detail: maestro wiki load <knowhow-id>
+Use the load command to read the full referenced document.
 </context>
 
 <execution>

package/.claude/commands/spec-setup.md

@@ -11,7 +11,7 @@ allowed-tools:
 ---
 <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.
+Core files (coding, arch, knowhow) are always created. Optional files (quality, debug, test, review) are created only when relevant signals are detected.
 All output lands in `.workflow/specs/`.
 </purpose>
 
@@ -44,7 +44,7 @@ Follow '~/.maestro/workflows/specs-setup.md' completely.
 
 <success_criteria>
 - [ ] `.workflow/specs/` directory created
-- [ ] Core files always created: `coding-conventions.md`, `architecture-constraints.md`, `learnings.md`
+- [ ] Core files always created: `coding-conventions.md`, `architecture-constraints.md`, `knowhow.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>

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

@@ -56,7 +56,7 @@ Follow '~/.maestro/workflows/wiki-connect.md' completely (Stages 1-6).
 - [ ] 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`
+- [ ] Graph insights appended to `specs/learnings.md` as `<spec-entry>` blocks
 - [ ] No unintended entry modifications (only `related` field changed)
 - [ ] Summary displayed with next-step routing
 </success_criteria>

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

@@ -48,7 +48,7 @@ Follow '~/.maestro/workflows/wiki-digest.md' completely (Stages 1-8).
 | 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 |
+| W002 | warning | specs/learnings.md not found — skipping cross-reference | Proceed without knowhow context |
 | W003 | warning | Some entry bodies failed to load — partial summaries | Note incomplete entries in digest |
 </error_codes>
 
@@ -57,13 +57,12 @@ Follow '~/.maestro/workflows/wiki-digest.md' completely (Stages 1-8).
 - [ ] 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
+- [ ] Cross-reference with specs/learnings.md 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`)
+- [ ] Digest written to `KNW-digest-{slug}-{date}.md`
+- [ ] Meta-insights appended to `specs/learnings.md` as `<spec-entry>` blocks
+- [ ] No files modified outside `.workflow/knowhow/` and `.workflow/issues/` (issues only when `--create-issues`)
 - [ ] Summary displayed with key findings and next-step routing
 </success_criteria>