maestro-flow 0.3.42 → 0.3.44

package/workflows/retrospective.md

@@ -1,8 +1,8 @@
 # Retrospective Workflow
 
-Multi-lens 复盘 of completed phase artifacts. Consumes existing execution outputs (verification.json, review.json, issues.jsonl, .summaries/, state.json, uat.md, plan.json) and routes distilled insights into the spec / note / issue / lessons stores.
+Multi-lens 复盘 of completed phase artifacts. Consumes existing execution outputs (verification.json, review.json, issues.jsonl, .summaries/, state.json, uat.md, plan.json) and routes distilled insights into the spec / note / issue / knowhow stores.
 
-This is a **post-execution analysis** workflow. It reads only — until the routing stage, where it writes new spec stubs, issue rows, memory entries, and lesson rows. It never modifies existing phase artifacts.
+This is a **post-execution analysis** workflow. It reads only — until the routing stage, where it writes new spec stubs, issue rows, memory entries, and knowhow entries. It never modifies existing phase artifacts.
 
 ---
 
@@ -304,24 +304,24 @@ Accept all? [Y/n/i for individual]
 
 #### Target: spec
 
-Route spec-routed insights as `<spec-entry>` entries into the appropriate category file. Map insight type to category:
-- `pattern` / `convention` → `coding`
-- `adr-candidate` / architecture → `arch`
-- quality-related → `quality`
+Route spec-routed insights as `<spec-entry>` entries into the appropriate target file. Map insight type to roles:
+- `pattern` / `convention` → `implement`
+- `adr-candidate` / architecture → `plan`
+- quality-related → `review`
 
 ```
-Map insight type → category → target file:
-  pattern/convention → coding → coding-conventions.md
-  adr-candidate/architecture → arch → arch-decisions.md
-  quality-related → quality → quality-conventions.md
+Map insight type → roles → target file:
+  pattern/convention → implement → coding-conventions.md
+  adr-candidate/architecture → plan → arch-decisions.md
+  quality-related → review → quality-conventions.md
 
 Append <spec-entry> to .workflow/specs/{target_file} with:
-  category, keywords (3-5 extracted from title+summary), date, source="retrospective"
+  roles, keywords (3-5 extracted from title+summary), date, source="retrospective"
   Body: insight title, summary, evidence refs, phase/lens/INS_id/confidence metadata
 
-Create target file with category frontmatter if it does not exist.
+Create target file with roles frontmatter if it does not exist.
 
-insight.routed_id = "{category_file}#INS-{INS_id}"
+insight.routed_id = "{target_file}#INS-{INS_id}"
 ```
 
 #### Target: note
@@ -369,26 +369,38 @@ After all routings complete, re-write `retrospective.json` with the `routed_id`
 
 ---
 
-## Stage 7: persist_lessons
+## Stage 7: persist_insights
 
-Append every distilled insight (regardless of routing target, including `routed_to: "none"`) to the lessons store.
+Append every distilled insight (regardless of routing target, including `routed_to: "none"`) to the knowhow store.
 
 ### Bootstrap
 
 ```
-Ensure .workflow/learning/lessons.jsonl and learning-index.json exist.
-Initialize learning-index.json with {"entries":[],"_metadata":{"created":"...","version":"1.0"}} if new.
+Ensure .workflow/specs/ exists and learnings.md exists.
+Create learnings.md with frontmatter (title, type: spec, roles: [implement]) if new.
 ```
 
-### Append rows
+### Append entries
 
-For each insight in `distilled_insights`, append a JSON line to `.workflow/learning/lessons.jsonl` with fields:
-`{ id, phase, phase_slug, lens, category, title, summary, confidence, tags, evidence_refs, routed_to, routed_id, source: "retrospective", captured_at }`
+For each insight in `distilled_insights`, append a `<spec-entry>` to `.workflow/specs/learnings.md`:
 
-### Update index
+```html
+<spec-entry roles="{insight.role}" keywords="{insight.category},{insight.tags joined by comma}" date="{YYYY-MM-DD}" id="{insight.id}" source="retrospective">
 
-Append an entry to `.workflow/learning/learning-index.json` entries[] for each new insight:
-`{ id, type: "insight", timestamp, file: "lessons.jsonl", summary (80 chars), tags, lens, category, phase, phase_slug, confidence, routed_to, routed_id }`
+### {insight.title}
+
+{insight.summary}
+
+- **Phase**: {phase} ({phase_slug})
+- **Lens**: {insight.lens}
+- **Confidence**: {insight.confidence}
+- **Evidence**: {insight.evidence_refs}
+- **Routed to**: {insight.routed_to} ({insight.routed_id or "—"})
+
+</spec-entry>
+```
+
+WikiIndexer auto-indexes each entry — no manual index update required.
 
 ### Backward-compat append to specs/learnings.md
 
@@ -396,10 +408,10 @@ Append learnings to `.workflow/specs/learnings.md` (shared with milestone-comple
 
 ```
 Append each insight to .workflow/specs/learnings.md as <spec-entry> with:
-  category="learning", keywords (3-5 extracted), date, source="retrospective"
+  roles="implement", keywords (3-5 extracted), date, source="retrospective"
   Body: title, summary, phase/lens/INS_id metadata
 
-Create file with category frontmatter + "## Entries" header if it does not exist.
+Create file with roles frontmatter + "## Entries" header if it does not exist.
 ```
 
 ---
@@ -409,12 +421,12 @@ Create file with category frontmatter + "## Entries" header if it does not exist
 Print confirmation banner and route the user.
 
 ```
-Print banner: phase, lenses run, insight count, routing summary (spec/note/issue/lesson counts with target paths), output file paths.
+Print banner: phase, lenses run, insight count, routing summary (spec/note/issue/knowhow counts with target paths), output file paths.
 
 Suggested next steps:
   manage-status                              — Review project state
   manage-issue list --source retrospective   — Triage created issues
-  manage-learn list                          — Browse the lessons library
+  manage-learn list                          — Browse the insights library
   maestro-milestone-audit                    — Audit milestone if all phases done
 ```
 
@@ -484,39 +496,21 @@ If `mode == "range"` or `--all`, loop Stages 3-8 per phase, then print aggregate
 }
 ```
 
-### lessons.jsonl row
+### spec-entry (in specs/learnings.md)
 
-One JSON object per line:
+```html
+<spec-entry roles="implement" keywords="pattern,auth,jwt,security" date="2026-04-11" id="INS-a1b2c3d4" source="retrospective">
 
-```json
-{"id":"INS-a1b2c3d4","phase":1,"phase_slug":"01-auth","lens":"technical","category":"pattern","title":"JWT refresh tokens must rotate on every use","summary":"...","confidence":"high","tags":["auth","jwt","security"],"evidence_refs":["..."],"routed_to":"spec","routed_id":"coding-conventions.md#INS-a1b2c3d4","source":"retrospective","captured_at":"2026-04-11T10:00:00Z"}
-```
+### JWT refresh tokens must rotate on every use
 
-### learning-index.json
+Refresh-on-use prevents replay attacks. Implemented in src/auth/refresh.ts; should become a project-wide convention.
 
-```json
-{
-  "entries": [
-    {
-      "id": "INS-a1b2c3d4",
-      "type": "insight",
-      "timestamp": "2026-04-11T10:00:00Z",
-      "file": "lessons.jsonl",
-      "summary": "JWT refresh tokens must rotate on every use",
-      "tags": ["auth", "jwt", "security"],
-      "lens": "technical",
-      "category": "pattern",
-      "phase": 1,
-      "phase_slug": "01-auth",
-      "confidence": "high",
-      "routed_to": "spec",
-      "routed_id": "coding-conventions.md#INS-a1b2c3d4"
-    }
-  ],
-  "_metadata": {
-    "created": "2026-04-11T10:00:00Z",
-    "version": "1.0"
-  }
-}
+- **Phase**: 1 (01-auth)
+- **Lens**: technical
+- **Confidence**: high
+- **Evidence**: .workflow/scratch/plan-auth-2026-04-15/verification.json#gaps[2]
+- **Routed to**: spec (coding-conventions.md#INS-a1b2c3d4)
+
+</spec-entry>
 ```
 

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 --category review
+specs_content = maestro spec load --role 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 --category arch
+specs_content = maestro spec load --role plan
 ```
 
 Ensure phases respect architectural constraints.

package/workflows/specs-add.md

@@ -5,11 +5,12 @@ Add a `<spec-entry>` closed-tag entry to a single target spec file by category.
 ## Arguments
 
 ```
-$ARGUMENTS: "[--scope <scope>] [--uid <uid>] <category> <content>"
+$ARGUMENTS: "[--scope <scope>] [--uid <uid>] [--roles <csv>] <category> <content>"
 
 --scope  -- target scope: project (default) | global | team | personal
 --uid    -- user id for personal scope (auto-detected from git if omitted)
-category -- one of: coding, arch, quality, debug, test, review, learning
+--roles  -- comma-separated applicable roles (implement,plan,test,review,analyze,explore)
+category -- one of: coding, arch, quality, debug, test, review, learning, tools
 content  -- free-text description of the entry
 ```
 
@@ -33,6 +34,7 @@ content  -- free-text description of the entry
 | `test` | `test-conventions.md` |
 | `review` | `review-standards.md` |
 | `learning` | `learnings.md` |
+| `tools` | `tools.md` |
 
 ## Prerequisites
 
@@ -83,6 +85,13 @@ 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>] [--category <type>] [keyword]"
+$ARGUMENTS: "[--scope <scope>] [--uid <uid>] [--role <role>] [keyword]"
 
 --scope     -- load scope: project (default) | global | team | personal
 --uid       -- user id for personal scope (auto-detected from git if omitted)
---category  -- filter by category (1:1 mapping to file):
-               coding | arch | quality | debug | test | review | learning | all
+--role      -- filter by role: implement | plan | test | review | analyze | explore
+               Loads primary role doc in full + cross-file entries with matching roles attr
 keyword     -- optional, grep within loaded specs for matching sections
 ```
 
@@ -18,16 +18,18 @@ keyword     -- optional, grep within loaded specs for matching sections
 
 Each category loads exactly one file per layer. Same mapping as spec-add.
 
-| Category | File loaded |
-|----------|------------|
-| `coding` | `coding-conventions.md` |
-| `arch` | `architecture-constraints.md` |
-| `quality` | `quality-rules.md` |
-| `debug` | `debug-notes.md` |
-| `test` | `test-conventions.md` |
-| `review` | `review-standards.md` |
-| `learning` | `learnings.md` |
-| `all` (default) | All `.md` files in specs/ |
+## 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)_ |
 
 ## Layer Order by Scope
 
@@ -44,12 +46,12 @@ Each layer is prefixed with a section header when multi-layer.
 
 ### Step 1: Parse Arguments
 
-Extract `--scope`, `--uid`, `--category <type>` and remaining text (keyword for grep).
+Extract `--scope`, `--uid`, `--role <role>` and remaining text (keyword for grep).
 
 ### Step 2: Load Specs via CLI
 
 ```bash
-maestro spec load --scope <scope> [--uid <uid>] [--category <category>] [--keyword <word>]
+maestro spec load --scope <scope> [--uid <uid>] [--role <role>] [--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 --category test
+specs_content = maestro spec load --role test
 ```
 
 Follow project test conventions in Step 4 (Generate Test Plan) and Step 5 (Write Tests).

package/workflows/tools-spec.md

@@ -0,0 +1,98 @@
+# Tool Spec Reference
+
+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.
+
+## 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`):
+```yaml
+---
+title: Tool Name
+type: recipe
+summary: "Use when {timing}. {scope description}"
+tags: [keyword1, keyword2]
+roles: [implement]
+---
+
+## Prerequisites
+...
+
+## Steps
+1. ...
+```
+
+## Description Rules
+
+- First line after `### Title` must state **when to use** this tool
+- For ref entries: `spec load` shows only the first 200 chars after heading — timing must be in that window
+- For ref knowhow docs: YAML `summary` field is shown by `wiki list` and wiki-role-loader hook
+
+## Discovery Path
+
+```
+Register → tools.md → spec load --role <role> / 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
+
+## Role Reference
+
+| 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 |
+
+## 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
+
+# Load tool specs
+maestro spec load --role <role>
+maestro spec load --role <role> --keyword <word>
+```