maestro-flow 0.3.44 → 0.3.46

package/workflows/knowhow.md

@@ -390,7 +390,7 @@ Atomic insights captured during active work.
 
 ## Entries
 
-<spec-entry roles="implement" keywords="pattern,auth,jwt" date="2026-05-10" id="INS-abc123" source="manual">
+<spec-entry category="coding" keywords="pattern,auth,jwt" date="2026-05-10" id="INS-abc123" source="manual">
 
 ### JWT refresh tokens must rotate on every use
 
@@ -402,7 +402,7 @@ Refresh-on-use prevents replay attacks.
 
 </spec-entry>
 
-<spec-entry roles="analyze" keywords="gotcha,redis,cache" date="2026-05-11" id="INS-def456" source="retrospective">
+<spec-entry category="debug" keywords="gotcha,redis,cache" date="2026-05-11" id="INS-def456" source="retrospective">
 
 ### Redis MULTI is not truly transactional
 

package/workflows/learn.md

@@ -118,7 +118,7 @@ First match wins. If nothing matches, category = `technique`.
 
 ```
 entry = <spec-entry
-  roles="{role}"
+  category="{category}"
   keywords="{category},{parsed --keywords values joined by comma}"
   date="{YYYY-MM-DD}"
   id="INS-{hex}"

package/workflows/map.md

@@ -30,7 +30,7 @@ Spawn 4 parallel `workflow-codebase-mapper` agents, each writing to `.workflow/r
 
 If `$ARGUMENTS` provided, pass as focus filter to each agent.
 
-Load project specs: `maestro spec load --role plan`
+Load project specs: `maestro spec load --category arch`
 
 Each agent spawned in parallel as `workflow-codebase-mapper` subagent with specs context.
 

package/workflows/milestone-complete.md

@@ -41,7 +41,7 @@ Archive completed milestone, move artifacts to history, and prepare for next.
 ## Step 2.5: Load Existing Learnings
 
 ```
-existing_learnings = maestro spec load --role implement
+existing_learnings = maestro spec load --category coding
 ```
 
 Check existing entries to avoid duplicates when appending in Step 3.
@@ -57,7 +57,7 @@ Check existing entries to avoid duplicates when appending in Step 3.
 
 2. Aggregate learnings and append to `.workflow/specs/learnings.md` using `<spec-entry>` closed-tag format. Each entry (strategy adjustment, pattern, or pitfall) follows this template:
    ```
-   <spec-entry roles="implement" keywords="{auto-extracted}" date="{YYYY-MM-DD}" source="milestone-complete">
+   <spec-entry category="learning" keywords="{auto-extracted}" date="{YYYY-MM-DD}" source="milestone-complete">
 
    ### {summary}
 

package/workflows/plan.md

@@ -74,7 +74,7 @@ default             → Create Mode: P1 → P2 → P3 → P4 → P4.5 → P5
 
 3. **Load project specs**
    ```
-   specs_content = maestro spec load --role plan
+   specs_content = maestro spec load --category arch
    ```
    Pass to planner agent as project constraints context.
 

package/workflows/quick.md

@@ -204,7 +204,7 @@ Report: "Context captured: ${QUICK_DIR}/context.md"
 ### Step 4.5: Load Project Specs
 
 ```
-specs_content = maestro spec load --role implement
+specs_content = maestro spec load --category coding
 ```
 
 Passed inline to planner agent in Step 5.

package/workflows/refactor.md

@@ -39,7 +39,7 @@ Write index.json: id, type="refactor", title, status="active", scope, plan (empt
 ### Step 2.5: Load Project Specs
 
 ```
-specs_content = maestro spec load --role implement
+specs_content = maestro spec load --category coding
 ```
 
 Used in Step 3 to detect pattern violations against project conventions.

package/workflows/retrospective.md

@@ -385,7 +385,7 @@ Create learnings.md with frontmatter (title, type: spec, roles: [implement]) if
 For each insight in `distilled_insights`, append a `<spec-entry>` to `.workflow/specs/learnings.md`:
 
 ```html
-<spec-entry roles="{insight.role}" keywords="{insight.category},{insight.tags joined by comma}" date="{YYYY-MM-DD}" id="{insight.id}" source="retrospective">
+<spec-entry category="{insight.category}" keywords="{insight.tags joined by comma}" date="{YYYY-MM-DD}" id="{insight.id}" source="retrospective">
 
 ### {insight.title}
 
@@ -408,7 +408,7 @@ Append learnings to `.workflow/specs/learnings.md` (shared with milestone-comple
 
 ```
 Append each insight to .workflow/specs/learnings.md as <spec-entry> with:
-  roles="implement", keywords (3-5 extracted), date, source="retrospective"
+  category="learning", keywords (3-5 extracted), date, source="retrospective"
   Body: title, summary, phase/lens/INS_id metadata
 
 Create file with roles frontmatter + "## Entries" header if it does not exist.
@@ -499,7 +499,7 @@ If `mode == "range"` or `--all`, loop Stages 3-8 per phase, then print aggregate
 ### spec-entry (in specs/learnings.md)
 
 ```html
-<spec-entry roles="implement" keywords="pattern,auth,jwt,security" date="2026-04-11" id="INS-a1b2c3d4" source="retrospective">
+<spec-entry category="coding" keywords="pattern,auth,jwt,security" date="2026-04-11" id="INS-a1b2c3d4" source="retrospective">
 
 ### JWT refresh tokens must rotate on every use
 

package/workflows/review.md

@@ -104,7 +104,7 @@ dimensions = --dimensions flag (comma-separated), or level defaults:
 **Skip if `--skip-specs` flag is set.**
 
 ```
-specs_content = maestro spec load --role review
+specs_content = maestro spec load --category review
 ```
 
 Pass specs_content to reviewer agents as quality standards context.

package/workflows/roadmap-common.md

@@ -15,7 +15,7 @@ Block if `.workflow/worktree-scope.json` exists — must run from main worktree.
 ### Load Specs
 
 ```
-specs_content = maestro spec load --role plan
+specs_content = maestro spec load --category arch
 ```
 
 Ensure phases respect architectural constraints.

package/workflows/specs-add.md

@@ -5,12 +5,11 @@ Add a `<spec-entry>` closed-tag entry to a single target spec file by category.
 ## Arguments
 
 ```
-$ARGUMENTS: "[--scope <scope>] [--uid <uid>] [--roles <csv>] <category> <content>"
+$ARGUMENTS: "[--scope <scope>] [--uid <uid>] <category> <content>"
 
 --scope  -- target scope: project (default) | global | team | personal
 --uid    -- user id for personal scope (auto-detected from git if omitted)
---roles  -- comma-separated applicable roles (implement,plan,test,review,analyze,explore)
-category -- one of: coding, arch, quality, debug, test, review, learning, tools
+category -- one of: coding, arch, quality, debug, test, review, learning
 content  -- free-text description of the entry
 ```
 
@@ -34,7 +33,6 @@ content  -- free-text description of the entry
 | `test` | `test-conventions.md` |
 | `review` | `review-standards.md` |
 | `learning` | `learnings.md` |
-| `tools` | `tools.md` |
 
 ## Prerequisites
 
@@ -85,13 +83,6 @@ Auto-extract 3-5 relevant keywords from the content:
 ```
 Entry format (closed-tag), date = YYYY-MM-DD, title = first meaningful phrase:
 
-When --roles provided (new format):
-<spec-entry roles="{role1},{role2}" keywords="{kw1},{kw2},{kw3}" date="{YYYY-MM-DD}">
-### {title}
-{content}
-</spec-entry>
-
-When --roles not provided (legacy format):
 <spec-entry category="{category}" keywords="{kw1},{kw2},{kw3}" date="{YYYY-MM-DD}">
 ### {title}
 {content}

package/workflows/specs-load.md

@@ -5,12 +5,12 @@ Load spec files filtered by category. Supports project, global, team, and person
 ## Arguments
 
 ```
-$ARGUMENTS: "[--scope <scope>] [--uid <uid>] [--role <role>] [keyword]"
+$ARGUMENTS: "[--scope <scope>] [--uid <uid>] [--category <category>] [keyword]"
 
 --scope     -- load scope: project (default) | global | team | personal
 --uid       -- user id for personal scope (auto-detected from git if omitted)
---role      -- filter by role: implement | plan | test | review | analyze | explore
-               Loads primary role doc in full + cross-file entries with matching roles attr
+--category  -- filter by category: coding | arch | test | review | debug | quality | learning
+               Loads category's primary doc in full + cross-file entries with matching category attr
 keyword     -- optional, grep within loaded specs for matching sections
 ```
 
@@ -18,18 +18,17 @@ keyword     -- optional, grep within loaded specs for matching sections
 
 Each category loads exactly one file per layer. Same mapping as spec-add.
 
-## File → Primary Role Mapping
+## File → Primary Category Mapping
 
-| File | Role |
-|------|------|
-| `coding-conventions.md` | implement |
-| `architecture-constraints.md` | plan |
+| 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 |
 
 ## Layer Order by Scope
 
@@ -46,12 +45,12 @@ Each layer is prefixed with a section header when multi-layer.
 
 ### Step 1: Parse Arguments
 
-Extract `--scope`, `--uid`, `--role <role>` and remaining text (keyword for grep).
+Extract `--scope`, `--uid`, `--category <category>` and remaining text (keyword for grep).
 
 ### Step 2: Load Specs via CLI
 
 ```bash
-maestro spec load --scope <scope> [--uid <uid>] [--role <role>] [--keyword <word>]
+maestro spec load --scope <scope> [--uid <uid>] [--category <category>] [--keyword <word>]
 ```
 
 If `maestro spec load` CLI is unavailable, read files directly from the resolved directory.

package/workflows/test-gen.md

@@ -9,7 +9,7 @@ Tests expose bugs -- fixing is for quality-debug or maestro-execute.
 ### Step 0: Load Project Specs
 
 ```
-specs_content = maestro spec load --role test
+specs_content = maestro spec load --category test
 ```
 
 Follow project test conventions in Step 4 (Generate Test Plan) and Step 5 (Write Tests).

package/workflows/tools-spec.md

@@ -4,48 +4,19 @@ Shared reference for tool spec registration and execution commands.
 
 ## Storage
 
-Tool specs are stored in `.workflow/specs/tools.md` as `<spec-entry>` blocks with per-entry `roles` attribute. The `tools.md` file has no primary role — entries are loaded via role matching.
+Tool specs are stored as knowhow documents in `.workflow/knowhow/` with `tool: true` in YAML frontmatter. Tool registration creates new knowhow files or promotes existing ones (via frontmatter update). The `category` field determines which `spec load --category` queries match this tool.
 
 ## Entry Format
 
-### Inline mode (short process, <10 steps)
-
-```xml
-<spec-entry roles="implement,test" keywords="payment,gateway,idempotency" date="YYYY-MM-DD">
-
-### Tool Name
-
-Use when {trigger condition / timing}.
-
-1. Step one
-2. Step two
-...
-
-</spec-entry>
-```
-
-### Ref mode (long process, >=10 steps or with code examples)
-
-Spec index entry in `tools.md`:
-```xml
-<spec-entry roles="implement" keywords="oauth,pkce,token" date="YYYY-MM-DD"
-  ref="knowhow/RCP-<slug>.md">
-
-### Tool Name
-
-Use when {trigger condition}. {scope summary — must fit within 200 chars for spec load display}.
-
-</spec-entry>
-```
-
-Referenced knowhow document (`knowhow/RCP-<slug>.md`):
+Knowhow document (`knowhow/RCP-<slug>.md`):
 ```yaml
 ---
 title: Tool Name
 type: recipe
+tool: true
 summary: "Use when {timing}. {scope description}"
 tags: [keyword1, keyword2]
-roles: [implement]
+category: coding
 ---
 
 ## Prerequisites
@@ -64,35 +35,38 @@ roles: [implement]
 ## Discovery Path
 
 ```
-Register → tools.md → spec load --role <role> / spec-injector auto-inject → agent discovers tool
+Register (knowhow/ + tool: true) → spec load --category / spec-injector auto-inject → agent discovers tool
 ```
 
 Agents discover tool specs via:
-- `spec load --role <role>` — returns entries matching the role
-- `spec-injector` hook — auto-injects at Agent launch based on agent type
-- `spec load --keyword <word>` — keyword search across all entries
+- `spec load --category <category>` — scans knowhow/ for `category + tool: true` matches
+- `spec-injector` hook — auto-injects at Agent launch based on agent type → category mapping
+- `spec load --keyword <word>` — keyword search across all entries (cross-category)
+
+## Category Reference
+
+`category` = **who consumes** (agent type), not what the content is about.
 
-## Role Reference
+| Category | Consumer Agent | Decision Question | Signal Words |
+|---|---|---|---|
+| coding | code-developer, workflow-executor | 开发者实现时需要？ | build, deploy, integrate, configure, api-contract |
+| test | tdd-developer, test-fix-agent | 测试者验证时需要？ | verify, validate, e2e, regression, idempotency |
+| review | workflow-reviewer | 审查者检查时需要？ | audit, checklist, compliance, quality-gate |
+| arch | workflow-planner | 规划者设计时需要？ | design, architecture, decompose, blueprint |
+| debug | debug-explore-agent | 调试者排查时需要？ | diagnose, trace, root-cause, reproduce |
 
-| Role | Agent types | Tool examples |
-|------|-------------|---------------|
-| implement | code-developer, workflow-executor | Build, deploy, integrate |
-| test | tdd-developer, test-fix-agent | Test flows, verification steps |
-| review | workflow-reviewer | Checklists, audit standards |
-| plan | workflow-planner | Design flows, analysis steps |
-| analyze | debug-explore-agent | Diagnostic flows, investigation |
+**Multi-consumer**: If tool serves multiple agents, split into separate docs with different categories.
 
 ## CLI Commands
 
 ```bash
-# Add inline tool spec
-maestro spec add tools "<title>" "<content>" --roles "<csv>" --keywords "<csv>"
+# Register new tool as knowhow document
+maestro knowhow add "knowhow/RCP-<slug>.md" --type recipe --tool
 
-# Add ref tool spec with knowhow
-maestro spec add tools "<title>" "<summary>" --roles "<csv>" --keywords "<csv>" \
-  --ref "knowhow/RCP-<slug>.md" --knowhow-type recipe
+# Promote existing knowhow to tool (in place)
+maestro wiki update <id> --frontmatter '{"tool": true, "category": "<cat>", "summary": "..."}'
 
-# Load tool specs
-maestro spec load --role <role>
-maestro spec load --role <role> --keyword <word>
+# Load specs by category
+maestro spec load --category <category>
+maestro spec load --category <category> --keyword <word>
 ```

package/workflows/ui-codify-knowhow.md

@@ -253,6 +253,6 @@ Open preview:
   file://${absolutePath}/preview.html
 
 Next steps:
-  maestro wiki list --role implement
+  maestro wiki list --category coding
   maestro spec load --keyword ${package_name}
 ```

package/workflows/ui-codify.md

@@ -220,6 +220,6 @@ Open preview:
   file://{absolute_path}/preview.html
 
 Next steps:
-  maestro wiki list --role implement    # Browse by role
+  maestro wiki list --category coding    # Browse by category
   maestro spec load --keyword {package_name}    # Load related specs
 ```

package/workflows/verify.md

@@ -42,7 +42,7 @@ Milestone mode creates output dir: .workflow/scratch/verify-{milestone_slug}-{da
 ## V0: Load Project Specs
 
 ```
-specs_content = maestro spec load --role review
+specs_content = maestro spec load --category review
 ```
 
 Pass specs_content to verifier agent as quality standards context.

package/.claude/commands/maestro-link-coordinate.md

@@ -1,71 +0,0 @@
----
-name: maestro-link-coordinate
-description: Execute command chain nodes step by step
-argument-hint: "\"intent text\" [--list] [-c [sessionId]] [--chain <name>] [--tool <tool>] [-y]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
----
-<purpose>
-Step-mode workflow coordinator using `maestro coordinate` CLI subcommands (start/next/status).
-Walks chain graphs node by node — each command node executed via `maestro delegate` internally.
-Decision/gate/eval nodes auto-resolve between steps. Session persisted for resume.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/maestro-link-coordinate.md
-</required_reading>
-
-<context>
-$ARGUMENTS — user intent text, or flags.
-
-**Flags:**
-- `--list` — List all available chain graphs
-- `-c` / `--continue [sessionId]` — Resume step_paused session via `coordinate next`
-- `--chain <name>` — Force a specific chain graph
-- `--tool <tool>` — CLI tool override (default: claude)
-- `-y` / `--yes` — Auto mode
-
-**CLI endpoints used:**
-- `maestro coordinate list` — enumerate chains
-- `maestro coordinate start "intent" --chain X` — begin step-mode session
-- `maestro coordinate next [sessionId]` — advance one step
-- `maestro coordinate status [sessionId]` — query state
-- `maestro coordinate run "intent"` — autonomous full run
-- `maestro coordinate watch <sessionId> [--follow]` — read-only event tail (separate from driver loop)
-- `maestro coordinate report` — agent-invoked command-node result writer (authoritative result channel)
-
-**Internal walker capabilities (invisible to driver loop):**
-- Prompt assembly owned by the walker (main flow) for both command and decision nodes
-- Decision nodes auto-resolve via `strategy: 'expr'` (fast path) with LLM decider fallback when expr has no match and no default edge, or explicit `strategy: 'llm'`
-- Walker events published to a file/SQLite broker for `watch` observers
-- LLM decision in step mode is synchronous — avoid tight per-step deadlines
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/maestro-link-coordinate.md' completely.
-</execution>
-
-<error_codes>
-| Code | Severity | Description | Recovery |
-|------|----------|-------------|----------|
-| E001 | error | No intent and no --list/--chain | Suggest --list |
-| E002 | error | Chain graph not found | Show list output |
-| E003 | error | Step execution failed | Check status, retry next |
-| E004 | error | Resume session not found | List sessions |
-| E005 | error | CLI endpoint unavailable | Check maestro installation |
-</error_codes>
-
-<success_criteria>
-- [ ] Chain graph loaded via `maestro coordinate start`
-- [ ] Each step executed via `maestro coordinate next` loop
-- [ ] JSON output parsed for session tracking
-- [ ] Decision nodes auto-resolved between steps
-- [ ] Session persisted and resumable via `-c`
-- [ ] Completion summary displayed
-</success_criteria>