maestro-flow 0.3.44 → 0.3.45

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

@@ -40,7 +40,7 @@ Scope routing, flags, resolution logic, output directory format, artifact regist
 
 ### 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,7 +13,7 @@ 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.
 
@@ -31,8 +31,8 @@ $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
 ```
 </context>
@@ -58,19 +58,19 @@ 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)
 
 **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
 
-Infer applicable roles from context, or ask user:
-- implement — execution tools (build, deploy, integrate)
+Infer applicable category from context, or ask user:
+- coding — 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)
+- arch — planning tools (design flows, analysis steps)
+- debug — analysis tools (diagnostic flows, investigation steps)
 
 ### Step 4: Decide Inline vs Ref
 
@@ -89,32 +89,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 +122,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/quality-debug.md

@@ -51,7 +51,7 @@ Extract conclusions from related artifacts that may affect this debug session
 
 ### 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

@@ -56,7 +56,7 @@ Extract conclusions from related artifacts that may affect this review. Pass as
 
 ### 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/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>                # 加载详文
 ```

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

@@ -56,7 +56,7 @@ $codify-to-knowhow ".workflow/reference_style/my-style-v1"
 - `<package-path>` (positional, required): Directory containing `knowhow-manifest.json`
 
 **Upstream**: `maestro-ui-codify`, `learn-decompose`, or any skill that generates a manifest
-**Downstream**: `maestro wiki list --role implement`, `maestro spec load --keyword <slug>`
+**Downstream**: `maestro wiki list --category coding`, `maestro spec load --keyword <slug>`
 </context>
 
 <manifest_schema>
@@ -396,7 +396,7 @@ Ref Links: spec -> knowhow bridge established
 Wiki Index: refreshed
 
 Next steps:
-  maestro wiki list --role implement    # Browse by role
+  maestro wiki list --category coding    # Browse by role
   maestro spec load --keyword {slug}    # Load related specs
   maestro wiki load <id>                # Load full entry
 ```

package/.codex/skills/maestro-analyze/SKILL.md

@@ -208,7 +208,7 @@ Create both directories.
    - Read `.workflow/state.json` → `current_milestone`, `artifacts[]`, `accumulated_context`
    - Find prior analyze artifacts from `state.json.artifacts[]` (type=analyze, same milestone) → load their `context.md`
    - Find brainstorm artifacts from `state.json.artifacts[]` (type=brainstorm, same milestone) → load `guidance-specification.md`
-   - Load project specs: `maestro spec load --role plan`
+   - Load project specs: `maestro spec load --category arch`
 
 3. **Quick mode routing**: If QUICK_MODE, generate only wave 3 (synthesis/decide) task in CSV. Skip exploration and scoring.
 

package/.codex/skills/maestro-collab/SKILL.md

@@ -208,7 +208,7 @@ Mark each eligible tool as `recommended: true/false` based on auto-selection.
 
 **3. Context loading**:
 - Read `.workflow/project.md` if exists
-- Load project specs: `maestro spec load --role implement` (if available)
+- Load project specs: `maestro spec load --category coding` (if available)
 - Grep for relevant codebase files based on requirement keywords
 
 **4. Build delegate prompt** (shared across all tools):

package/.codex/skills/maestro-milestone-complete/SKILL.md

@@ -61,7 +61,7 @@ Snapshot `roadmap.md` as `roadmap-snapshot.md` in the milestone archive.
 
 **Extraction**: Parse each source for patterns, pitfalls, strategy adjustments. Look for recurring themes across summaries and explicit lessons in reflection logs.
 
-**Dedup**: Run `maestro spec load --role implement` to load existing entries. Skip any extracted learning whose keywords fully overlap with an existing entry.
+**Dedup**: Run `maestro spec load --category coding` to load existing entries. Skip any extracted learning whose keywords fully overlap with an existing entry.
 
 **Write**: Append to `.workflow/specs/learnings.md` using `<spec-entry>` closed-tag format:
 ```

package/.codex/skills/maestro-plan/SKILL.md

@@ -198,7 +198,7 @@ If no matching session found, list available sessions and abort.
    - Read spec-ref if `--spec` flag
    - Read `.workflow/codebase/doc-index.json` if exists
    - Find design artifacts from `state.json.artifacts[]` (type=brainstorm with ui-designer) for MASTER.md
-   - Load project specs via `maestro spec load --role plan`
+   - Load project specs via `maestro spec load --category arch`
 
 3. **Upstream analysis check**:
    - If `{contextDir}/conclusions.json` exists and has content: reuse as exploration context, skip wave 1

package/.codex/skills/maestro-tools-execute/SKILL.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>]"
+argument-hint: "[tool-name | --category <category>]"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Agent
 ---
 
@@ -9,18 +9,18 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Agent
 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
+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>
 
 <context>
-$ARGUMENTS — Tool name, keyword, or --role filter
+$ARGUMENTS — Tool name, keyword, or --category filter
 
 ```bash
 $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
 ```
 
@@ -33,23 +33,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 tool entries 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 output, list available tools.
 
 **Empty args**:
-Load all tools.md entries, present to user with AskUserQuestion for selection.
+Load all 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: