maestro-flow-one 0.2.2 → 0.2.4

package/maestro-flow/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/maestro-flow/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/maestro-flow/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/maestro-flow/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/maestro-flow/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/maestro-flow/commands/lifecycle/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/maestro-flow/commands/lifecycle/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/maestro-flow/commands/lifecycle/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/maestro-flow/commands/lifecycle/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/maestro-flow/commands/lifecycle/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/maestro-flow/commands/lifecycle/tools-execute.md

@@ -0,0 +1,117 @@
+---
+name: maestro-tools-execute
+description: Load and execute tool specs by category or name
+argument-hint: "[tool-name | --category <category>]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+  - Agent
+---
+<purpose>
+Load registered tool documents and execute them step-by-step. Two invocation modes:
+
+1. **Direct** — Specify tool name, load full steps, execute sequentially
+2. **Category-based** — List available tools for a category, user selects, then execute
+
+Execution follows the tool definition steps in order, reporting progress per step and asking user on blockers.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/tools-spec.md
+</required_reading>
+
+<context>
+$ARGUMENTS — Tool name, keyword, or --category filter
+
+**Examples**:
+```
+/maestro-tools-execute integration-test
+/maestro-tools-execute --category coding
+/maestro-tools-execute --category review --keyword api
+/maestro-tools-execute
+```
+
+Empty arguments enters interactive mode: list all tools for user selection.
+</context>
+
+<execution>
+
+### Step 1: Load Tool
+
+**By name**:
+```bash
+maestro spec load --category coding --keyword <name>
+```
+Match knowhow documents with `tool: true` whose title or keywords contain the name.
+
+**By category**:
+```bash
+maestro spec load --category <category>
+```
+Extract tool entries from the "Available Tools" section in output.
+
+**Empty args**:
+Load all categories, collect tool entries, present to user with AskUserQuestion for selection.
+
+### Step 2: Display Tool
+
+Show tool information:
+- Name, category, keywords
+- Steps overview (for ref entries, expand knowhow detail first)
+
+Expand ref entries:
+```bash
+maestro wiki load <knowhow-id>
+```
+
+### Step 3: Confirm Execution
+
+Ask user:
+- Execute steps as-is?
+- Adjust parameters/scope?
+- View only, do not execute?
+
+### Step 4: Step-by-Step Execution
+
+Follow the tool definition steps in order:
+1. Read current step description
+2. Execute step action (file ops, commands, code changes, etc.)
+3. Verify step completion
+4. Report progress: `[Step N/M] done — <step_name>`
+5. Proceed to next step
+
+**Blocker handling**:
+- Step fails → report error, ask user: retry / skip / abort
+- Needs user input → AskUserQuestion for parameters
+- Prerequisites unmet → show missing items, ask how to proceed
+
+### Step 5: Report Results
+
+After completion, output:
+- Completed steps list
+- Skipped/failed steps (if any)
+- Artifacts produced (generated files, test results, etc.)
+- Suggested next actions
+
+</execution>
+
+<error_codes>
+| Code | Severity | Description |
+|------|----------|-------------|
+| E001 | fatal | No matching tool found — check name/keyword |
+| E002 | warning | Multiple tools match — list options for user selection |
+| E003 | warning | Step execution failed — ask user how to proceed |
+</error_codes>
+
+<success_criteria>
+- [ ] Tool correctly loaded (ref expanded if applicable)
+- [ ] User confirmed before execution starts
+- [ ] Each step has progress feedback
+- [ ] Blockers handled interactively
+- [ ] Results reported clearly
+</success_criteria>

package/maestro-flow/commands/lifecycle/tools-register.md

@@ -0,0 +1,136 @@
+---
+name: maestro-tools-register
+description: Register tool specs - extract, generate, or optimize
+argument-hint: "[description]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+  - Agent
+---
+<purpose>
+Codify reusable business processes as knowhow documents with `tool: true` in `.workflow/knowhow/`. Once registered, tools are auto-discovered by `spec load --category` and spec-injector — plan agents pick up design/architecture flows, test agents pick up verification methods, implement agents pick up execution steps.
+
+When to register: during planning to standardize a business process (e.g. payment reconciliation, OAuth integration steps); after execution to capture a validated procedure (e.g. database migration rollback); before testing to register verification methods for test agents (e.g. E2E checkout flow, API idempotency verification); during retrospective/harvest to extract reusable process knowledge from artifacts.
+
+Three modes: Extract (from code/docs), Generate (from description), Optimize (improve existing).
+Short processes (<10 steps) inline; long processes (>=10 steps) use ref mode with knowhow detail doc.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/tools-spec.md
+</required_reading>
+
+<context>
+$ARGUMENTS — Intent description
+
+**Examples**:
+```
+/maestro-tools-register extract OAuth PKCE token exchange flow from src/auth/
+/maestro-tools-register generate Stripe webhook idempotency verification
+/maestro-tools-register generate E2E checkout flow with payment gateway mock setup
+/maestro-tools-register optimize e2e-checkout tool
+```
+</context>
+
+<execution>
+
+### Step 1: Intent Detection
+
+Parse $ARGUMENTS to determine mode:
+- Contains "extract" → extract mode
+- Contains "optimize/improve" → optimize mode
+- Other → generate mode
+- Empty → ask user with AskUserQuestion
+
+### Step 2: Gather Information
+
+**Extract mode**:
+- Identify source (current conversation, specified files, codebase scan)
+- Extract step sequence, prerequisites, expected outputs
+
+**Generate mode**:
+- Confirm tool name, applicable roles, target scenario
+- If unclear, ask user with AskUserQuestion
+
+**Optimize mode**:
+- Load existing tool: `maestro spec load --category coding --keyword <name>`
+- Analyze improvement points (step splitting, prerequisites, error handling)
+
+**For all modes** — identify the usage timing: when should an agent or user invoke this tool? This becomes the first line of the entry description (see Step 5).
+
+### Step 3: Determine Category
+
+Infer applicable category from context, or ask user:
+- coding — execution tools (build, deploy, integrate)
+- test — testing tools (test flows, verification steps)
+- review — review tools (checklists, audit standards)
+- arch — planning tools (design flows, analysis steps)
+- debug — analysis tools (diagnostic flows, investigation steps)
+
+### Step 4: Decide Inline vs Ref
+
+- Steps <10 and no code blocks → **inline mode**
+- Steps >=10 or contains code examples/config → **ref mode**
+
+### Step 5: Write
+
+**Description format**: First line after `### Title` must state **when to use** this tool (the usage timing from Step 2). This is critical for ref entries — `spec load` only shows the first 200 chars after the heading as the summary.
+
+```
+### {Title}
+
+Use when {timing/trigger condition}.
+
+1. Step one ...
+```
+
+**Create knowhow tool document** in `.workflow/knowhow/` with `tool: true` in YAML frontmatter:
+```yaml
+---
+title: <Title>
+type: recipe
+category: <category>
+keywords: [<keywords>]
+tool: true
+summary: "Use when <timing>. <scope description>"
+---
+
+## Steps
+1. Step one ...
+```
+
+**Optionally register spec ref entry** for index discoverability:
+```bash
+maestro spec add <category> "<title>" "Use when <timing>. <scope summary>" --keywords "<csv>" \
+  --ref "knowhow/RCP-<slug>.md" --knowhow-type recipe
+```
+
+### Step 6: Verify
+
+- `maestro spec load --category <category> --keyword <keyword>` to confirm loadable
+- Display result: title, category, keywords, storage location
+
+</execution>
+
+<error_codes>
+| Code | Severity | Description |
+|------|----------|-------------|
+| E001 | fatal | `.workflow/specs/` does not exist — run `maestro spec init` |
+| E002 | warning | Duplicate tool name detected — confirm overwrite/optimize |
+| E003 | fatal | category parameter empty — tools must declare a category |
+</error_codes>
+
+<success_criteria>
+- [ ] Tool registered as knowhow document with `tool: true` frontmatter
+- [ ] category correctly set
+- [ ] keywords auto-extracted (3-5 terms)
+- [ ] Description starts with "Use when ..." (usage timing)
+- [ ] Loadable via `spec load --category <category>`
+- [ ] Long processes use ref mode with knowhow file created
+- [ ] Ref knowhow YAML includes `summary` with usage timing
+</success_criteria>

package/maestro-flow/commands/lifecycle/ui-codify.md

@@ -0,0 +1,67 @@
+---
+name: maestro-ui-codify
+description: Extract design system from code, generate reference package, persist as knowledge assets
+argument-hint: "<source-path> [--package-name <name>] [--output-dir <path>] [--overwrite]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - Skill
+---
+<purpose>
+Codify UI design system from existing source code. 4-phase pipeline:
+
+1. **Validate** (inline): Parameter validation, workspace setup, file discovery
+2. **Extract** (3 parallel agents): Style Agent + Animation Agent + Layout Agent produce design-tokens.json, animation-tokens.json, layout-templates.json
+3. **Package** (agent): Copy tokens to package directory, generate preview.html + preview.css
+4. **Knowhow** (manifest + skill): Build knowhow-manifest.json, call codify-to-knowhow to persist as knowledge assets
+
+Position in pipeline: code -> **ui-codify** -> knowhow + specs
+</purpose>
+
+<deferred_reading>
+- [ui-codify.md](~/.maestro/workflows/ui-codify.md) — read always (main workflow orchestrator)
+- [ui-codify-extract.md](~/.maestro/workflows/ui-codify-extract.md) — read when Phase 2 starts (style extraction with 3 agents)
+- [ui-codify-package.md](~/.maestro/workflows/ui-codify-package.md) — read when Phase 3 starts (reference package generation)
+- [ui-codify-knowhow.md](~/.maestro/workflows/ui-codify-knowhow.md) — read when Phase 4 starts (knowledge asset generation)
+</deferred_reading>
+
+<context>
+$ARGUMENTS — source path (required) with optional flags.
+
+Flags:
+- `<source-path>` (positional, required): Directory containing CSS/SCSS/JS/TS/HTML source files
+- `--package-name <name>`: Package name for reference output (default: auto-generated from source directory)
+- `--output-dir <path>`: Output directory for reference package (default: `.workflow/reference_style`)
+- `--overwrite`: Allow overwriting existing package directory
+</context>
+
+<execution>
+Route to `~/.maestro/workflows/ui-codify.md` and follow completely.
+
+The workflow orchestrates 4 phases with deferred loading of phase-specific workflow files. Each phase reads its workflow file only when execution reaches that phase.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | error | Source path argument required | parse_input |
+| E002 | error | Source path not found or not a directory | validate |
+| E003 | error | Package directory exists without --overwrite flag | validate |
+| W001 | warning | animation-tokens.json not found (optional, extraction continues) | extract |
+</error_codes>
+
+<success_criteria>
+- [ ] Source path validated and file discovery completed
+- [ ] design-tokens.json generated with color, typography, spacing tokens
+- [ ] layout-templates.json generated with component patterns (universal/specialized)
+- [ ] animation-tokens.json generated (optional, W001 if missing)
+- [ ] preview.html + preview.css generated as interactive showcase
+- [ ] knowhow-manifest.json created with AST/DCS assets and spec entries
+- [ ] codify-to-knowhow called and completed successfully
+- [ ] Temporary workspace cleaned up
+</success_criteria>

package/maestro-flow/commands/manage/harvest.md

@@ -54,7 +54,7 @@ Extraction patterns, classification rules, routing infrastructure, and fragment
 - Review wiki entries → `maestro wiki list --type note`
 - Connect wiki graph → `/wiki-connect --fix`
 - Triage issues → `/manage-issue list --source harvest`
-- View specs → `/spec-load --category learning`
+- View specs → `/spec-load --role implement`
 - Full retrospective → `/quality-retrospective`
 </execution>
 

package/maestro-flow/commands/manage/learn.md

@@ -16,7 +16,7 @@ Unified atomic knowledge capture for the workflow learning library. Captures two
 - **Insights**: Timeless "eureka moment" entries (patterns, gotchas, techniques) — the default mode
 - **Tips**: Quick contextual notes for cross-session recovery (formerly in `manage-knowhow-capture tip`)
 
-Both types are stored in `.workflow/learning/lessons.jsonl` with auto-detected phase linkage and keyword-based category inference. Tips are distinguished by `source: "tip"` and implicitly tagged `tip`. Same store as retrospective output, so search and list see the entire knowledge corpus.
+Both types are stored in `.workflow/specs/learnings.md` as `<spec-entry>` blocks with auto-detected phase linkage and keyword-based category inference. Tips are distinguished by `source: "tip"` and implicitly tagged `tip`. Same store as retrospective output, so search and list see the entire knowledge corpus.
 </purpose>
 
 <required_reading>
@@ -30,7 +30,7 @@ Arguments: $ARGUMENTS
 - `"<insight text>"` (or any non-keyword text) → insight capture mode
 - `tip <text>` → tip capture mode (quick contextual note, auto-tagged `tip`)
 - `list` → list recent entries (default 20)
-- `search <query>` → text search across lessons.jsonl
+- `search <query>` → `maestro spec load --category learning` or text search across `specs/learnings.md`
 - `show <INS-id>` → full detail with phase context
 - empty → AskUserQuestion to prompt for text
 
@@ -47,21 +47,19 @@ Follow `~/.maestro/workflows/learn.md` Stages 1–5 in order.
 | E001 | error | `.workflow/` not initialized — run `/maestro-init` first | parse_input |
 | E002 | error | Unknown `--category` value (allowed: pattern, antipattern, decision, tool, gotcha, technique, tip) | parse_input |
 | E003 | error | `show` mode requires an INS-id argument | show |
-| E004 | error | Insight id not found in lessons.jsonl | show |
+| E004 | error | Insight id not found in `specs/learnings.md` | show |
 | W001 | warning | Auto-phase detection found a current_phase but no matching artifact in registry; phase set to null | capture |
-| W002 | warning | learning-index.json out of sync with lessons.jsonl (different row count); offer to rebuild | list/search |
 </error_codes>
 
 <success_criteria>
 - [ ] Mode correctly routed (capture / list / search / show)
-- [ ] Capture: `lessons.jsonl` row appended with valid JSON and all required fields
-- [ ] Capture: `learning-index.json` updated with matching entry
+- [ ] Capture: `<spec-entry>` block appended to `specs/learnings.md` with all required fields
 - [ ] Capture: phase auto-link resolves correctly via artifact registry when `state.json` has `current_phase`
 - [ ] Capture: category inference produces a sensible default when `--category` absent
 - [ ] List: filters apply, output sorted newest-first, default limit 20
 - [ ] Search: results ranked by title (3) > tags (2) > summary (1) match
 - [ ] Show: full insight displayed with phase context and routed-artifact link if any
-- [ ] No file modifications outside `.workflow/learning/`
+- [ ] No file modifications outside `.workflow/knowhow/`
 - [ ] Confirmation banner displayed with INS-id and next-step hints
 - [ ] Next step: `/manage-learn list` to browse, or `/manage-learn search <query>` to find related insights
 </success_criteria>

package/maestro-flow/commands/manage/wiki.md

@@ -34,7 +34,7 @@ $ARGUMENTS — subcommand and optional flags.
 | No args | Same as `health` |
 
 **Flags:**
-- `--type <type>` — Filter by wiki type: spec, knowhow, note, lesson, issue
+- `--type <type>` — Filter by wiki type: spec, knowhow, note, issue
 - `--fix` — Auto-fix issues found during cleanup (remove broken links, suggest connections)
 - `--json` — Output in JSON format
 </context>

package/maestro-flow/commands/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/maestro-flow/commands/quality/auto-test.md

@@ -85,7 +85,7 @@ Append to state.json.artifacts[]:
 **Next-step routing on completion:**
 - Converged (>=95%) → `/maestro-verify {phase}`
 - All requirements verified (spec source) → `/maestro-milestone-audit`
-- Bugs discovered → `/quality-debug --from-auto-test {phase}`
+- Bugs discovered → `/quality-debug --from-uat {phase}`
 - Max iter, >80% → `/quality-test {phase}` for manual UAT
 - Max iter, <80% → `/quality-debug {phase}`
 - Coverage still low → `/quality-auto-test {phase} --layer {missing}`

package/maestro-flow/commands/quality/debug.md

@@ -49,6 +49,14 @@ Extract conclusions from related artifacts that may affect this debug session
 2. **Wiki prior knowledge**: Run `maestro wiki search "<symptom keywords>" --json 2>/dev/null`. If results found, check for prior investigations on similar issues to avoid re-investigation.
 3. Both are optional — proceed without if unavailable.
 
+### 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
+
 **Output**: `DEBUG_DIR = .workflow/scratch/{YYYYMMDD}-debug-P{N}-{slug}/` (P{N} = phase number when phase-scoped; omit for standalone). Output directory rules defined in workflow debug.md Step 4.
 </context>
 

package/maestro-flow/commands/quality/retrospective.md

@@ -1,6 +1,6 @@
 ---
 name: quality-retrospective
-description: Phase retrospective with insight routing to specs and lessons
+description: Phase retrospective with insight routing to specs and knowhow
 argument-hint: "[phase|N..M] [--lens technical|process|quality|decision] [--all] [--no-route] [--compare N] [-y]"
 allowed-tools:
   - Read
@@ -13,7 +13,7 @@ allowed-tools:
   - AskUserQuestion
 ---
 <purpose>
-Post-execution multi-perspective retrospective (复盘) for completed phases. Consumes existing execution artifacts (verification.json, review.json, issues.jsonl, plan.json, .summaries/, uat.md, state.json) and runs four parallel lenses — technical, process, quality, decision — to distill reusable insights. Routes each insight into the appropriate store: spec stub for reusable patterns, memory tip for process notes, issue for recurring gaps. Auto-scans for unreviewed completed phases and reports the backlog. Every insight is also persisted to `.workflow/learning/lessons.jsonl` for cross-phase queryability.
+Post-execution multi-perspective retrospective (复盘) for completed phases. Consumes existing execution artifacts (verification.json, review.json, issues.jsonl, plan.json, .summaries/, uat.md, state.json) and runs four parallel lenses — technical, process, quality, decision — to distill reusable insights. Routes each insight into the appropriate store: spec stub for reusable patterns, memory tip for process notes, issue for recurring gaps. Auto-scans for unreviewed completed phases and reports the backlog. Every insight is also persisted to `.workflow/knowhow/specs/learnings.md` as `<spec-entry>` blocks for cross-phase queryability.
 </purpose>
 
 <required_reading>
@@ -70,9 +70,8 @@ Follow `~/.maestro/workflows/retrospective.md` Stages 1–8 in order. Key invari
 - [ ] Spec entries (if any) appended as `<spec-entry>` to matching `.workflow/specs/{category-file}.md`
 - [ ] Issue rows (if any) match canonical issues.jsonl schema (status "open", full issue_history, all required fields)
 - [ ] Note tips (if any) created via `Skill({ skill: "manage-learn", args: "tip ..." })`
-- [ ] `lessons.jsonl` appended with one row per insight regardless of routing target
-- [ ] `learning-index.json` updated and parseable
+- [ ] `specs/learnings.md` appended with one `<spec-entry>` per insight regardless of routing target
 - [ ] No existing phase artifacts modified (verification.json, review.json, plan.json untouched)
 - [ ] Confirmation banner displays routing counts and next-step suggestions
-- [ ] Next step: `/manage-status` to review state, or `/manage-issue list --source retrospective` to triage created issues, or `/manage-learn list` to browse the lessons library
+- [ ] Next step: `/manage-status` to review state, or `/manage-issue list --source retrospective` to triage created issues, or `/manage-learn list` to browse the knowhow library
 </success_criteria>

package/maestro-flow/commands/quality/review.md

@@ -54,6 +54,14 @@ Extract conclusions from related artifacts that may affect this review. Pass as
 2. **Wiki constraints**: Run `maestro wiki search "architecture constraint" --json 2>/dev/null`. If results found, pass as `wiki_context` to reviewer agents for evaluating code against documented decisions.
 3. Both are optional — proceed without if unavailable.
 
+### Role Knowledge
+1. Browse accumulated knowledge for this role:
+   `maestro wiki list --category review`
+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
+
 **Output**: `REVIEW_DIR = .workflow/scratch/{YYYYMMDD}-review-P{N}-{slug}/` (P{N} = phase number, enables directory-level identification as state.json fallback)
 </context>
 

package/maestro-flow/commands/spec/add.md

@@ -1,6 +1,6 @@
 ---
 name: spec-add
-description: Add spec entry by category
+description: Add spec entry by category with role tagging
 argument-hint: "[--scope project|global|team|personal] <category> <content>"
 allowed-tools:
   - Read
@@ -13,6 +13,7 @@ allowed-tools:
 Add a knowledge entry to the specs system using `<spec-entry>` closed-tag format.
 Each category maps 1:1 to a single target file — no dual-write.
 Supports 4 scopes: project (default), global, team, personal.
+Entries use `category` attribute to declare which category they belong to.
 </purpose>
 
 <required_reading>
@@ -22,7 +23,22 @@ Supports 4 scopes: project (default), global, team, personal.
 <context>
 $ARGUMENTS -- expects `[--scope <scope>] [--uid <uid>] <category> <content>`
 
+**Options:**
+- `--ref <path>` — Create as index entry referencing a knowhow document. If the path exists, only creates the spec index entry. If path doesn't exist, also creates the knowhow file.
+- `--knowhow-type <type>` — Knowhow document type when creating with --ref (asset, blueprint, document, template, recipe, reference, decision)
+
 Scope-to-directory mapping, category-to-file mapping, and entry format defined in workflow specs-add.md.
+
+**Examples:**
+```bash
+# Standard spec entry
+/spec-add coding "Named exports" "Always use named exports" --keywords "exports,naming"
+
+# Spec with ref to detailed knowhow
+/spec-add coding "OAuth PKCE Flow" "完整 PKCE 集成流程" --ref knowhow/RCP-oauth-pkce.md --keywords "oauth,pkce"
+
+/spec-add arch "OAuth PKCE 集成" "完整流程设计" --ref knowhow/AST-oauth-flow.md
+```
 </context>
 
 <execution>
@@ -34,7 +50,7 @@ Follow '~/.maestro/workflows/specs-add.md' completely.
 |------|----------|-------------|-------|
 | E001 | fatal | Category and content are both required | parse_input |
 | E002 | fatal | Specs directory not initialized -- run `maestro spec init --scope <scope>` | validate_entry |
-| E003 | fatal | Invalid category -- must be one of: coding, arch, quality, debug, test, review, learning | parse_input |
+| E003 | fatal | Invalid category -- must be one of: coding, arch, quality, debug, test, review, learning, tools | parse_input |
 | E004 | fatal | Invalid scope -- must be one of: project, global, team, personal | parse_input |
 | E005 | fatal | Personal scope requires uid -- use `--uid` or run `maestro collab join` first | parse_input |
 </error_codes>

package/maestro-flow/commands/spec/load.md

@@ -1,7 +1,7 @@
 ---
 name: spec-load
 description: Load specs and lessons for current context
-argument-hint: "[--category <type>] [--keyword <word>] [--with-lessons]"
+argument-hint: "[--category <category>] [--keyword <word>]"
 allowed-tools:
   - Read
   - Bash
@@ -9,8 +9,8 @@ allowed-tools:
   - Grep
 ---
 <purpose>
-Load and display relevant spec files for the current working context.
-Supports filtering by category (file-level) and keyword (entry-level via `<spec-entry>` tags).
+Load relevant specs filtered by category (file-level) and/or keyword (entry-level).
+Category-based loading: loads the category's primary doc in full + matching entries from other files.
 </purpose>
 
 <required_reading>
@@ -20,14 +20,33 @@ Supports filtering by category (file-level) and keyword (entry-level via `<spec-
 <context>
 $ARGUMENTS -- optional flags and keyword
 
-Category-to-file mapping (1:1) and flag details defined in workflow specs-load.md.
+**Flags:**
+- `--category <category>` — Load by category: primary category doc (full) + cross-file entries with matching category attr. Categories: coding, arch, test, review, debug, quality, learning.
+- `--keyword <word>` — Filter by keyword within entries
+
+**File → Primary Category mapping:**
+| File | Category |
+|------|----------|
+| coding-conventions.md | coding |
+| architecture-constraints.md | arch |
+| test-conventions.md | test |
+| review-standards.md | review |
+| debug-notes.md | debug |
+| quality-rules.md | quality |
+| learnings.md | learning |
 
 **Examples:**
 ```
+/spec-load --category coding            # coding全文 + 跨文件coding条目
+/spec-load --category review            # review-standards + quality-rules + 跨文件review条目
+/spec-load --category coding --keyword auth
 /spec-load --keyword auth
-/spec-load --category coding --keyword naming
-/spec-load --category arch
 ```
+
+**Ref entries:**
+When loading entries with `ref` attribute, only the summary is shown with a load command:
+  → Detail: maestro wiki load <knowhow-id>
+Use the load command to read the full referenced document.
 </context>
 
 <execution>

package/maestro-flow/commands/spec/setup.md

@@ -11,7 +11,7 @@ allowed-tools:
 ---
 <purpose>
 Initialize the project-level specs directory by scanning the codebase for conventions, patterns, and tech stack.
-Core files (coding, arch, learning) are always created. Optional files (quality, debug, test, review) are created only when relevant signals are detected.
+Core files (coding, arch, knowhow) are always created. Optional files (quality, debug, test, review) are created only when relevant signals are detected.
 All output lands in `.workflow/specs/`.
 </purpose>
 
@@ -44,7 +44,7 @@ Follow '~/.maestro/workflows/specs-setup.md' completely.
 
 <success_criteria>
 - [ ] `.workflow/specs/` directory created
-- [ ] Core files always created: `coding-conventions.md`, `architecture-constraints.md`, `learnings.md`
+- [ ] Core files always created: `coding-conventions.md`, `architecture-constraints.md`, `knowhow.md`
 - [ ] Optional files created when detected: `quality-rules.md` (linter/CI), `test-conventions.md` (test framework), `debug-notes.md` (on demand), `review-standards.md` (on demand)
 - [ ] Report displayed with summary and next steps
 </success_criteria>

package/maestro-flow/commands/wiki/connect.md

@@ -56,7 +56,7 @@ Follow '~/.maestro/workflows/wiki-connect.md' completely (Stages 1-6).
 - [ ] If --fix: entries updated with new `related` links
 - [ ] If --fix: new health score computed and delta reported
 - [ ] Report written to `wiki-connections-{date}.md`
-- [ ] Graph insights appended to `lessons.jsonl`
+- [ ] Graph insights appended to `specs/learnings.md` as `<spec-entry>` blocks
 - [ ] No unintended entry modifications (only `related` field changed)
 - [ ] Summary displayed with next-step routing
 </success_criteria>

package/maestro-flow/commands/wiki/digest.md

@@ -48,7 +48,7 @@ Follow '~/.maestro/workflows/wiki-digest.md' completely (Stages 1-8).
 | E001 | error | No wiki entries found (empty index) | Initialize wiki content first |
 | E002 | error | Topic search returned 0 results | Broaden topic or check wiki content |
 | W001 | warning | Too few entries (<5) for meaningful theme clustering | Digest produced but themes may be trivial |
-| W002 | warning | lessons.jsonl not found — skipping cross-reference | Proceed without lesson context |
+| W002 | warning | specs/learnings.md not found — skipping cross-reference | Proceed without knowhow context |
 | W003 | warning | Some entry bodies failed to load — partial summaries | Note incomplete entries in digest |
 </error_codes>
 
@@ -57,13 +57,12 @@ Follow '~/.maestro/workflows/wiki-digest.md' completely (Stages 1-8).
 - [ ] Baseline health score recorded
 - [ ] Entries clustered into 3-5 semantic themes
 - [ ] Per-theme analysis: summary, key entries, gaps, health
-- [ ] Cross-reference with lessons.jsonl completed
+- [ ] Cross-reference with specs/learnings.md completed
 - [ ] Coverage heatmap generated (type × theme matrix)
 - [ ] Knowledge gaps identified with suggested actions
 - [ ] If `--create-issues`: gap issues created in `issues.jsonl` (deduped)
-- [ ] Digest written to `digest-{slug}-{date}.md`
-- [ ] Meta-insights appended to `lessons.jsonl`
-- [ ] `learning-index.json` updated
-- [ ] No files modified outside `.workflow/learning/` and `.workflow/issues/` (issues only when `--create-issues`)
+- [ ] Digest written to `KNW-digest-{slug}-{date}.md`
+- [ ] Meta-insights appended to `specs/learnings.md` as `<spec-entry>` blocks
+- [ ] No files modified outside `.workflow/knowhow/` and `.workflow/issues/` (issues only when `--create-issues`)
 - [ ] Summary displayed with key findings and next-step routing
 </success_criteria>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maestro-flow-one",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "All Maestro workflow commands as a single Claude Code skill — intent routing, decision gates, minimal closed-loop chains",
   "bin": {
     "maestro-flow": "bin/maestro-flow.js"