maestro-flow 0.3.43 → 0.3.44

package/.codex/skills/quality-refactor/SKILL.md

@@ -1,151 +1,151 @@
----
-name: quality-refactor
-description: Reduce tech debt with reflection-driven iteration
-argument-hint: "<phase|--dir path> [--max-iterations N]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion
----
-
-<purpose>
-Iterative refactoring cycle: analyze scope for tech debt -> plan refactoring tasks -> execute each with test verification -> reflect on strategy per round -> repeat if needed. Every change is verified against existing tests. Failed changes are reverted and retried with adjusted strategy.
-</purpose>
-
-<context>
-$ARGUMENTS -- module path, feature area, or "all", plus optional flags.
-
-**Usage**:
-
-```bash
-$quality-refactor "src/auth"                    # module path scope
-$quality-refactor "authentication"              # feature area scope
-$quality-refactor "all"                         # full codebase scan
-$quality-refactor "src/api --max-iterations 5"  # limit iteration rounds
-$quality-refactor "--dir .workflow/scratch/refactor-auth-2026-03-18"  # resume existing
-```
-
-**Flags**:
-- `<phase|scope>`: Module path, feature area, or "all"
-- `--dir path`: Resume existing refactor scratch directory
-- `--max-iterations N`: Max refactoring rounds (default: 3)
-
-**Output**: `.workflow/scratch/refactor-{slug}-{date}/` with index.json, plan.json, reflection-log.md, .task/, .summaries/
-</context>
-
-<invariants>
-1. **Test after every change** -- zero regressions tolerated
-2. **Revert on failure** -- never leave broken state
-3. **Max 2 retries per task** with strategy adjustment
-4. **Reflection-driven** -- every round records strategy, outcome, adjustment
-5. **User approval required** before execution (Step 4)
-6. **Quick wins first** -- order by risk (low first) and dependency
-7. **Agent calls use `run_in_background: false`** for synchronous execution
-8. **Incremental safety** -- each task is independently safe to apply or revert
-</invariants>
-
-<execution>
-
-### Step 1: Parse Scope
-
-1. Parse `$ARGUMENTS` for scope and flags
-2. If `--dir` provided: resume existing scratch directory (skip to Step 5)
-3. Scope types:
-   - Module path (e.g., "src/auth") -> scan that directory
-   - Feature area (e.g., "authentication") -> search for related files
-   - "all" -> full codebase scan
-4. If empty: prompt user via AskUserQuestion with options (Module path / Feature area / Full codebase)
-5. Detect `--max-iterations N` (default: 3)
-
-### Step 2: Create Scratch Directory
-
-Create `.workflow/scratch/refactor-{slug}-{date}/` with `.task/` and `.summaries/` subdirectories. Write `index.json` with type "refactor", scope, status "active", plan/execution/reflection counters.
-
-### Step 3: Scope Analysis
-
-Load project specs if available (`maestro spec load --category coding`).
-
-Analyze scope for tech debt categories:
-
-| Category | What to Look For |
-|----------|-----------------|
-| Duplication | Repeated code blocks, copy-paste patterns |
-| Complexity | Long functions, deep nesting, high cyclomatic complexity |
-| Naming | Inconsistent naming, unclear identifiers |
-| Dependencies | Circular deps, tight coupling, god objects |
-| Dead code | Unused functions, unreachable branches |
-| Pattern violations | Inconsistent with project conventions |
-
-Present analysis summary table with category, count, severity.
-Confirm with user before proceeding.
-
-### Step 4: Plan Refactoring
-
-1. Write `plan.json` with scope, total_tasks, strategy ("incremental -- each task independently safe")
-2. For each identified issue, create `.task/TASK-{NNN}.json`:
-   - id, title, status (pending), type (refactor), category
-   - description, read_first files, files with action/target/change
-   - convergence.criteria (grep-verifiable), verification command
-   - implementation steps, risk level
-3. Order: high risk last, dependencies respected, quick wins first
-4. Update `index.json` plan fields
-5. Present plan to user via AskUserQuestion -- show affected files, risk areas, ask for approval
-
-### Step 5: Execute with Reflection
-
-Initialize `reflection-log.md` if not exists.
-
-For each task in order:
-
-**5a. Execute refactoring:** Spawn Agent to implement the refactoring — read `read_first` files, apply changes to targets, follow convergence criteria exactly.
-
-**5b. Run test suite** (npm test / pytest / go test as appropriate).
-
-**5c. Record in reflection-log.md:** Round number, task title, strategy, result (pass/fail), test outcome, adjustment for next round, files changed.
-
-**5d. Handle test failures:**
-1. Revert the change
-2. Record failure + strategy adjustment in reflection-log.md
-3. Retry with adjusted strategy (max 2 retries per task)
-4. If still failing: mark task "blocked", continue to next
-
-**5e. Update state:**
-- `.task/TASK-{NNN}.json` status -> "completed" or "blocked"
-- `.summaries/TASK-{NNN}-summary.md` written
-- `index.json` execution and reflection fields updated
-
-### Step 6: Final Verification
-
-Run full test suite. Record final state in reflection-log.md: test result, tasks completed/total, tasks blocked, key learnings.
-
-### Step 7: Complete and Report
-
-Update `index.json`: status -> "completed", final execution/reflection counts.
-
-Display report: scope, tasks completed/blocked, reflection rounds, strategy adjustments, test status, key learnings from reflection-log.md, artifact paths (`{REFACTOR_DIR}/reflection-log.md`, `{REFACTOR_DIR}/.summaries/`).
-
-**Next-step routing:**
-
-| Result | Next Step |
-|--------|-----------|
-| All tests pass, refactoring complete | `$quality-sync` (update codebase docs) |
-| Test failures remain after refactor | `$quality-debug "{scope}"` |
-| No test suite available for scope | `$quality-auto-test "{phase}"` |
-| Partial completion (some blocked) | `$quality-debug "{scope}"` for blocked tasks |
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Scope/description required | Prompt user for module path, feature area, or "all" |
-| E002 | error | Test suite not available | Suggest creating tests first, or proceed with manual verification |
-| W001 | warning | Partial test coverage | Note uncovered areas, proceed with extra caution |
-</error_codes>
-
-<success_criteria>
-- [ ] Scope resolved and scratch directory created
-- [ ] Tech debt analysis completed with categorized findings
-- [ ] Refactoring plan approved by user
-- [ ] Each task executed with test verification
-- [ ] Failed changes reverted, retried with adjusted strategy
-- [ ] Reflection log records every round's strategy and outcome
-- [ ] Final test suite passes with zero regressions
-- [ ] Completion report with key learnings displayed
-</success_criteria>
+---
+name: quality-refactor
+description: Reduce tech debt with reflection-driven iteration
+argument-hint: "<phase|--dir path> [--max-iterations N]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion
+---
+
+<purpose>
+Iterative refactoring cycle: analyze scope for tech debt -> plan refactoring tasks -> execute each with test verification -> reflect on strategy per round -> repeat if needed. Every change is verified against existing tests. Failed changes are reverted and retried with adjusted strategy.
+</purpose>
+
+<context>
+$ARGUMENTS -- module path, feature area, or "all", plus optional flags.
+
+**Usage**:
+
+```bash
+$quality-refactor "src/auth"                    # module path scope
+$quality-refactor "authentication"              # feature area scope
+$quality-refactor "all"                         # full codebase scan
+$quality-refactor "src/api --max-iterations 5"  # limit iteration rounds
+$quality-refactor "--dir .workflow/scratch/refactor-auth-2026-03-18"  # resume existing
+```
+
+**Flags**:
+- `<phase|scope>`: Module path, feature area, or "all"
+- `--dir path`: Resume existing refactor scratch directory
+- `--max-iterations N`: Max refactoring rounds (default: 3)
+
+**Output**: `.workflow/scratch/refactor-{slug}-{date}/` with index.json, plan.json, reflection-log.md, .task/, .summaries/
+</context>
+
+<invariants>
+1. **Test after every change** -- zero regressions tolerated
+2. **Revert on failure** -- never leave broken state
+3. **Max 2 retries per task** with strategy adjustment
+4. **Reflection-driven** -- every round records strategy, outcome, adjustment
+5. **User approval required** before execution (Step 4)
+6. **Quick wins first** -- order by risk (low first) and dependency
+7. **Agent calls use `run_in_background: false`** for synchronous execution
+8. **Incremental safety** -- each task is independently safe to apply or revert
+</invariants>
+
+<execution>
+
+### Step 1: Parse Scope
+
+1. Parse `$ARGUMENTS` for scope and flags
+2. If `--dir` provided: resume existing scratch directory (skip to Step 5)
+3. Scope types:
+   - Module path (e.g., "src/auth") -> scan that directory
+   - Feature area (e.g., "authentication") -> search for related files
+   - "all" -> full codebase scan
+4. If empty: prompt user via AskUserQuestion with options (Module path / Feature area / Full codebase)
+5. Detect `--max-iterations N` (default: 3)
+
+### Step 2: Create Scratch Directory
+
+Create `.workflow/scratch/refactor-{slug}-{date}/` with `.task/` and `.summaries/` subdirectories. Write `index.json` with type "refactor", scope, status "active", plan/execution/reflection counters.
+
+### Step 3: Scope Analysis
+
+Load project specs if available (`maestro spec load --role implement`).
+
+Analyze scope for tech debt categories:
+
+| Category | What to Look For |
+|----------|-----------------|
+| Duplication | Repeated code blocks, copy-paste patterns |
+| Complexity | Long functions, deep nesting, high cyclomatic complexity |
+| Naming | Inconsistent naming, unclear identifiers |
+| Dependencies | Circular deps, tight coupling, god objects |
+| Dead code | Unused functions, unreachable branches |
+| Pattern violations | Inconsistent with project conventions |
+
+Present analysis summary table with category, count, severity.
+Confirm with user before proceeding.
+
+### Step 4: Plan Refactoring
+
+1. Write `plan.json` with scope, total_tasks, strategy ("incremental -- each task independently safe")
+2. For each identified issue, create `.task/TASK-{NNN}.json`:
+   - id, title, status (pending), type (refactor), category
+   - description, read_first files, files with action/target/change
+   - convergence.criteria (grep-verifiable), verification command
+   - implementation steps, risk level
+3. Order: high risk last, dependencies respected, quick wins first
+4. Update `index.json` plan fields
+5. Present plan to user via AskUserQuestion -- show affected files, risk areas, ask for approval
+
+### Step 5: Execute with Reflection
+
+Initialize `reflection-log.md` if not exists.
+
+For each task in order:
+
+**5a. Execute refactoring:** Spawn Agent to implement the refactoring — read `read_first` files, apply changes to targets, follow convergence criteria exactly.
+
+**5b. Run test suite** (npm test / pytest / go test as appropriate).
+
+**5c. Record in reflection-log.md:** Round number, task title, strategy, result (pass/fail), test outcome, adjustment for next round, files changed.
+
+**5d. Handle test failures:**
+1. Revert the change
+2. Record failure + strategy adjustment in reflection-log.md
+3. Retry with adjusted strategy (max 2 retries per task)
+4. If still failing: mark task "blocked", continue to next
+
+**5e. Update state:**
+- `.task/TASK-{NNN}.json` status -> "completed" or "blocked"
+- `.summaries/TASK-{NNN}-summary.md` written
+- `index.json` execution and reflection fields updated
+
+### Step 6: Final Verification
+
+Run full test suite. Record final state in reflection-log.md: test result, tasks completed/total, tasks blocked, key learnings.
+
+### Step 7: Complete and Report
+
+Update `index.json`: status -> "completed", final execution/reflection counts.
+
+Display report: scope, tasks completed/blocked, reflection rounds, strategy adjustments, test status, key learnings from reflection-log.md, artifact paths (`{REFACTOR_DIR}/reflection-log.md`, `{REFACTOR_DIR}/.summaries/`).
+
+**Next-step routing:**
+
+| Result | Next Step |
+|--------|-----------|
+| All tests pass, refactoring complete | `$quality-sync` (update codebase docs) |
+| Test failures remain after refactor | `$quality-debug "{scope}"` |
+| No test suite available for scope | `$quality-auto-test "{phase}"` |
+| Partial completion (some blocked) | `$quality-debug "{scope}"` for blocked tasks |
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Scope/description required | Prompt user for module path, feature area, or "all" |
+| E002 | error | Test suite not available | Suggest creating tests first, or proceed with manual verification |
+| W001 | warning | Partial test coverage | Note uncovered areas, proceed with extra caution |
+</error_codes>
+
+<success_criteria>
+- [ ] Scope resolved and scratch directory created
+- [ ] Tech debt analysis completed with categorized findings
+- [ ] Refactoring plan approved by user
+- [ ] Each task executed with test verification
+- [ ] Failed changes reverted, retried with adjusted strategy
+- [ ] Reflection log records every round's strategy and outcome
+- [ ] Final test suite passes with zero regressions
+- [ ] Completion report with key learnings displayed
+</success_criteria>

package/.codex/skills/quality-retrospective/SKILL.md

@@ -8,7 +8,7 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 <purpose>
 Multi-lens retrospective for completed phases. Context-Agent Fork loads phase artifacts once;
 four parallel lens agents (technical, process, quality, decision) analyze independently;
-synthesizer distills insights; outputs are routed to spec stubs, knowhow tips, issues, and lessons.jsonl.
+synthesizer distills insights; outputs are routed to spec stubs, knowhow tips, issues, and specs/learnings.md.
 
 ```
 +------------------------------------------------------------------+
@@ -71,8 +71,8 @@ When `-y`: Accept all routing recommendations without prompting. Route all insig
 - `.workflow/specs/{category-file}.md` -- `<spec-entry>` entries appended to matching category files (one per spec-routed insight)
 - `.workflow/issues/issues.jsonl` -- appended issue rows (`source: "retrospective"`)
 - `.workflow/knowhow/TIP-*.md` -- knowhow tips (via `manage-knowhow-capture` skill)
-- `.workflow/learning/lessons.jsonl` -- append-only insight log
-- `.workflow/learning/learning-index.json` -- updated searchable index
+- `.workflow/specs/learnings.md` -- append-only insight log
+- Index auto-maintained by WikiIndexer
 
 **Storage read (never modified)** — all resolved via `state.json.artifacts[]`:
 ```
@@ -125,7 +125,7 @@ Each artifact's type determines its outputs at `.workflow/{a.path}/`:
 7. **Archive before overwrite**: Move existing retrospective.{md,json} to `.history/` with timestamp before writing new ones
 8. **Spec learnings.md backward-compat**: Append to it only if it already exists -- never create it
 9. **Route confirmation**: Unless `-y`, present routing table and ask per-group before writing spec/issue/knowhow
-10. **Lessons always written**: Append to `lessons.jsonl` regardless of `--no-route` -- routing only controls spec/issue/knowhow creation
+10. **Lessons always written**: Append to `specs/learnings.md` regardless of `--no-route` -- routing only controls spec/issue/knowhow creation
 </invariants>
 
 <execution>
@@ -250,7 +250,7 @@ Write two files to `{target_dir}/`:
 - **retrospective.json**: phase, slug, timestamp, lenses_run, metrics, findings_by_lens, distilled_insights, routing_summary
 - **retrospective.md**: Header with phase/slug/timestamp, metrics table (tasks completed, test pass rate, review issues, UAT scenarios), findings by lens, distilled insights, routing summary
 
-Append each insight to `.workflow/learning/lessons.jsonl` and update `learning-index.json`.
+Append each insight to `.workflow/specs/learnings.md`.
 
 If `.workflow/specs/learnings.md` already exists, append each insight as `<spec-entry>` (category=`learning`, auto-extract keywords, date=today, source=`retrospective`). Never create the file -- only append if it exists.
 
@@ -287,6 +287,6 @@ Next steps: `$manage-status`, `$manage-issue "list --source retrospective"`, `$m
 - [ ] Synthesizer produces deduplicated insights with stable INS-ids
 - [ ] Routing applied per insight (spec/issue/knowhow/none) with confirmation
 - [ ] retrospective.{md,json} written to phase directory
-- [ ] Lessons appended to lessons.jsonl regardless of --no-route flag
+- [ ] Lessons appended to specs/learnings.md regardless of --no-route flag
 - [ ] Existing retrospective archived before overwrite
 </success_criteria>

package/.codex/skills/spec-add/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: spec-add
-description: Add spec entry by category
-argument-hint: "<category> <content>"
+description: Add spec entry by category with role tagging
+argument-hint: "<category> <content> [--roles <csv>]"
 allowed-tools: Read, Write, Bash, Glob, Grep
 ---
 
@@ -15,9 +15,9 @@ $spec-add "arch Use Zod for runtime validation over io-ts"
 $spec-add "quality All API endpoints must return structured error objects"
 ```
 
-**Valid categories**: coding, arch, quality, debug, test, review, learning, bug, pattern, decision, rule, validation.
+**Valid categories**: coding, arch, quality, debug, test, review, learning, tools, bug, pattern, decision, rule, validation.
 
-**CLI alternative**: `maestro spec add <category> "<title>" "<content>" --keywords kw1,kw2 --source <src>`. Used by workflow agents (analyze, plan, execute) for programmatic spec enrichment.
+**CLI alternative**: `maestro spec add <category> "<title>" "<content>" --keywords kw1,kw2 --roles implement,test --source <src>`. Used by workflow agents (analyze, plan, execute) for programmatic spec enrichment.
 </purpose>
 
 <context>
@@ -33,6 +33,7 @@ $ARGUMENTS — `<category> <content>` where category selects the target file.
 | `test` | `test-conventions.md` |
 | `review` | `review-standards.md` |
 | `learning` | `learnings.md` |
+| `tools` | `tools.md` |
 | `bug` | `learnings.md` |
 | `pattern` | `coding-conventions.md` |
 | `decision` | `architecture-constraints.md` |
@@ -40,6 +41,8 @@ $ARGUMENTS — `<category> <content>` where category selects the target file.
 | `validation` | `quality-rules.md` |
 
 Extended types (`bug`, `pattern`, `decision`, `rule`, `validation`) are stored in the file of their closest core category but retain their specific category in the `<spec-entry>` tag.
+
+**--roles option**: When `--roles` is provided, the entry uses `roles` attr instead of `category` attr. This declares which agent roles should load this entry via `spec load --role`.
 </context>
 
 <execution>
@@ -70,6 +73,16 @@ Auto-extract 3-5 relevant keywords from the content. Keywords should be:
 Append `<spec-entry>` closed-tag block to target file:
 
 ```markdown
+<!-- With --roles (new format): -->
+<spec-entry roles="{role1},{role2}" keywords="{kw1},{kw2},{kw3}" date="{YYYY-MM-DD}">
+
+### {title extracted from content}
+
+{content}
+
+</spec-entry>
+
+<!-- Without --roles (legacy format): -->
 <spec-entry category="{category}" keywords="{kw1},{kw2},{kw3}" date="{YYYY-MM-DD}">
 
 ### {title extracted from content}

package/.codex/skills/spec-load/SKILL.md

@@ -1,45 +1,41 @@
 ---
 name: spec-load
 description: Load specs and lessons for current context
-argument-hint: "[--category <type>] [--keyword <word>]"
+argument-hint: "[--role <role>] [--keyword <word>]"
 allowed-tools: Read, Bash, Glob, Grep
 ---
 
 <purpose>
-Load relevant specs filtered by category (file-level) and/or keyword (entry-level via `<spec-entry>` tags).
+Load relevant specs filtered by role (primary), category (file-level), and/or keyword (entry-level).
+Role-based loading: loads role's primary doc in full + matching entries from other files.
 </purpose>
 
 <context>
-$ARGUMENTS — optional category filter and keyword.
+$ARGUMENTS — optional role, category filter, and keyword.
 
 ```bash
 $spec-load
-$spec-load "--category coding"
+$spec-load "--role implement"
 $spec-load "--keyword auth"
-$spec-load "--category coding --keyword naming"
+$spec-load "--role implement --keyword auth"
+$spec-load "--role review"
 ```
 
-**Category-to-file mapping (1:1, same 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` |
-| `bug` | `learnings.md` |
-| `pattern` | `coding-conventions.md` |
-| `decision` | `architecture-constraints.md` |
-| `rule` | `quality-rules.md` |
-| `validation` | `quality-rules.md` |
-| `all` (default) | All spec files |
-
-Extended types (`bug`, `pattern`, `decision`, `rule`, `validation`) are stored in their closest core category's file but retain their specific category in the `<spec-entry>` tag.
-
-**Keyword filtering**: When `--keyword` is provided, only entries with matching keyword in their `<spec-entry keywords="...">` attribute are returned. Legacy entries (heading format) are filtered by text grep.
+**File → Primary Role mapping:**
+| File | Primary 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)_ |
+
+**--role loading**: Loads primary role doc in full + entries from other files that have matching `roles` attr.
+
+**Keyword filtering**: When `--keyword` is provided, only entries with matching keyword in their `<spec-entry keywords="...">` attribute are returned.
 </context>
 
 <execution>
@@ -50,11 +46,11 @@ Verify `.workflow/specs/` exists (E001).
 
 ### Step 2: Parse Arguments
 
-Extract optional `--category` and `--keyword` flags.
+Extract optional `--role` and `--keyword` flags.
 
 ### Step 3: Load via CLI
 
-Run `maestro spec load [--category <cat>] [--keyword <word>]`. If CLI unavailable, read files directly and apply keyword filter.
+Run `maestro spec load [--role <role>] [--keyword <word>]`. If CLI unavailable, read files directly and apply keyword/role filter.
 
 ### Step 4: Display Results
 

package/.codex/skills/team-quality-assurance/roles/executor/role.md

@@ -26,7 +26,7 @@ Run test suites, collect coverage data, and perform automatic fix cycles when te
 | Target layer | task description `layer: L1/L2/L3` | Yes |
 
 1. Extract session path and target layer from task description
-2. Load validation specs: Run `maestro spec load --category quality` for verification rules and acceptance criteria
+2. Load validation specs: Run `maestro spec load --role review` for verification rules and acceptance criteria
 3. Read .msg/meta.json for strategy and generated test file list
 3. Detect test command by framework:
 

package/.codex/skills/team-review/roles/reviewer/role.md

@@ -21,7 +21,7 @@ Deep analysis on scan findings: triage, root cause / impact / optimization enric
 | .msg/meta.json | <session>/.msg/meta.json | No |
 
 1. Extract session path, input path, dimensions from task description
-2. Load review specs: Run `maestro spec load --category review` for review standards, checklists, and approval gates
+2. Load review specs: Run `maestro spec load --role review` for review standards, checklists, and approval gates
 3. Load scan results. If missing or empty -> report clean, complete immediately
 3. Load wisdom files from `<session>/wisdom/`
 4. Triage findings into two buckets:

package/.codex/skills/team-tech-debt/roles/scanner/role.md

@@ -18,7 +18,7 @@ Multi-dimension tech debt scanner. Scan codebase across 5 dimensions (code, arch
 | .msg/meta.json | <session>/.msg/meta.json | Yes |
 
 1. Extract session path and scan scope from task description
-2. Load debug specs: Run `maestro spec load --category debug` for known issues, workarounds, and root-cause notes
+2. Load debug specs: Run `maestro spec load --role analyze` for known issues, workarounds, and root-cause notes
 3. Read .msg/meta.json for team context
 3. Detect project type and framework:
 

package/.codex/skills/team-testing/roles/executor/role.md

@@ -24,7 +24,7 @@ Execute tests, collect coverage, attempt auto-fix for failures. Acts as the Crit
 | .msg/meta.json | <session>/wisdom/.msg/meta.json | No |
 
 1. Extract session path and test directory from task description
-2. Load test specs: Run `maestro spec load --category test` for test framework conventions and coverage targets
+2. Load test specs: Run `maestro spec load --role test` for test framework conventions and coverage targets
 3. Extract coverage target (default: 80%)
 3. Read .msg/meta.json for framework info (from strategist namespace)
 4. Determine test framework:

package/.codex/skills/team-testing/roles/generator/role.md

@@ -22,7 +22,7 @@ Generate test code by layer (L1 unit / L2 integration / L3 E2E). Acts as the Gen
 | .msg/meta.json | <session>/wisdom/.msg/meta.json | No |
 
 1. Extract session path and layer from task description
-2. Load test specs: Run `maestro spec load --category test` for test framework conventions and coverage targets
+2. Load test specs: Run `maestro spec load --role test` for test framework conventions and coverage targets
 3. Read test strategy:
 
 ```

package/.codex/skills/wiki-connect/SKILL.md

@@ -15,12 +15,12 @@ optionally auto-applies new `related` links to improve graph connectivity.
 $ARGUMENTS — optional flags.
 
 **Flags:**
-- `--scope <type>` — Limit to wiki type (spec, knowhow, note, lesson, issue). Default: all.
+- `--scope <type>` — Limit to wiki type (spec, knowhow, note, issue). Default: all.
 - `--min-similarity N` — Threshold 0.0-1.0 (default: 0.3)
 - `--fix` — Auto-apply top suggestions
 - `--max N` — Max suggestions (default: 20)
 
-**Output**: `.workflow/learning/wiki-connections-{date}.md`
+**Output**: `.workflow/knowhow/KNW-wiki-connections-{date}.md`
 </context>
 
 <execution>
@@ -47,7 +47,7 @@ For each suggestion: get entry → append target to `related` → update via `ma
 Re-run `maestro wiki health` for delta.
 
 ### Stage 6: Persist
-Write `wiki-connections-{date}.md`. Append graph insights to `lessons.jsonl` (source: "wiki-connect").
+Write `KNW-wiki-connections-{date}.md`. Append graph insights to `specs/learnings.md` (source: "wiki-connect").
 
 **Next steps:** `/wiki-digest <topic>`, `/manage-wiki health`, `/learn-follow <wiki-id>`, `maestro wiki graph`
 </execution>
@@ -68,6 +68,6 @@ Write `wiki-connections-{date}.md`. Append graph insights to `lessons.jsonl` (so
 - [ ] Candidates scored and ranked
 - [ ] Suggestions displayed with scores and reasons
 - [ ] If --fix: entries updated, new health score reported
-- [ ] Report written to `wiki-connections-{date}.md`
-- [ ] Graph insights appended to `lessons.jsonl`
+- [ ] Report written to `KNW-wiki-connections-{date}.md`
+- [ ] Graph insights appended to `specs/learnings.md`
 </success_criteria>

package/.codex/skills/wiki-digest/SKILL.md

@@ -26,7 +26,7 @@ $ARGUMENTS — scope and optional flags.
 - `--format full` — Detailed with per-entry summaries
 - `--create-issues` — Auto-create knowledge-gap issues in issues.jsonl
 
-**Output**: `.workflow/learning/digest-{slug}-{date}.md`
+**Output**: `.workflow/knowhow/KNW-digest-{slug}-{date}.md`
 </context>
 
 <execution>
@@ -41,7 +41,7 @@ Group entries into 3-5 themes via: tag co-occurrence, title BM25 similarity, rel
 Per theme: summary paragraph, key entries (by hub score), gap detection (broken links, orphans, TODO markers, missing perspectives), health score.
 
 ### Stage 4: Cross-Reference with Lessons
-Search `lessons.jsonl` for related insights. Flag unlinked insights (lessons matching theme but not referenced by wiki entries).
+Search `specs/learnings.md` for related insights. Flag unlinked insights (knowhow entries matching theme but not referenced by wiki entries).
 
 ### Stage 5: Coverage Heatmap
 Type × theme matrix showing knowledge density:
@@ -49,7 +49,7 @@ Type × theme matrix showing knowledge density:
               Theme 1    Theme 2    Theme 3
 spec          ███░░      ░░░░░      █████
 memory        ████░      ███░░      ░░░░░
-lesson        █░░░░      ██░░░      ████░
+knowhow       █░░░░      ██░░░      ████░
 ```
 Empty cells = knowledge gaps.
 
@@ -60,7 +60,7 @@ Produce `digest-{slug}-{date}.md` with themes, heatmap, gaps, unlinked insights,
 For each gap: dedup against issues.jsonl, append with `type: "knowledge-gap"`, `source: "wiki-digest"`.
 
 ### Stage 8: Persist
-Append meta-insights to `lessons.jsonl` (source: "wiki-digest"). Display summary.
+Append meta-insights to `specs/learnings.md` (source: "wiki-digest"). Display summary.
 
 **Next steps:** `/learn-follow <wiki-id>`, `/wiki-connect --fix`, `/manage-wiki cleanup`, `/learn-decompose <path>`
 </execution>
@@ -71,7 +71,7 @@ Append meta-insights to `lessons.jsonl` (source: "wiki-digest"). Display summary
 | E001 | error | No wiki entries found | Initialize wiki content |
 | E002 | error | Topic search returned 0 | Broaden topic |
 | W001 | warning | Too few entries (<5) | Themes may be trivial |
-| W002 | warning | lessons.jsonl not found | Skip cross-reference |
+| W002 | warning | learnings.md not found | Skip cross-reference |
 | W003 | warning | Some entry bodies failed to load | Partial summaries |
 </error_codes>
 
@@ -79,9 +79,9 @@ Append meta-insights to `lessons.jsonl` (source: "wiki-digest"). Display summary
 - [ ] Scope parsed and entries loaded
 - [ ] Entries clustered into 3-5 semantic themes
 - [ ] Per-theme analysis with gaps identified
-- [ ] Cross-reference with lessons.jsonl completed
+- [ ] Cross-reference with specs/learnings.md completed
 - [ ] Coverage heatmap generated
 - [ ] If --create-issues: gap issues created (deduped)
-- [ ] Digest written to `digest-{slug}-{date}.md`
-- [ ] Meta-insights appended to lessons.jsonl
+- [ ] Digest written to `KNW-digest-{slug}-{date}.md`
+- [ ] Meta-insights appended to specs/learnings.md
 </success_criteria>

package/dashboard/dist-server/dashboard/src/server/routes/specs.js

@@ -237,7 +237,7 @@ export function createSpecsRoutes(workflowRoot, writer) {
                 .split(/\s+/)
                 .filter(w => w.length >= 3);
             const keywords = [...new Set(kwCandidates)].slice(0, 5).join(',');
-            const entryBlock = `\n<spec-entry category="${entryCategory}" keywords="${keywords}" date="${date}">\n\n### ${firstLine}\n\n${content.trim()}\n\n</spec-entry>\n`;
+            const entryBlock = `\n<spec-entry roles="${entryCategory}" keywords="${keywords}" date="${date}">\n\n### ${firstLine}\n\n${content.trim()}\n\n</spec-entry>\n`;
             let newId = '';
             await withWriteLock(async () => {
                 const specsDir = await getSpecsDir(resolveRoot());