maestro-flow 0.3.44 → 0.3.45

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 knowhow files, not spec entries. 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,31 @@ roles: [implement]
 ## Discovery Path
 
 ```
-Register → tools.md → spec load --role <role> / spec-injector auto-inject → agent discovers tool
+Register → tools.md → spec load --category <category> / spec-injector auto-inject → agent discovers tool
 ```
 
 Agents discover tool specs via:
-- `spec load --role <role>` — returns entries matching the role
+- `spec load --category <category>` — returns entries matching the category
 - `spec-injector` hook — auto-injects at Agent launch based on agent type
 - `spec load --keyword <word>` — keyword search across all entries
 
-## Role Reference
+## Category Reference
 
-| Role | Agent types | Tool examples |
-|------|-------------|---------------|
-| implement | code-developer, workflow-executor | Build, deploy, integrate |
+| Category | Agent types | Tool examples |
+|----------|-------------|---------------|
+| coding | 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 |
+| arch | workflow-planner | Design flows, analysis steps |
+| debug | debug-explore-agent | Diagnostic flows, investigation |
 
 ## CLI Commands
 
 ```bash
-# Add inline tool spec
-maestro spec add tools "<title>" "<content>" --roles "<csv>" --keywords "<csv>"
-
-# Add ref tool spec with knowhow
-maestro spec add tools "<title>" "<summary>" --roles "<csv>" --keywords "<csv>" \
-  --ref "knowhow/RCP-<slug>.md" --knowhow-type recipe
+# Register tool as knowhow document
+maestro knowhow add "knowhow/RCP-<slug>.md" --type recipe --tool
 
-# 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.