maestro-flow 0.3.44 → 0.3.46

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

@@ -134,7 +134,7 @@ Build the decomposition report grouped by dimension:
 
 ### Stage 6: Persist
 1. Write `.workflow/knowhow/KNW-decompose-{slug}-{date}.md`
-2. Append each **new** pattern as a `<spec-entry>` block to `specs/learnings.md` via `maestro spec add learning --roles implement --body "<content>" --keywords "decompose,pattern,{dimension},{target-slug}"`:
+2. Append each **new** pattern as a `<spec-entry>` block to `specs/learnings.md` via `maestro spec add learning --body "<content>" --keywords "decompose,pattern,{dimension},{target-slug}"`:
    - Stable INS-id from `hash("decompose" + target + pattern_name)`
 4. If `--save-spec`: for each new pattern, invoke `Skill({ skill: "spec-add", args: "pattern {description}" })`
 5. If `--save-wiki`: create wiki note per dimension group via `maestro wiki create --type note --slug decompose-{dimension}-{slug}`

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

@@ -124,7 +124,7 @@ Build a structured summary document:
 
 ### Stage 7: Persist
 1. Write `.workflow/knowhow/KNW-follow-{slug}-{date}.md` with the understanding map
-2. Append each new pattern/technique as a `<spec-entry>` block to `specs/learnings.md` via `maestro spec add learning --roles implement --body "<content>" --keywords "follow,{target-slug}"`:
+2. Append each new pattern/technique as a `<spec-entry>` block to `specs/learnings.md` via `maestro spec add learning --body "<content>" --keywords "follow,{target-slug}"`:
    - Stable INS-id from `hash("follow" + target + pattern_name)`
 3. If `--save-wiki`: run `maestro wiki create --type note --slug follow-{slug} --title "Follow-Along: {target}" --body-file .workflow/knowhow/KNW-follow-{slug}-{date}.md`
 5. Display summary with key findings and next steps

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

@@ -178,7 +178,7 @@ Write final `report.md`:
 ```
 
 ### Stage 8: Persist
-1. Append findings as `<spec-entry>` blocks to `specs/learnings.md` via `maestro spec add learning --roles implement --body "<content>" --keywords "investigate,{question-slug}"`:
+1. Append findings as `<spec-entry>` blocks to `specs/learnings.md` via `maestro spec add learning --body "<content>" --keywords "investigate,{question-slug}"`:
    - Confirmed hypotheses → `roles="implement"` (merge "technique"/"pattern" into keywords)
    - Disproved hypotheses → `roles="analyze"` (merge "gotcha" into keywords)
    - Stable INS-id from `hash("investigate" + question + finding_title)`

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

@@ -248,7 +248,7 @@ Write `.workflow/knowhow/KNW-retro-{date}.json` with structured data.
 
 ### Stage 5: Persist
 1. Write report files
-2. Append insights as `<spec-entry>` blocks to `specs/learnings.md` via `maestro spec add learning --roles implement --body "<content>" --keywords "<kw>"`:
+2. Append insights as `<spec-entry>` blocks to `specs/learnings.md` via `maestro spec add learning --body "<content>" --keywords "<kw>"`:
    - Git insights: source="retro-git", roles per insight type
    - Decision insights: source="retro-decision", roles="plan" (merge "decision" into keywords)
    - Stable INS-id from `hash(lens + metric_or_decision + date)`

package/.claude/commands/learn-second-opinion.md

@@ -128,7 +128,7 @@ Across all perspectives (or from single agent in challenge/consult):
    - Per-persona findings (review) / adversarial analysis (challenge) / Q&A transcript (consult)
    - Synthesis: agreements, disagreements, verdict
    - Recommendations
-2. Append non-trivial findings as `<spec-entry>` blocks to `specs/learnings.md` via `maestro spec add learning --roles implement --body "<content>" --keywords "second-opinion,{mode},{target-slug}"`
+2. Append non-trivial findings as `<spec-entry>` blocks to `specs/learnings.md` via `maestro spec add learning --body "<content>" --keywords "second-opinion,{mode},{target-slug}"`
 4. Display summary with verdict and recommendations
 
 **Next-step routing:**

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

@@ -44,7 +44,7 @@ Scope routing, output directory format, artifact registration schema, and output
 
 ### Role Knowledge
 1. Browse accumulated knowledge for this role:
-   `maestro wiki list --role analyze`
+   `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...]`

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

@@ -47,7 +47,7 @@ $ARGUMENTS -- topic text for auto mode, or role name for single role mode.
 
 ### Role Knowledge
 1. Browse accumulated knowledge for this role:
-   `maestro wiki list --role brainstorm`
+   `maestro wiki list --category arch`
 2. Analyze the index, identify entries relevant to the current task
 3. Load selected documents:
    `maestro wiki load <id1> [id2] [id3...]`

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

@@ -36,11 +36,12 @@ Scope routing, flags, resolution logic, output directory format, artifact regist
 
 1. **Codebase docs**: If `.workflow/codebase/doc-index.json` exists, read `ARCHITECTURE.md` for module boundaries. Pass as shared context to executor agents.
 2. **Wiki knowledge**: Run `maestro wiki search "<phase keywords>" --json 2>/dev/null`. If results found, extract top 5 entries as prior knowledge context for agents.
-3. Both are optional — proceed without if unavailable (log warning).
+3. **Coding specs + tools**: Run `maestro spec load --category coding` to load coding conventions AND discoverable knowhow tools (tool: true entries). Pass as specs context to all executor agents.
+4. All are optional — proceed without if unavailable (log warning).
 
 ### Role Knowledge
 1. Browse accumulated knowledge for this role:
-   `maestro wiki list --role implement`
+   `maestro wiki list --category coding`
 2. Analyze the index, identify entries relevant to the current task
 3. Load selected documents:
    `maestro wiki load <id1> [id2] [id3...]`

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

@@ -48,7 +48,7 @@ Scope routing, base flags (`--collab`, `--spec`, `-y`, `--gaps`, `--dir`), outpu
 
 ### Role Knowledge
 1. Browse accumulated knowledge for this role:
-   `maestro wiki list --role plan`
+   `maestro wiki list --category arch`
 2. Analyze the index, identify entries relevant to the current task
 3. Load selected documents:
    `maestro wiki load <id1> [id2] [id3...]`

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

@@ -1,7 +1,7 @@
 ---
 name: maestro-tools-execute
-description: Load and execute tool specs by role or name
-argument-hint: "[tool-name | --role <role>]"
+description: Load and execute tool specs by category or name
+argument-hint: "[tool-name | --category <category>]"
 allowed-tools:
   - Read
   - Write
@@ -13,10 +13,10 @@ allowed-tools:
   - Agent
 ---
 <purpose>
-Load registered tool specs and execute them step-by-step. Two invocation modes:
+Load registered tool documents 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
+2. **Category-based** — List available tools for a category, user selects, then execute
 
 Execution follows the tool definition steps in order, reporting progress per step and asking user on blockers.
 </purpose>
@@ -26,13 +26,13 @@ Execution follows the tool definition steps in order, reporting progress per ste
 </required_reading>
 
 <context>
-$ARGUMENTS — Tool name, keyword, or --role filter
+$ARGUMENTS — Tool name, keyword, or --category filter
 
 **Examples**:
 ```
 /maestro-tools-execute integration-test
-/maestro-tools-execute --role implement
-/maestro-tools-execute --role review --keyword api
+/maestro-tools-execute --category coding
+/maestro-tools-execute --category review --keyword api
 /maestro-tools-execute
 ```
 
@@ -45,23 +45,23 @@ Empty arguments enters interactive mode: list all tools for user selection.
 
 **By name**:
 ```bash
-maestro spec load --role implement --keyword <name>
+maestro spec load --category coding --keyword <name>
 ```
-Match entries in tools.md whose title or keywords contain the name.
+Match knowhow documents with `tool: true` whose title or keywords contain the name.
 
-**By role**:
+**By category**:
 ```bash
-maestro spec load --role <role>
+maestro spec load --category <category>
 ```
-Extract tools.md entries from output, list available tools.
+Extract tool entries from the "Available Tools" section in output.
 
 **Empty args**:
-Load all tools.md entries, present to user with AskUserQuestion for selection.
+Load all categories, collect tool entries, present to user with AskUserQuestion for selection.
 
 ### Step 2: Display Tool
 
 Show tool information:
-- Name, roles, keywords
+- Name, category, keywords
 - Steps overview (for ref entries, expand knowhow detail first)
 
 Expand ref entries:

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

@@ -13,11 +13,11 @@ allowed-tools:
   - 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.
+Codify reusable business processes as knowhow documents with `tool: true` in `.workflow/knowhow/`. Once registered, tools are auto-discovered by `spec load --category` 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).
+Four modes: Extract (from code/docs), Generate (from description), Optimize (improve existing), Promote (existing knowhow → tool in place).
 Short processes (<10 steps) inline; long processes (>=10 steps) use ref mode with knowhow detail doc.
 </purpose>
 
@@ -31,9 +31,11 @@ $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 generate Stripe webhook idempotency verification
+/maestro-tools-register generate E2E checkout flow with payment gateway mock setup
 /maestro-tools-register optimize e2e-checkout tool
+/maestro-tools-register promote RCP-db-migration-rollback as test tool
+/maestro-tools-register promote knowhow-auth-api to coding tool
 ```
 </context>
 
@@ -44,6 +46,7 @@ $ARGUMENTS — Intent description
 Parse $ARGUMENTS to determine mode:
 - Contains "extract" → extract mode
 - Contains "optimize/improve" → optimize mode
+- Contains "promote" or references existing knowhow doc (path/ID) → promote mode
 - Other → generate mode
 - Empty → ask user with AskUserQuestion
 
@@ -58,19 +61,37 @@ Parse $ARGUMENTS to determine mode:
 - If unclear, ask user with AskUserQuestion
 
 **Optimize mode**:
-- Load existing tool: `maestro spec load --role implement --keyword <name>`
+- Load existing tool: `maestro spec load --category coding --keyword <name>`
 - Analyze improvement points (step splitting, prerequisites, error handling)
 
+**Promote mode** (existing knowhow → tool):
+- Locate document: `maestro wiki list --keyword <name>` or by path in `.workflow/knowhow/`
+- Read document, verify it contains actionable steps (numbered list or ## Steps section)
+- If no actionable steps, suggest extract mode instead
+- Determine category (Step 3) and summary ("Use when ...")
+- Update frontmatter via: `maestro wiki update <id> --frontmatter '{"tool": true, "category": "<cat>", "summary": "<summary>"}'`
+- Do NOT recreate the document — modify in place
+
 **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
+### Step 3: Determine Category
+
+**Core principle**: `category` = **who consumes this tool** (which agent type discovers and uses it), not what the content is about.
+
+| Category | Consumer Agent | Decision Question | Signal Words |
+|---|---|---|---|
+| `coding` | code-developer, workflow-executor | 开发者实现时需要这个流程吗？ | build, deploy, integrate, configure, setup, migrate, api-contract |
+| `test` | tdd-developer, test-fix-agent | 测试者验证行为时需要这个流程吗？ | verify, validate, assert, e2e, regression, coverage, idempotency |
+| `review` | workflow-reviewer | 审查者需要这个作为 checklist 吗？ | audit, checklist, compliance, quality-gate, standard |
+| `arch` | workflow-planner | 规划者设计方案时需要这个吗？ | design, architecture, decompose, trade-off, migration-strategy |
+| `debug` | debug-explore-agent | 调试者排查问题时需要这个吗？ | diagnose, trace, investigate, root-cause, reproduce |
 
-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)
+**Multi-consumer split**: If content serves multiple consumers (e.g., API doc for both dev and test), split into separate documents:
+- API contract (what endpoints look like) → `category: coding` (AST-*, tool: false)
+- API verification steps (how to test) → `category: test` (RCP-*, tool: true)
+- Ask user when ambiguous: "This tool content serves both developers and testers. Split into separate documents?"
+
+**Ambiguous cases**: Choose the **primary consumer** — the agent that would fail without this knowledge.
 
 ### Step 4: Decide Inline vs Ref
 
@@ -89,32 +110,31 @@ 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:
+**Create knowhow tool document** in `.workflow/knowhow/` with `tool: true` in YAML frontmatter:
 ```yaml
 ---
 title: <Title>
 type: recipe
+category: <category>
+keywords: [<keywords>]
+tool: true
 summary: "Use when <timing>. <scope description>"
-tags: [<keywords>]
-roles: [<roles>]
 ---
+
+## Steps
+1. Step one ...
 ```
-2. Register spec index entry — description must also include usage timing within 200 chars (this is what `spec load` shows):
+
+**Optionally register spec ref entry** for index discoverability:
 ```bash
-maestro spec add tools "<title>" "Use when <timing>. <scope summary>" --roles "<csv>" --keywords "<csv>" \
+maestro spec add <category> "<title>" "Use when <timing>. <scope summary>" --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
+- `maestro spec load --category <category> --keyword <keyword>` to confirm loadable
+- Display result: title, category, keywords, storage location
 
 </execution>
 
@@ -123,15 +143,15 @@ maestro spec add tools "<title>" "Use when <timing>. <scope summary>" --roles "<
 |------|----------|-------------|
 | 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 |
+| E003 | fatal | category parameter empty — tools must declare a category |
 </error_codes>
 
 <success_criteria>
-- [ ] Tool definition written to tools.md (or ref to knowhow)
-- [ ] roles attribute correctly set
+- [ ] Tool registered as knowhow document with `tool: true` frontmatter
+- [ ] category correctly set
 - [ ] keywords auto-extracted (3-5 terms)
 - [ ] Description starts with "Use when ..." (usage timing)
-- [ ] Loadable via `spec load --role <role>`
+- [ ] Loadable via `spec load --category <category>`
 - [ ] Long processes use ref mode with knowhow file created
 - [ ] Ref knowhow YAML includes `summary` with usage timing
 </success_criteria>

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

@@ -34,6 +34,9 @@ Arguments: $ARGUMENTS
 | `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 |
+| `asset` | AST- | Code asset (API contract, data model) | assetType, codePaths, category |
+| `blueprint` | BLP- | Architecture design with code paths | codePaths, category |
+| `document` | DOC- | General long-form (fallback) | — |
 
 No arguments: auto-detect type or ask user via AskUserQuestion.
 
@@ -42,6 +45,9 @@ No arguments: auto-detect type or ask user via AskUserQuestion.
 - `--source <url>` — Source URL for references
 - `--tag tag1,tag2` — Categorization tags
 - `--title <title>` — Explicit title (auto-generated if omitted)
+- `--asset-type <type>` — Asset subtype: api-contract, data-model, prompt, config, etc.
+- `--code-paths <paths>` — Related source paths for asset/blueprint (comma-separated)
+- `--category <cat>` — Spec category for agent discovery (coding, arch, test, debug, review, learning)
 </context>
 
 <execution>
@@ -58,8 +64,11 @@ Parse first token as type. If ambiguous, AskUserQuestion with options:
 | `reference`, `ref`, `参考`, `引用` | reference |
 | `decision`, `dcs`, `决策`, `adr` | decision |
 | `tip`, `note`, `记录`, `快速` | tip |
+| `asset`, `ast`, `资产`, `契约` | asset |
+| `blueprint`, `blp`, `蓝图` | blueprint |
+| `document`, `doc`, `文档` | document |
 | No match, short text, `--tag` present | tip |
-| No arguments | AskUserQuestion (6 options) |
+| No arguments | AskUserQuestion (9 options) |
 
 ### Step 2: Generate Content by Type
 

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

@@ -47,11 +47,12 @@ Extract conclusions from related artifacts that may affect this debug session
 
 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.
+3. **Debug specs + tools**: Run `maestro spec load --category debug --keyword "<symptom keywords>"`. If tools found, extract known issues, workarounds, and root-cause notes to inform hypotheses.
+4. All are optional — proceed without if unavailable.
 
 ### Role Knowledge
 1. Browse accumulated knowledge for this role:
-   `maestro wiki list --role analyze`
+   `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...]`

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

@@ -52,11 +52,12 @@ Extract conclusions from related artifacts that may affect this review. Pass as
 
 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.
+3. **Review specs + tools**: Run `maestro spec load --category review` to load review standards, checklists, AND discoverable knowhow tools. Pass as `specs_content` to all reviewer agents.
+4. All are optional — proceed without if unavailable.
 
 ### Role Knowledge
 1. Browse accumulated knowledge for this role:
-   `maestro wiki list --role review`
+   `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...]`

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

@@ -1,7 +1,7 @@
 ---
 name: spec-add
 description: Add spec entry by category with role tagging
-argument-hint: "[--scope project|global|team|personal] [--roles <csv>] <category> <content>"
+argument-hint: "[--scope project|global|team|personal] <category> <content>"
 allowed-tools:
   - Read
   - Write
@@ -13,7 +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.
+Entries use `category` attribute to declare which category they belong to.
 </purpose>
 
 <required_reading>
@@ -21,10 +21,9 @@ Entries use `roles` attribute to declare which agent roles should load them.
 </required_reading>
 
 <context>
-$ARGUMENTS -- expects `[--scope <scope>] [--uid <uid>] [--roles <csv>] <category> <content>`
+$ARGUMENTS -- expects `[--scope <scope>] [--uid <uid>] <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)
 
@@ -32,16 +31,12 @@ Scope-to-directory mapping, category-to-file mapping, and entry format defined i
 
 **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"
+# Standard spec entry
+/spec-add coding "Named exports" "Always use named exports" --keywords "exports,naming"
 
-# Tool spec with ref to detailed knowhow
-/spec-add tools "OAuth PKCE Flow" "完整 PKCE 集成流程" --roles "implement" --ref knowhow/RCP-oauth-pkce.md
+# Spec with ref to detailed knowhow
+/spec-add coding "OAuth PKCE Flow" "完整 PKCE 集成流程" --ref knowhow/RCP-oauth-pkce.md --keywords "oauth,pkce"
 
-# 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>

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

@@ -1,7 +1,7 @@
 ---
 name: spec-load
 description: Load specs and lessons for current context
-argument-hint: "[--role <role>] [--keyword <word>]"
+argument-hint: "[--category <category>] [--keyword <word>]"
 allowed-tools:
   - Read
   - Bash
@@ -9,8 +9,8 @@ allowed-tools:
   - Grep
 ---
 <purpose>
-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.
+Load relevant specs filtered by category (file-level) and/or keyword (entry-level).
+Category-based loading: loads the category's primary doc in full + matching entries from other files.
 </purpose>
 
 <required_reading>
@@ -21,26 +21,25 @@ Role-based loading: loads the role's primary doc in full + matching entries from
 $ARGUMENTS -- optional flags and keyword
 
 **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.
+- `--category <category>` — Load by category: primary category doc (full) + cross-file entries with matching category attr. Categories: coding, arch, test, review, debug, quality, learning.
 - `--keyword <word>` — Filter by keyword within entries
 
-**File → Primary Role mapping:**
-| File | Role |
-|------|------|
-| coding-conventions.md | implement |
-| architecture-constraints.md | plan |
+**File → Primary Category mapping:**
+| File | Category |
+|------|----------|
+| coding-conventions.md | coding |
+| architecture-constraints.md | arch |
 | test-conventions.md | test |
 | review-standards.md | review |
-| debug-notes.md | analyze |
-| quality-rules.md | review |
-| learnings.md | implement |
-| tools.md | _(per-entry roles)_ |
+| debug-notes.md | debug |
+| quality-rules.md | quality |
+| learnings.md | learning |
 
 **Examples:**
 ```
-/spec-load --role implement             # coding全文 + 跨文件implement条目
-/spec-load --role review                # review-standards + quality-rules + 跨文件review条目
-/spec-load --role implement --keyword auth
+/spec-load --category coding            # coding全文 + 跨文件coding条目
+/spec-load --category review            # review-standards + quality-rules + 跨文件review条目
+/spec-load --category coding --keyword auth
 /spec-load --keyword auth
 ```
 

package/.claude/skills/codify-to-knowhow/SKILL.md

@@ -164,4 +164,4 @@ Completion report
 ## Related Commands
 
 **上游**: `maestro-ui-codify`, `learn-decompose`, 或任何生成 manifest 的 skill
-**后续**: `maestro wiki list --role implement`, `maestro spec load --keyword <slug>`
+**后续**: `maestro wiki list --category coding`, `maestro spec load --keyword <slug>`

package/.claude/skills/codify-to-knowhow/phases/04-index-verify.md

@@ -104,7 +104,7 @@ Ref 链接: spec → knowhow 桥梁已建立
 Wiki 索引: 已刷新
 
 后续操作:
-  maestro wiki list --role implement    # 按角色浏览
+  maestro wiki list --category coding    # 按角色浏览
   maestro spec load --keyword {slug}    # 加载相关 spec
   maestro wiki load <id>                # 加载详文
 ```