maestro-flow 0.3.43 → 0.3.45

package/.claude/commands/learn-decompose.md

@@ -31,16 +31,15 @@ Arguments: $ARGUMENTS
 - `--save-wiki` — Create wiki note entries per pattern group via `maestro wiki create --type note`
 
 **Storage written:**
-- `.workflow/learning/decompose-{slug}-{YYYY-MM-DD}.md` — Pattern decomposition report
-- `.workflow/learning/lessons.jsonl` — One insight per discovered pattern (source: "decompose")
-- `.workflow/learning/learning-index.json` — Updated index
+- `.workflow/knowhow/KNW-decompose-{slug}-{YYYY-MM-DD}.md` — Pattern decomposition report
+- `.workflow/specs/learnings.md` — One `<spec-entry>` per discovered pattern (source: "decompose")
 - If `--save-spec`: entries appended to `.workflow/specs/coding-conventions.md`
 - If `--save-wiki`: new wiki note entries
 
 **Storage read:**
 - Source files at target path
 - `.workflow/specs/coding-conventions.md` — Existing documented patterns (for dedup)
-- `.workflow/learning/lessons.jsonl` — Previously identified patterns (for dedup)
+- `.workflow/specs/learnings.md` — Previously identified patterns (for dedup)
 </context>
 
 <execution>
@@ -53,7 +52,7 @@ Arguments: $ARGUMENTS
 
 ### Stage 2: Load Existing Patterns
 - Read `.workflow/specs/coding-conventions.md` — extract documented patterns
-- Search `lessons.jsonl` for entries with `category: "pattern"` — previously discovered
+- Search `specs/learnings.md` for `<spec-entry>` blocks with `roles="implement"` — previously discovered
 - Build dedup set: pattern names already known
 
 ### Stage 3: Parallel Agent Analysis (4 dimensions)
@@ -104,7 +103,7 @@ If `--patterns` specified, instruct agents to focus only on named patterns.
 
 ### Stage 4: Cross-Reference & Dedup
 - Match agent findings against existing pattern set from Stage 2
-- Mark each finding: `documented` (already in specs), `known` (in lessons), or `new`
+- Mark each finding: `documented` (already in specs), `known` (in knowhow), or `new`
 - Flag contradictions: finding conflicts with documented convention
 - Merge duplicate findings across agents (same pattern found by multiple dimensions)
 
@@ -134,12 +133,9 @@ Build the decomposition report grouped by dimension:
 ```
 
 ### Stage 6: Persist
-1. Write `.workflow/learning/decompose-{slug}-{date}.md`
-2. Append each **new** pattern to `lessons.jsonl`:
-   - `source: "decompose"`, `category: "pattern"`, `confidence: <level>`
-   - Tags: `["decompose", "{dimension}", "{target-slug}"]`
+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 --body "<content>" --keywords "decompose,pattern,{dimension},{target-slug}"`:
    - Stable INS-id from `hash("decompose" + target + pattern_name)`
-3. Update `learning-index.json`
 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}`
 6. Display summary with counts and next steps
@@ -166,11 +162,10 @@ Build the decomposition report grouped by dimension:
 - [ ] All 4 dimension agents spawned in parallel
 - [ ] Each finding has: name, dimension, confidence, anchors, description, tradeoffs
 - [ ] Cross-reference performed (documented / known / new status assigned)
-- [ ] Pattern catalog written to `decompose-{slug}-{date}.md`
-- [ ] New patterns appended to `lessons.jsonl` with stable INS-ids
-- [ ] `learning-index.json` updated
+- [ ] Pattern catalog written to `KNW-decompose-{slug}-{date}.md`
+- [ ] New patterns appended to `specs/learnings.md` as `<spec-entry>` blocks with stable INS-ids
 - [ ] If --save-spec: spec entries created for new patterns
 - [ ] If --save-wiki: wiki notes created per dimension group
-- [ ] No files modified outside `.workflow/learning/` (and optionally specs/wiki)
+- [ ] No files modified outside `.workflow/knowhow/` (and optionally specs/wiki)
 - [ ] Summary displayed with pattern counts and next-step routing
 </success_criteria>

package/.claude/commands/learn-follow.md

@@ -14,7 +14,7 @@ allowed-tools:
 <purpose>
 Guided reading experience for code files, wiki entries, or topics. Instead of just reading code, this command walks through content section by section using forcing questions (inspired by gstack `/office-hours` brainstorming) to extract patterns, identify assumptions, and build a structured understanding map.
 
-Outputs reading notes with extracted patterns, open questions, and connection points. Insights persist to `lessons.jsonl` and optionally become wiki note entries for the knowledge graph.
+Outputs reading notes with extracted patterns, open questions, and connection points. Insights persist to `specs/learnings.md` as `<spec-entry>` blocks and optionally become wiki note entries for the knowledge graph.
 </purpose>
 
 <context>
@@ -31,16 +31,15 @@ Arguments: $ARGUMENTS
 - `--save-wiki` — Create a wiki note entry with the reading notes via `maestro wiki create --type note`
 
 **Storage written:**
-- `.workflow/learning/follow-{slug}-{YYYY-MM-DD}.md` — Reading notes with understanding map
-- `.workflow/learning/lessons.jsonl` — Appended pattern/technique insights
-- `.workflow/learning/learning-index.json` — Updated index
+- `.workflow/knowhow/KNW-follow-{slug}-{YYYY-MM-DD}.md` — Reading notes with understanding map
+- `.workflow/knowhow/specs/learnings.md` — Appended pattern/technique `<spec-entry>` blocks
 - If `--save-wiki`: new wiki note entry
 
 **Storage read:**
 - Target source file or wiki entry
 - `maestro wiki backlinks <id>` / `maestro wiki forward <id>` — Relationship context
 - `.workflow/specs/coding-conventions.md` — Convention reference for pattern matching
-- `.workflow/learning/lessons.jsonl` — Prior insights for dedup and cross-reference
+- `.workflow/knowhow/specs/learnings.md` — Prior insights for dedup and cross-reference
 </context>
 
 <execution>
@@ -120,17 +119,14 @@ Build a structured summary document:
 ## Connections
 - Links to: {forward link entries}
 - Referenced by: {backlink entries}
-- Related lessons: {matching lessons.jsonl entries}
+- Related insights: {matching specs/learnings.md entries}
 ```
 
 ### Stage 7: Persist
-1. Write `.workflow/learning/follow-{slug}-{date}.md` with the understanding map
-2. Append each new pattern/technique as an insight to `lessons.jsonl`:
-   - `source: "follow"`, `category: "pattern"` or `"technique"`
-   - Tags: `["follow", "{target-slug}"]`
+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 --body "<content>" --keywords "follow,{target-slug}"`:
    - Stable INS-id from `hash("follow" + target + pattern_name)`
-3. Update `learning-index.json`
-4. If `--save-wiki`: run `maestro wiki create --type note --slug follow-{slug} --title "Follow-Along: {target}" --body-file .workflow/learning/follow-{slug}-{date}.md`
+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
 
 **Next-step routing:**
@@ -158,10 +154,9 @@ Build a structured summary document:
 - [ ] Patterns extracted with file:line anchors
 - [ ] Convention comparison performed against coding-conventions.md
 - [ ] Understanding map produced with: concepts, patterns, assumptions, questions, connections
-- [ ] `follow-{slug}-{date}.md` written
-- [ ] `lessons.jsonl` appended with discovered patterns (stable INS-ids)
-- [ ] `learning-index.json` updated
+- [ ] `KNW-follow-{slug}-{date}.md` written
+- [ ] `specs/learnings.md` appended with discovered patterns as `<spec-entry>` blocks (stable INS-ids)
 - [ ] If --save-wiki: wiki note entry created
-- [ ] No files modified outside `.workflow/learning/` (and optionally wiki)
+- [ ] No files modified outside `.workflow/knowhow/` (and optionally wiki)
 - [ ] Summary displayed with next-step routing
 </success_criteria>

package/.claude/commands/learn-investigate.md

@@ -27,16 +27,15 @@ Arguments: $ARGUMENTS
 - `--max-hypotheses N` — Maximum hypotheses to test before escalating (default: 3)
 
 **Storage written:**
-- `.workflow/learning/investigate-{slug}/evidence.ndjson` — Structured evidence log (one JSON line per evidence)
-- `.workflow/learning/investigate-{slug}/understanding.md` — Evolving understanding document
-- `.workflow/learning/investigate-{slug}/report.md` — Final investigation report
-- `.workflow/learning/lessons.jsonl` — Investigation findings as insights (source: "investigate")
-- `.workflow/learning/learning-index.json` — Updated index
+- `.workflow/knowhow/KNW-investigate-{slug}/evidence.ndjson` — Structured evidence log (one JSON line per evidence)
+- `.workflow/knowhow/KNW-investigate-{slug}/understanding.md` — Evolving understanding document
+- `.workflow/knowhow/KNW-investigate-{slug}/report.md` — Final investigation report
+- `.workflow/knowhow/specs/learnings.md` — Investigation findings as `<spec-entry>` blocks (source: "investigate")
 
 **Storage read:**
 - Source files within scope
 - `maestro wiki search "<question>"` — Prior knowledge about the topic
-- `.workflow/learning/lessons.jsonl` — Prior related investigations
+- `.workflow/knowhow/specs/learnings.md` — Prior related investigations
 - `.workflow/specs/debug-notes.md` — Known gotchas and patterns
 - `.workflow/codebase/architecture.md` — Structural context (if exists)
 </context>
@@ -47,17 +46,17 @@ Arguments: $ARGUMENTS
 - Parse question from arguments
 - Determine scope (--scope or full project)
 - Generate investigation slug from question keywords
-- Create `.workflow/learning/investigate-{slug}/` directory
+- Create `.workflow/knowhow/KNW-investigate-{slug}/` directory
 - Search prior knowledge:
   - `maestro wiki search "<question>"` for related entries
-  - Grep `lessons.jsonl` for related insights
+  - Search `specs/learnings.md` for related insights
   - Read `debug-notes.md` for known gotchas
 
 Write initial `understanding.md`:
 ```markdown
 # Investigation: {question}
 ## Initial Understanding
-- Prior knowledge: {summary of wiki/lessons findings}
+- Prior knowledge: {summary of wiki/knowhow findings}
 - Scope: {path or "full project"}
 - Started: {timestamp}
 ```
@@ -78,7 +77,7 @@ For each piece of evidence, append to `evidence.ndjson`:
 ### Stage 3: Pattern Matching
 Compare collected evidence against known patterns:
 - Check `debug-notes.md` entries for matching situations
-- Check `lessons.jsonl` for related technique/pattern/gotcha entries
+- Check `specs/learnings.md` for related technique/pattern/gotcha entries
 - Identify: does this match a documented pattern, or is it novel?
 
 Update `understanding.md` with pattern analysis section.
@@ -179,12 +178,10 @@ Write final `report.md`:
 ```
 
 ### Stage 8: Persist
-1. Append findings to `lessons.jsonl`:
-   - Confirmed hypotheses → `category: "technique"` or `"pattern"`
-   - Disproved hypotheses → `category: "gotcha"` (what looked true but wasn't)
-   - `source: "investigate"`, tags: `["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)`
-2. Update `learning-index.json`
 3. Display summary with answer and next steps
 
 **Next-step routing:**
@@ -199,23 +196,22 @@ Write final `report.md`:
 |------|----------|-----------|----------|
 | E001 | error | No question provided | Provide a question as the first argument |
 | E002 | error | Scope path does not exist | Check --scope path is valid |
-| W001 | warning | No prior knowledge found in wiki/lessons | Proceed with fresh investigation |
+| W001 | warning | No prior knowledge found in wiki/knowhow | Proceed with fresh investigation |
 | W002 | warning | Evidence collection found very few matches (<3) | Broaden search terms or expand scope |
 | W003 | warning | All hypotheses inconclusive — escalating | Investigation marked INCONCLUSIVE |
 </error_codes>
 
 <success_criteria>
 - [ ] Question parsed and investigation slug generated
-- [ ] Investigation directory created under `.workflow/learning/`
-- [ ] Prior knowledge loaded from wiki and lessons
+- [ ] Investigation directory created under `.workflow/knowhow/`
+- [ ] Prior knowledge loaded from wiki and knowhow
 - [ ] Evidence collected and logged to `evidence.ndjson` (structured NDJSON)
-- [ ] Pattern matching performed against debug-notes and lessons
+- [ ] Pattern matching performed against debug-notes and knowhow insights
 - [ ] At least 1 hypothesis formed and tested
 - [ ] `understanding.md` tracks evolving understanding with timestamps
 - [ ] `report.md` written with answer, evidence trail, hypothesis results
-- [ ] Findings appended to `lessons.jsonl` with stable INS-ids
-- [ ] `learning-index.json` updated
+- [ ] Findings appended to `specs/learnings.md` as `<spec-entry>` blocks with stable INS-ids
 - [ ] 3-strike escalation triggered if all hypotheses fail
-- [ ] No files modified outside `.workflow/learning/`
+- [ ] No files modified outside `.workflow/knowhow/`
 - [ ] Summary displayed with answer and next-step routing
 </success_criteria>

package/.claude/commands/learn-retro.md

@@ -18,7 +18,7 @@ Two lenses, usable independently or together:
 - **git**: Commit metrics, session detection, per-author breakdown, file hotspots, trend tracking
 - **decision**: Decision tracing across wiki/specs/git, multi-perspective evaluation, lifecycle classification
 
-All insights persist to `.workflow/learning/lessons.jsonl` for cross-session queryability via `manage-learn`.
+All insights persist to `.workflow/knowhow/specs/learnings.md` as `<spec-entry>` blocks for cross-session queryability via `manage-learn`.
 </purpose>
 
 <context>
@@ -38,18 +38,17 @@ Arguments: $ARGUMENTS
 **Decision lens flags:**
 - `--phase N` — Decisions from phase N's context and related specs
 - `--tag <tag>` — Decisions tagged with specific tag in wiki/specs
-- `--id <id>` — Single decision by wiki ID or lessons.jsonl INS-id
+- `--id <id>` — Single decision by wiki ID or specs/learnings.md INS-id
 
 **Storage written:**
-- `.workflow/learning/retro-{YYYY-MM-DD}.md` — Unified human-readable report
-- `.workflow/learning/retro-{YYYY-MM-DD}.json` — Structured metrics (machine-readable)
-- `.workflow/learning/lessons.jsonl` — Appended insights (source: "retro-git" or "retro-decision")
-- `.workflow/learning/learning-index.json` — Updated index
+- `.workflow/knowhow/KNW-retro-{YYYY-MM-DD}.md` — Unified human-readable report
+- `.workflow/knowhow/KNW-retro-{YYYY-MM-DD}.json` — Structured metrics (machine-readable)
+- `.workflow/knowhow/specs/learnings.md` — Appended `<spec-entry>` blocks (source: "retro-git" or "retro-decision")
 
 **Storage read:**
 - `.workflow/state.json` — Current phase context (optional)
-- `.workflow/learning/retro-*.json` — Prior retro for trend comparison
-- `.workflow/learning/lessons.jsonl` — Existing insights for dedup
+- `.workflow/knowhow/KNW-retro-*.json` — Prior retro for trend comparison
+- `.workflow/knowhow/specs/learnings.md` — Existing insights for dedup
 - `maestro wiki list --type spec --json` — Spec entries (decision lens)
 - `.workflow/specs/architecture-constraints.md` — Documented architectural decisions (decision lens)
 - Phase context with Locked/Free/Deferred decisions (decision lens) — resolve via `state.json.artifacts[]` scratch paths
@@ -60,7 +59,7 @@ Arguments: $ARGUMENTS
 ### Stage 1: Parse Arguments & Select Lenses
 - Parse `--lens` flag: `git`, `decision`, or `all` (default: `all`)
 - Extract lens-specific flags
-- Check `.workflow/learning/` exists; bootstrap if missing
+- Check `.workflow/knowhow/` exists; bootstrap if missing
 
 Display banner:
 ```
@@ -121,7 +120,7 @@ For each author:
 - Session count and patterns
 
 #### 2e: Trend Comparison (if --compare or prior report exists)
-- Find most recent `.workflow/learning/retro-*.json`
+- Find most recent `.workflow/knowhow/KNW-retro-*.json`
 - Compute deltas: commits, LOC, test ratio, churn rate, session count
 - Flag significant changes (>20% delta) as trend highlights
 
@@ -145,9 +144,9 @@ git log --oneline --all --grep="decision\|chose\|decided\|architecture" -20
 ```
 
 Also read:
-- `.workflow/specs/architecture-constraints.md` — grep for `<spec-entry category="arch"` blocks
+- `.workflow/specs/architecture-constraints.md` — grep for `<spec-entry` blocks with `roles="plan"`
 - Phase context files — resolve via `state.json.artifacts[]` scratch paths — scan for "Locked:", "Deferred:" sections
-- `.workflow/learning/lessons.jsonl` — filter `category == "decision"`
+- `.workflow/knowhow/specs/learnings.md` — filter entries with `keywords` containing "decision"
 
 Apply scope filter (--phase, --tag, --id).
 
@@ -157,7 +156,7 @@ Per decision:
 {
   "id": "source id",
   "title": "what was decided",
-  "source": "wiki|spec|phase-context|lesson|git",
+  "source": "wiki|spec|phase-context|knowhow|git",
   "date": "when decided",
   "rationale": "why",
   "alternatives": "what was considered",
@@ -203,7 +202,7 @@ Spawn 3 Agents in a single message:
 
 ### Stage 4: Unified Report
 
-Write `.workflow/learning/retro-{date}.md`:
+Write `.workflow/knowhow/KNW-retro-{date}.md`:
 
 ```markdown
 # Retrospective: {date}
@@ -243,17 +242,16 @@ Write `.workflow/learning/retro-{date}.md`:
 1. {action}: {reason}
 ```
 
-Write `.workflow/learning/retro-{date}.json` with structured data.
+Write `.workflow/knowhow/KNW-retro-{date}.json` with structured data.
 
 ---
 
 ### Stage 5: Persist
 1. Write report files
-2. Append insights to `lessons.jsonl`:
-   - Git insights: `source: "retro-git"`, `category` per insight type
-   - Decision insights: `source: "retro-decision"`, `category: "decision"`
+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)`
-3. Update `learning-index.json`
 4. Display summary
 
 **Next-step routing:**
@@ -271,8 +269,8 @@ Write `.workflow/learning/retro-{date}.json` with structured data.
 | E001 | error | Not inside a git repository (git lens) | Navigate to a git repo directory |
 | E002 | error | No commits found in time window (git lens) | Increase --days or check filters |
 | E003 | error | No decisions found in any source (decision lens) | Check wiki/specs content, or provide --id |
-| E004 | error | --id not found in wiki or lessons (decision lens) | Verify the decision ID exists |
-| W001 | warning | `.workflow/learning/` not found, bootstrapping | Auto-created; proceed normally |
+| E004 | error | --id not found in wiki or knowhow (decision lens) | Verify the decision ID exists |
+| W001 | warning | `.workflow/knowhow/` not found, bootstrapping | Auto-created; proceed normally |
 | W002 | warning | No prior retro report for comparison | Skip trend section; first retro establishes baseline |
 | W003 | warning | One perspective agent failed — partial evaluation (decision lens) | Proceed with available perspectives |
 | W004 | warning | No git implementation evidence for a decision | Evaluation is theoretical only |
@@ -294,10 +292,9 @@ Write `.workflow/learning/retro-{date}.json` with structured data.
   - [ ] 3 perspective agents spawned in parallel
   - [ ] Each decision classified by lifecycle status
   - [ ] Recommendations generated for non-Validated decisions
-- [ ] Unified report written to `retro-{date}.md`
-- [ ] Structured data written to `retro-{date}.json`
-- [ ] `lessons.jsonl` appended with insights (stable INS-ids)
-- [ ] `learning-index.json` updated
-- [ ] No files modified outside `.workflow/learning/`
+- [ ] Unified report written to `KNW-retro-{date}.md`
+- [ ] Structured data written to `KNW-retro-{date}.json`
+- [ ] `specs/learnings.md` appended with `<spec-entry>` blocks (stable INS-ids)
+- [ ] No files modified outside `.workflow/knowhow/`
 - [ ] Summary displayed with next-step routing
 </success_criteria>

package/.claude/commands/learn-second-opinion.md

@@ -18,7 +18,7 @@ Structured second-opinion workflow for code, decisions, or plans. Three modes in
 - **challenge**: single adversarial agent that tries to break the approach, find hidden assumptions, and propose alternatives
 - **consult**: interactive Q&A mode where the agent studies the target and answers your questions
 
-Decoupled from the phase/execution lifecycle — can be invoked on any piece of code or knowledge at any time. Findings persist to `lessons.jsonl`.
+Decoupled from the phase/execution lifecycle — can be invoked on any piece of code or knowledge at any time. Findings persist to `specs/learnings.md` as `<spec-entry>` blocks.
 </purpose>
 
 <context>
@@ -36,15 +36,14 @@ Arguments: $ARGUMENTS
 - `--mode consult` — Interactive Q&A session
 
 **Storage written:**
-- `.workflow/learning/opinion-{slug}-{YYYY-MM-DD}.md` — Opinion report
-- `.workflow/learning/lessons.jsonl` — New insights from analysis (source: "second-opinion")
-- `.workflow/learning/learning-index.json` — Updated index
+- `.workflow/knowhow/KNW-opinion-{slug}-{YYYY-MM-DD}.md` — Opinion report
+- `.workflow/knowhow/specs/learnings.md` — New `<spec-entry>` blocks from analysis (source: "second-opinion")
 
 **Storage read:**
 - Target content (file, wiki entry, diff, or plan)
 - `.workflow/specs/` — Project conventions for context
 - `maestro wiki search` — Related knowledge entries
-- `.workflow/learning/lessons.jsonl` — Prior insights about the topic
+- `.workflow/knowhow/specs/learnings.md` — Prior insights about the topic
 </context>
 
 <execution>
@@ -60,7 +59,7 @@ Arguments: $ARGUMENTS
 ### Stage 2: Load Context
 - Read relevant specs: `Skill({ skill: "spec-load" })` silently to get project conventions
 - Search wiki: `maestro wiki search "<target topic>"` for related entries (top 5)
-- Search lessons: grep `lessons.jsonl` for entries related to the target area
+- Search insights: search `specs/learnings.md` for entries related to the target area
 - Build context brief: target content + conventions + related knowledge
 
 ### Stage 3: Execute Mode
@@ -124,15 +123,12 @@ Across all perspectives (or from single agent in challenge/consult):
 - **Top 3 recommendations**: prioritized by impact
 
 ### Stage 5: Persist & Report
-1. Write `.workflow/learning/opinion-{slug}-{date}.md`:
+1. Write `.workflow/knowhow/KNW-opinion-{slug}-{date}.md`:
    - Target summary
    - Per-persona findings (review) / adversarial analysis (challenge) / Q&A transcript (consult)
    - Synthesis: agreements, disagreements, verdict
    - Recommendations
-2. Append non-trivial findings to `lessons.jsonl`:
-   - `source: "second-opinion"`, `category: "pattern"` or `"antipattern"` or `"decision"`
-   - Tags: `["second-opinion", "{mode}", "{target-slug}"]`
-3. Update `learning-index.json`
+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:**
@@ -153,15 +149,14 @@ Across all perspectives (or from single agent in challenge/consult):
 
 <success_criteria>
 - [ ] Target resolved and content loaded
-- [ ] Context gathered (specs, wiki, lessons)
+- [ ] Context gathered (specs, wiki, knowhow)
 - [ ] Mode executed correctly:
   - review: 3 agents spawned in parallel, all returned findings
   - challenge: adversarial analysis completed with forcing questions
   - consult: interactive Q&A loop completed
 - [ ] Synthesis produced with agreements, disagreements, verdict
-- [ ] Report written to `opinion-{slug}-{date}.md`
-- [ ] Non-trivial findings appended to `lessons.jsonl`
-- [ ] `learning-index.json` updated
-- [ ] No files modified outside `.workflow/learning/`
+- [ ] Report written to `KNW-opinion-{slug}-{date}.md`
+- [ ] Non-trivial findings appended to `specs/learnings.md` as `<spec-entry>` blocks
+- [ ] No files modified outside `.workflow/knowhow/`
 - [ ] Summary displayed with verdict and next-step routing
 </success_criteria>

package/.claude/commands/maestro-analyze.md

@@ -41,6 +41,14 @@ $ARGUMENTS -- phase number for milestone-scoped, topic text for adhoc/standalone
 - `--gaps [ISS-ID]`: Issue root cause analysis mode. If ISS-ID provided, analyze single issue. If omitted, analyze all open/registered issues from issues.jsonl.
 
 Scope routing, output directory format, artifact registration schema, and output artifact listing are defined in workflow analyze.md (Scope Routing and Output Structure sections).
+
+### Role Knowledge
+1. Browse accumulated knowledge for this role:
+   `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...]`
+4. Review loaded knowledge before proceeding
 </context>
 
 <execution>

package/.claude/commands/maestro-brainstorm.md

@@ -44,6 +44,14 @@ $ARGUMENTS -- topic text for auto mode, or role name for single role mode.
 - `--skip-questions`: Skip context gathering questions
 - `--include-questions`: Force context gathering even if analysis exists
 - `--style-skill PKG`: Style package for ui-designer role
+
+### Role Knowledge
+1. Browse accumulated knowledge for this role:
+   `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...]`
+4. Review loaded knowledge before proceeding
 </context>
 
 <execution>

package/.claude/commands/maestro-execute.md

@@ -30,13 +30,21 @@ Invoked after /maestro-plan produces a confirmed plan. When called without args
 <context>
 $ARGUMENTS — phase number, or no args for milestone-wide execution, with optional flags.
 
-Scope routing, flags, resolution logic, output directory format, artifact registration schema, and incremental learning extraction are defined in workflow `execute.md`.
+Scope routing, flags, resolution logic, output directory format, artifact registration schema, and incremental knowhow extraction are defined in workflow `execute.md`.
 
 ### Pre-load context (before task execution)
 
 1. **Codebase docs**: If `.workflow/codebase/doc-index.json` exists, read `ARCHITECTURE.md` for module boundaries. Pass as shared context to executor agents.
 2. **Wiki knowledge**: Run `maestro wiki search "<phase keywords>" --json 2>/dev/null`. If results found, extract top 5 entries as prior knowledge context for agents.
 3. Both are optional — proceed without if unavailable (log warning).
+
+### Role Knowledge
+1. Browse accumulated knowledge for this role:
+   `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...]`
+4. Review loaded knowledge before proceeding
 </context>
 
 <execution>
@@ -61,7 +69,7 @@ After each task completes, evaluate inquiry triggers:
    → Ask: "TASK-{NNN} succeeded after {N} retries. Should this fix pattern be documented? (`/spec-add debug`)"
 
 3. **Implicit knowledge**: If task summary contains design rationale ("chose X because", "rejected Y due to"):
-   → Ask: "Design decision detected. Should it be recorded as a learning? (`/spec-add learning`)"
+   → Ask: "Design decision detected. Should it be recorded as knowhow? (`/spec-add learning`)"
 
 If user confirms, invoke `Skill({ skill: "spec-add", args: "<category> <content>" })` with extracted content.
 
@@ -115,6 +123,6 @@ If failed tasks exist, suggest /quality-debug for investigation.
 - [ ] `.summaries/TASK-{NNN}-summary.md` written for each completed task
 - [ ] `.task/TASK-{NNN}.json` statuses updated (completed|blocked)
 - [ ] EXC artifact registered in state.json for each plan executed
-- [ ] Incremental learnings extracted to specs/learnings.md
+- [ ] Incremental knowhow extracted to specs/learnings.md
 - [ ] state.json updated with execution progress
 </success_criteria>

package/.claude/commands/maestro-learn.md

@@ -46,8 +46,8 @@ $ARGUMENTS — user learning intent text, or flags.
 | `pattern-catalog` | decompose --save-spec --save-wiki → second-opinion --mode review | Full pattern extraction + review |
 
 **Storage:**
-- `.workflow/learning/.maestro-learn/{session_id}/status.json` — Session tracking
-- All learn command outputs go to `.workflow/learning/`
+- `.workflow/knowhow/.maestro-learn/{session_id}/status.json` — Session tracking
+- All learn command outputs go to `.workflow/knowhow/`
 </context>
 
 <execution>
@@ -108,7 +108,7 @@ pattern-catalog → [learn-decompose --save-spec --save-wiki, learn-second-opini
 **If not `-y`:** show plan, ask for confirmation.
 
 **Execute:**
-1. Create session dir: `.workflow/learning/.maestro-learn/learn-{timestamp}/`
+1. Create session dir: `.workflow/knowhow/.maestro-learn/learn-{timestamp}/`
 2. Write `status.json` with chain steps
 3. Execute each step via `Skill()`:
    - On success: mark completed, continue
@@ -136,5 +136,5 @@ pattern-catalog → [learn-decompose --save-spec --save-wiki, learn-second-opini
 - [ ] All chain steps executed via Skill()
 - [ ] Error handling: retry/skip/abort per step
 - [ ] Session summary displayed with next-step routing
-- [ ] No files modified outside `.workflow/learning/`
+- [ ] No files modified outside `.workflow/knowhow/`
 </success_criteria>

package/.claude/commands/maestro-milestone-complete.md

@@ -13,7 +13,7 @@ allowed-tools:
 ---
 
 <purpose>
-Mark a milestone as complete after its audit has passed. Archives all scratch artifacts to `milestones/{M}/artifacts/`, moves artifact entries from `state.json.artifacts[]` to `milestone_history`, extracts final learnings, and advances to the next milestone.
+Mark a milestone as complete after its audit has passed. Archives all scratch artifacts to `milestones/{M}/artifacts/`, moves artifact entries from `state.json.artifacts[]` to `milestone_history`, extracts final knowhow, and advances to the next milestone.
 </purpose>
 
 <required_reading>
@@ -34,14 +34,14 @@ Milestone: $ARGUMENTS (optional -- defaults to current_milestone from state.json
 <execution>
 Follow '~/.maestro/workflows/milestone-complete.md' completely.
 
-Archive flow steps (validation, directory archival, artifact history, learning extraction, state advancement, cleanup) are defined in workflow `milestone-complete.md`.
+Archive flow steps (validation, directory archival, artifact history, knowhow extraction, state advancement, cleanup) are defined in workflow `milestone-complete.md`.
 
 ### Knowledge Promotion Inquiry
 
-After learning extraction (step 4), scan `learnings.md` for promotion candidates:
+After knowhow extraction (step 4), scan `learnings.md` for promotion candidates:
 
-1. **High-frequency pattern detection**: Scan all `<spec-entry category="learning">` entries for keyword overlap (≥2 entries sharing keywords):
-   → Ask: "Keyword '{keyword}' appears in {N} learning entries. Should this be promoted to a formal coding convention? (`/spec-add coding`)"
+1. **High-frequency pattern detection**: Scan all `<spec-entry>` entries with `roles="implement"` for keyword overlap (≥2 entries sharing keywords):
+   → Ask: "Keyword '{keyword}' appears in {N} knowhow entries. Should this be promoted to a formal coding convention? (`/spec-add coding`)"
 
 2. **Convention drift detection**: Compare executed task summaries against `coding-conventions.md` and `architecture-constraints.md`:
    → Ask: "Were any established conventions bypassed during this milestone? Should conventions be updated?"
@@ -68,7 +68,7 @@ If user confirms promotion, invoke `Skill({ skill: "spec-add", args: "<category>
 - [ ] Audit report verified as PASS
 - [ ] Scratch artifacts moved to milestones/{M}/artifacts/
 - [ ] Artifact entries archived to milestone_history
-- [ ] Learnings extracted to specs/learnings.md
+- [ ] Knowhow extracted to specs/learnings.md
 - [ ] state.json updated: next milestone as current, artifacts[] cleared
 - [ ] Roadmap snapshot saved
 - [ ] project.md Context updated with milestone summary

package/.claude/commands/maestro-plan.md

@@ -45,6 +45,14 @@ Scope routing, base flags (`--collab`, `--spec`, `-y`, `--gaps`, `--dir`), outpu
 **Upstream context:**
 - Reads `context.md` from prior analyze artifact (auto-discovered from state.json or via --dir)
 - Reads `conclusions.json` if available (implementation_scope seeds task generation)
+
+### Role Knowledge
+1. Browse accumulated knowledge for this role:
+   `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...]`
+4. Review loaded knowledge before proceeding
 </context>
 
 <execution>

package/.claude/commands/maestro-ralph-execute.md

@@ -170,8 +170,7 @@ flag = auto_flag_map[next.skill] || "-y"
 effective_args = `${next.args} ${flag}`
 
 Bash({
-  command: `maestro delegate "Execute: Skill({ skill: \"${next.skill}\", args: \"${effective_args}\" })
-Do NOT reimplement — invoke the skill command directly." --to claude --mode write`,
+  command: `maestro delegate "/${next.skill} ${effective_args}" --to claude --mode write`,
   run_in_background: true,
   timeout: 600000
 })