maestro-flow 0.3.43 → 0.3.44

package/.codex/skills/codify-to-knowhow/SKILL.md

@@ -0,0 +1,427 @@
+---
+name: codify-to-knowhow
+description: Manifest-driven knowledge asset generator — converts structured packages into knowhow + spec entries
+argument-hint: "<package-path>"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+<purpose>
+Sequential manifest-driven knowledge asset generator. Reads `knowhow-manifest.json` from a package directory, writes knowhow files and spec entries with ref linking. No wave execution needed — pure sequential file operations.
+
+**Core workflow**: Validate Manifest -> Write Knowhow Files -> Write Spec Entries -> Verify & Index
+
+```
++---------------------------------------------------------------------------+
+|                  CODIFY TO KNOWHOW (Direct Execution)                     |
++---------------------------------------------------------------------------+
+|                                                                           |
+|  Step 1: Parse package-path from $ARGUMENTS                              |
+|                                                                           |
+|  Step 2: Load & Validate knowhow-manifest.json                           |
+|     +-- Validate required fields: slug, roles, knowhow[], specs[]        |
+|     +-- Parse manifest object                                            |
+|                                                                           |
+|  Step 3: Generate Knowhow Assets                                         |
+|     +-- For each manifest.knowhow[]:                                     |
+|     |   +-- Idempotency check (skip if file exists)                      |
+|     |   +-- Build frontmatter + body with <knowhow-entry> tags           |
+|     |   +-- Write to .workflow/knowhow/{PREFIX}-{slug}-{fileSlug}.md     |
+|                                                                           |
+|  Step 4: Generate Spec Entries                                            |
+|     +-- For each manifest.specs[]:                                       |
+|     |   +-- Idempotency check (skip if title exists)                     |
+|     |   +-- Write via maestro spec add CLI (fallback: direct append)     |
+|     |   +-- Include ref attribute linking to knowhow file                |
+|                                                                           |
+|  Step 5: Refresh Wiki Index                                               |
+|     +-- maestro wiki health                                              |
+|                                                                           |
+|  Step 6: Verify & Report                                                  |
+|     +-- Verify knowhow files exist                                       |
+|     +-- Verify spec entries written                                      |
+|     +-- Verify ref links resolve                                         |
+|     +-- Output completion report                                         |
+|                                                                           |
++---------------------------------------------------------------------------+
+```
+
+</purpose>
+
+<context>
+```bash
+$codify-to-knowhow ".workflow/reference_style/my-style-v1"
+```
+
+**Arguments**:
+- `<package-path>` (positional, required): Directory containing `knowhow-manifest.json`
+
+**Upstream**: `maestro-ui-codify`, `learn-decompose`, or any skill that generates a manifest
+**Downstream**: `maestro wiki list --role implement`, `maestro spec load --keyword <slug>`
+</context>
+
+<manifest_schema>
+
+### knowhow-manifest.json
+
+```json
+{
+  "slug": "my-style-v1",
+  "domain": "ui-design",
+  "roles": ["implement", "review"],
+  "packagePath": ".workflow/reference_style/my-style-v1",
+
+  "knowhow": [
+    {
+      "prefix": "AST",
+      "fileSlug": "tokens",
+      "title": "Design Tokens",
+      "category": "asset",
+      "assetType": "design-tokens",
+      "codePaths": ["src/styles/"],
+      "tags": ["design-tokens", "colors"],
+      "body": "## Colors\n\n...",
+      "entries": [
+        {
+          "category": "pattern",
+          "keywords": "colors,tokens",
+          "title": "Color System",
+          "body": "## Colors\n\n..."
+        }
+      ]
+    }
+  ],
+
+  "specs": [
+    {
+      "category": "coding",
+      "keywords": "colors,design-tokens",
+      "title": "Color Coding Convention",
+      "ref": "knowhow/AST-my-style-v1-tokens.md",
+      "body": "Use var(--color-primary) for primary colors..."
+    }
+  ]
+}
+```
+
+**Required fields**:
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `slug` | Yes | Package slug, used in file naming |
+| `roles` | Yes | Role annotation array |
+| `knowhow` | Yes | Knowhow asset declarations (can be empty) |
+| `specs` | Yes | Spec entry declarations (can be empty) |
+| `domain` | No | Domain identifier (ui-design, api, data) |
+| `packagePath` | No | Original package path (metadata) |
+
+**knowhow[] item fields**:
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `prefix` | Yes | File prefix: AST, DCS, BLP, TIP, RCP, REF |
+| `fileSlug` | Yes | File name suffix (e.g. "tokens") |
+| `title` | Yes | Document title |
+| `category` | Yes | asset, decision, blueprint, tip, recipe, reference |
+| `tags` | Yes | Tag array |
+| `body` | Yes | Markdown body content |
+| `assetType` | No | Asset subtype (design-tokens, components, etc.) |
+| `codePaths` | No | Related source code paths |
+| `entries` | No | Sub-entries with `<knowhow-entry>` closed tags |
+
+**specs[] item fields**:
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `category` | Yes | coding, arch, quality, debug, test, review, learning |
+| `title` | Yes | Entry title |
+| `keywords` | Yes | Comma-separated keywords |
+| `body` | Yes | Entry body text |
+| `ref` | No | Reference path to knowhow file |
+
+</manifest_schema>
+
+<invariants>
+1. **Manifest Required**: No manifest = error exit, no fallback
+2. **Idempotent Writes**: Same-slug file exists = skip, never overwrite
+3. **Closed Tags**: All entries use `<spec-entry>` / `<knowhow-entry>` closed-tag format
+4. **Upstream Generates Manifest**: This skill only writes, never extracts knowledge
+5. **CLI First, File Fallback**: Prefer `maestro spec add` CLI; fall back to direct file append on failure
+6. **Ref Bridge**: Spec entries reference knowhow files via `ref` attribute
+</invariants>
+
+<execution>
+
+### Step 1: Parse Package Path
+
+**Parse from `$ARGUMENTS`**:
+
+| Variable | Source | Default |
+|----------|--------|---------|
+| `package_path` | positional (required) | ERROR if missing |
+
+```bash
+package_path="${PACKAGE_PATH}"
+
+# Validate directory exists
+test -d "$package_path" || { echo "ERROR: Package path not found: $package_path"; exit 1; }
+
+# Validate manifest exists
+manifest_file="${package_path}/knowhow-manifest.json"
+test -f "$manifest_file" || { echo "ERROR: knowhow-manifest.json not found in $package_path"; exit 1; }
+```
+
+### Step 2: Load & Validate Manifest
+
+Read `${package_path}/knowhow-manifest.json` and validate:
+
+```javascript
+const manifest = JSON.parse(manifestContent);
+
+// Required field validation
+const required = ['slug', 'roles', 'knowhow', 'specs'];
+const missing = required.filter(f => !manifest[f]);
+if (missing.length > 0) {
+  ERROR("Missing required fields: " + missing.join(', '));
+  EXIT(1);
+}
+
+// Summary
+REPORT(`Manifest loaded:
+  Slug: ${manifest.slug}
+  Domain: ${manifest.domain || 'generic'}
+  Roles: ${manifest.roles.join(', ')}
+  Knowhow assets: ${manifest.knowhow.length}
+  Spec entries: ${manifest.specs.length}
+`);
+```
+
+### Step 3: Generate Knowhow Assets
+
+Ensure `.workflow/knowhow/` exists. For each `manifest.knowhow[]` item:
+
+```bash
+mkdir -p .workflow/knowhow
+```
+
+```javascript
+const knowhowPaths = [];
+
+for (const asset of manifest.knowhow) {
+  const filename = `${asset.prefix}-${manifest.slug}-${asset.fileSlug}.md`;
+  const filepath = `.workflow/knowhow/${filename}`;
+
+  // Idempotency check
+  if (fileExists(filepath)) {
+    REPORT(`SKIP: ${filename} (already exists)`);
+    continue;
+  }
+
+  // Build frontmatter
+  let frontmatter = `---
+title: ${asset.title}
+type: ${asset.category}`;
+
+  if (asset.assetType) {
+    frontmatter += `\nassetType: ${asset.assetType}`;
+  }
+
+  frontmatter += `\nroles: [${manifest.roles.join(', ')}]`;
+
+  if (asset.codePaths && asset.codePaths.length > 0) {
+    frontmatter += `\ncodePaths:`;
+    for (const cp of asset.codePaths) {
+      frontmatter += `\n  - ${cp}`;
+    }
+  }
+
+  frontmatter += `\ntags: [${asset.tags.join(', ')}]`;
+  frontmatter += `\n---`;
+
+  // Build body
+  let body = asset.body || '';
+
+  // If entries[], generate <knowhow-entry> closed tags
+  if (asset.entries && asset.entries.length > 0) {
+    const today = new Date().toISOString().split('T')[0];
+    for (let i = 0; i < asset.entries.length; i++) {
+      const entry = asset.entries[i];
+      const entryId = `${asset.prefix}-${manifest.slug}-${String(i + 1).padStart(3, '0')}`;
+      body += `\n\n<knowhow-entry keywords="${entry.category},${entry.keywords}" date="${today}" id="${entryId}" roles="${manifest.roles.join(',')}" source="codify-to-knowhow">
+
+### ${entry.title}
+
+${entry.body}
+
+</knowhow-entry>`;
+    }
+  }
+
+  const content = `${frontmatter}\n\n${body}`;
+  Write(filepath, content);
+  REPORT(`CREATED: ${filename}`);
+  knowhowPaths.push(filepath);
+}
+
+const skippedCount = manifest.knowhow.length - knowhowPaths.length;
+REPORT(`Knowhow assets: ${knowhowPaths.length} created, ${skippedCount} skipped`);
+```
+
+### Step 4: Generate Spec Entries
+
+For each `manifest.specs[]` item, write spec entry with `<spec-entry>` closed tag:
+
+```javascript
+const categoryFileMap = {
+  coding: 'coding-conventions.md',
+  arch: 'architecture-constraints.md',
+  quality: 'quality-rules.md',
+  debug: 'debug-notes.md',
+  test: 'test-conventions.md',
+  review: 'review-standards.md',
+  learning: 'learnings.md'
+};
+
+const today = new Date().toISOString().split('T')[0];
+let specEntryCount = 0;
+
+for (const spec of manifest.specs) {
+  const targetFile = `.workflow/specs/${categoryFileMap[spec.category]}`;
+
+  // Idempotency: check if title already exists
+  const titleExists = Bash(`grep -q "${spec.title}" "${targetFile}" 2>/dev/null && echo "exists" || echo "new"`);
+
+  if (titleExists.trim() === 'exists') {
+    REPORT(`SKIP spec: "${spec.title}" (already exists in ${spec.category})`);
+    continue;
+  }
+
+  // Build spec-entry closed tag
+  let refAttr = '';
+  if (spec.ref) {
+    refAttr = `\n  ref="${spec.ref}"`;
+  }
+
+  const entryBlock = `
+
+<spec-entry roles="${manifest.roles.join(',')}" keywords="${spec.keywords}" date="${today}"${refAttr}>
+
+### ${spec.title}
+
+${spec.body}
+
+</spec-entry>`;
+
+  // Prefer CLI, fallback to direct append
+  const cliResult = Bash(`maestro spec add ${spec.category} "${spec.title}" "${spec.body}" --keywords "${spec.keywords}" 2>/dev/null`);
+
+  if (cliResult.exitCode !== 0) {
+    // Fallback: direct file append
+    Edit(targetFile, { append: entryBlock });
+  }
+
+  specEntryCount++;
+  REPORT(`CREATED spec: "${spec.title}" -> ${spec.category}`);
+}
+
+REPORT(`Spec entries: ${specEntryCount} created`);
+```
+
+### Step 5: Refresh Wiki Index
+
+```bash
+maestro wiki health 2>/dev/null || echo "Wiki index refresh skipped (command not available)"
+```
+
+### Step 6: Verify & Report
+
+**6a: Verify knowhow files**:
+
+```bash
+echo "=== Knowhow Asset Verification ==="
+for file in ${knowhowPaths}; do
+  if test -f "$file"; then
+    echo "  OK: $file"
+  else
+    echo "  MISSING: $file"
+  fi
+done
+```
+
+**6b: Verify spec entries**:
+
+```bash
+echo "=== Spec Entry Verification ==="
+grep -c "${slug}" .workflow/specs/coding-conventions.md 2>/dev/null && \
+  echo "  OK: coding-conventions.md" || echo "  MISSING: No entries in coding-conventions.md"
+
+grep -c "${slug}" .workflow/specs/architecture-constraints.md 2>/dev/null && \
+  echo "  OK: architecture-constraints.md" || echo "  MISSING: No entries in architecture-constraints.md"
+```
+
+**6c: Verify ref links**:
+
+```bash
+echo "=== Ref Link Verification ==="
+refs=$(grep -oP 'ref="knowhow/[^"]*"' .workflow/specs/coding-conventions.md .workflow/specs/architecture-constraints.md 2>/dev/null | grep "${slug}" || true)
+
+if [ -n "$refs" ]; then
+  echo "$refs" | while IFS= read -r ref; do
+    filepath=$(echo "$ref" | grep -oP 'knowhow/[^"]*')
+    if test -f ".workflow/$filepath"; then
+      echo "  OK: $filepath"
+    else
+      echo "  BROKEN: $filepath (file not found)"
+    fi
+  done
+else
+  echo "  WARNING: No ref links found for ${slug}"
+fi
+```
+
+**6d: Completion report**:
+
+```
+=== Codify to Knowhow Complete ===
+
+Package: {slug}
+Source: {packagePath}
+
+Knowhow Assets:
+  {list of created/skipped files}
+
+Spec Entries ({specEntryCount} created):
+  {list of created/skipped entries by category}
+
+Ref Links: spec -> knowhow bridge established
+Wiki Index: refreshed
+
+Next steps:
+  maestro wiki list --role implement    # Browse by role
+  maestro spec load --keyword {slug}    # Load related specs
+  maestro wiki load <id>                # Load full entry
+```
+
+</execution>
+
+<error_codes>
+
+| Error | Resolution |
+|-------|------------|
+| Package path not found | Abort: "Package path not found: {path}" |
+| Manifest not found | Abort: "knowhow-manifest.json not found in {path}" |
+| Missing required fields | Abort: "Missing required fields: {list}" |
+| Idempotent conflict | Skip existing assets, report skip count |
+| CLI spec add failed | Fallback to direct file append |
+| Wiki health failed | Warning, continue (non-critical) |
+
+</error_codes>
+
+<success_criteria>
+- [ ] Package path validated and manifest loaded
+- [ ] All required manifest fields present
+- [ ] Knowhow files written to .workflow/knowhow/ (idempotent)
+- [ ] Spec entries written with <spec-entry> closed tags (idempotent)
+- [ ] Ref links from specs point to existing knowhow files
+- [ ] Wiki index refreshed
+- [ ] Completion report with asset counts
+</success_criteria>

package/.codex/skills/learn-decompose/SKILL.md

@@ -8,7 +8,7 @@ allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUser
 <purpose>
 Systematic pattern extraction from code via CSV wave pipeline. 4 parallel dimension agents
 scan a module, then a cross-reference agent deduplicates against existing patterns and
-produces a catalog. Discovered patterns persist to `lessons.jsonl` and optionally to
+produces a catalog. Discovered patterns persist to `specs/learnings.md` and optionally to
 specs (via `spec-add`) and wiki.
 
 ```
@@ -32,7 +32,7 @@ $ARGUMENTS — target path/module and optional flags.
 - `--save-spec`: Invoke `spec-add` for each new pattern
 - `--save-wiki`: Create wiki note entries per dimension group
 
-**Output**: `.workflow/.csv-wave/{session-id}/` + `.workflow/learning/decompose-{slug}-{date}.md`
+**Output**: `.workflow/.csv-wave/{session-id}/` + `.workflow/knowhow/KNW-decompose-{slug}-{date}.md`
 </context>
 
 <invariants>
@@ -40,7 +40,7 @@ $ARGUMENTS — target path/module and optional flags.
 2. **Evidence required**: Every finding must have file:line anchors
 3. **Dedup before persist**: Cross-reference against existing specs + lessons
 4. **Stable IDs**: INS-id from `hash("decompose" + target + pattern_name)`
-5. **No files modified outside** `.workflow/learning/` (and optionally specs/wiki)
+5. **No files modified outside** `.workflow/knowhow/` (and optionally specs/wiki)
 </invariants>
 
 <execution>
@@ -50,7 +50,7 @@ $ARGUMENTS — target path/module and optional flags.
 Parse flags from `$ARGUMENTS`: `-y`/`--yes`, `--patterns <list>`, `--save-spec`, `--save-wiki`, `--continue`, `-c N`.
 Extract remaining text as target path/module.
 
-Resolve target to file list. Load existing patterns from `coding-conventions.md` + `lessons.jsonl` for dedup set.
+Resolve target to file list. Load existing patterns from `coding-conventions.md` + `specs/learnings.md` for dedup set.
 
 ### Phase 2: Wave 1 — Parallel Dimension Scans
 
@@ -87,8 +87,8 @@ Single agent receives all wave 1 findings via `prev_context`. Tasks:
 
 ### Phase 4: Persist
 
-1. Write `decompose-{slug}-{date}.md` with full catalog
-2. Append each **new** pattern to `lessons.jsonl` (source: "decompose", category: "pattern")
+1. Write `KNW-decompose-{slug}-{date}.md` with full catalog
+2. Append each **new** pattern to `specs/learnings.md` (source: "decompose", category: "pattern")
 3. If `--save-spec`: invoke `spec-add` per new pattern
 4. If `--save-wiki`: create wiki note per dimension group
 </execution>
@@ -107,7 +107,7 @@ Single agent receives all wave 1 findings via `prev_context`. Tasks:
 - [ ] 4 dimension agents spawned in parallel via spawn_agents_on_csv
 - [ ] Each finding has: name, dimension, confidence, anchors, description
 - [ ] Cross-reference performed (documented / known / new)
-- [ ] Pattern catalog written to `decompose-{slug}-{date}.md`
-- [ ] New patterns appended to `lessons.jsonl` with stable INS-ids
+- [ ] Pattern catalog written to `KNW-decompose-{slug}-{date}.md`
+- [ ] New patterns appended to `specs/learnings.md` with stable INS-ids
 - [ ] If --save-spec / --save-wiki: entries created
 </success_criteria>

package/.codex/skills/learn-follow/SKILL.md

@@ -8,7 +8,7 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 <purpose>
 Guided reading experience for code files, wiki entries, or topics. Walks through content
 section by section using 4 forcing questions to extract patterns, identify assumptions,
-and build a structured understanding map. Insights persist to `lessons.jsonl`.
+and build a structured understanding map. Insights persist to `specs/learnings.md`.
 
 Unlike `learn-decompose` which is parallel pattern extraction, this is sequential
 deep reading that builds understanding incrementally.
@@ -27,7 +27,7 @@ $ARGUMENTS — target and optional flags.
 - `--depth deep` — Every function, branch, assumption
 - `--save-wiki` — Create wiki note with reading notes
 
-**Output**: `.workflow/learning/follow-{slug}-{date}.md`
+**Output**: `.workflow/knowhow/KNW-follow-{slug}-{date}.md`
 </context>
 
 <execution>
@@ -56,8 +56,8 @@ From forcing question answers, extract: design patterns (with file:line anchors)
 Cross-reference against `coding-conventions.md`: documented vs undocumented patterns.
 
 ### Stage 5: Persist
-1. Write `follow-{slug}-{date}.md` with understanding map
-2. Append new patterns to `lessons.jsonl` (source: "follow", stable INS-ids)
+1. Write `KNW-follow-{slug}-{date}.md` with understanding map
+2. Append new patterns to `specs/learnings.md` (source: "follow", stable INS-ids)
 3. If `--save-wiki`: create wiki note entry
 
 **Next steps:** `/learn-decompose <path>`, `/spec-add coding ...`, `/learn-second-opinion <file>`
@@ -78,6 +78,6 @@ Cross-reference against `coding-conventions.md`: documented vs undocumented patt
 - [ ] All 4 forcing questions applied per section
 - [ ] Patterns extracted with file:line anchors
 - [ ] Understanding map produced with concepts, patterns, assumptions, questions
-- [ ] `follow-{slug}-{date}.md` written
-- [ ] `lessons.jsonl` appended with stable INS-ids
+- [ ] `KNW-follow-{slug}-{date}.md` written
+- [ ] `specs/learnings.md` appended with stable INS-ids
 </success_criteria>

package/.codex/skills/learn-investigate/SKILL.md

@@ -21,14 +21,14 @@ $ARGUMENTS — question text and optional flags.
 - `--scope <path>` — Restrict to files under this directory (default: entire project)
 - `--max-hypotheses N` — Max hypotheses before escalating (default: 3)
 
-**Output**: `.workflow/learning/investigate-{slug}/` (evidence.ndjson, understanding.md, report.md)
+**Output**: `.workflow/knowhow/KNW-investigate-{slug}/` (evidence.ndjson, understanding.md, report.md)
 </context>
 
 <execution>
 
 ### Stage 1: Frame the Question
 - Parse question, generate slug, create investigation directory
-- Search prior knowledge: wiki search, grep lessons.jsonl, read debug-notes.md
+- Search prior knowledge: wiki search, grep specs/learnings.md, read debug-notes.md
 - Write initial `understanding.md`
 
 ### Stage 2: Evidence Collection
@@ -54,7 +54,7 @@ If all hypotheses fail: broaden scope, search wiki with alt keywords, or mark IN
 
 ### Stage 5: Synthesize + Persist
 1. Write `report.md` with answer, evidence trail, hypothesis results
-2. Append to `lessons.jsonl`:
+2. Append to `specs/learnings.md`:
    - Confirmed → category: "technique" / "pattern"
    - Disproved → category: "gotcha"
 3. Display summary with next-step routing
@@ -78,6 +78,6 @@ If all hypotheses fail: broaden scope, search wiki with alt keywords, or mark IN
 - [ ] At least 1 hypothesis formed and tested
 - [ ] understanding.md tracks evolving understanding
 - [ ] report.md written with answer and evidence trail
-- [ ] Findings appended to lessons.jsonl with stable INS-ids
+- [ ] Findings appended to specs/learnings.md with stable INS-ids
 - [ ] 3-strike escalation triggered if all hypotheses fail
 </success_criteria>

package/.codex/skills/learn-retro/SKILL.md

@@ -22,7 +22,7 @@ $ARGUMENTS — lens selection and scope flags.
 **Git flags:** `--days N` (default: 7), `--author <name>`, `--area <path>`, `--compare`
 **Decision flags:** `--phase N`, `--tag <tag>`, `--id <id>`
 
-**Output**: `.workflow/learning/retro-{date}.md` + `retro-{date}.json`
+**Output**: `.workflow/knowhow/KNW-retro-{date}.md` + `KNW-retro-{date}.json`
 </context>
 
 <execution>
@@ -41,7 +41,7 @@ $ARGUMENTS — lens selection and scope flags.
 **Trend comparison** if prior `retro-*.json` exists.
 
 ### Phase 3: Decision Lens (skip if --lens git)
-**3a: Collect decisions** from wiki, specs, git log, phase context, lessons.jsonl.
+**3a: Collect decisions** from wiki, specs, git log, phase context, specs/learnings.md.
 **3b: Build decision registry** per decision (id, title, source, rationale, alternatives, evidence).
 
 **3c: Multi-perspective evaluation** via spawn_agents_on_csv (3 parallel agents):
@@ -55,10 +55,10 @@ $ARGUMENTS — lens selection and scope flags.
 **3d: Classify lifecycle**: Validated / Aging / Questionable / Stale / Reversed.
 
 ### Phase 4: Unified Report
-Write `retro-{date}.md` + `retro-{date}.json` with metrics, sessions, hotspots, decision health, combined insights, recommended actions.
+Write `KNW-retro-{date}.md` + `KNW-retro-{date}.json` with metrics, sessions, hotspots, decision health, combined insights, recommended actions.
 
 ### Phase 5: Persist
-Append insights to `lessons.jsonl` (source: "retro-git" or "retro-decision"). Display summary.
+Append insights to `specs/learnings.md` (source: "retro-git" or "retro-decision"). Display summary.
 
 **Next steps:** `/learn-follow <path>`, `/quality-auto-test <area>`, `/learn-investigate <question>`
 </execution>
@@ -69,7 +69,7 @@ Append insights to `lessons.jsonl` (source: "retro-git" or "retro-decision"). Di
 | E001 | error | Not inside git repo (git lens) | Navigate to git repo |
 | E002 | error | No commits in time window | Increase --days |
 | E003 | error | No decisions found (decision lens) | Check wiki/specs content |
-| W001 | warning | .workflow/learning/ not found | Auto-bootstrap |
+| W001 | warning | .workflow/knowhow/ not found | Auto-bootstrap |
 | W002 | warning | No prior retro for comparison | First retro establishes baseline |
 | W003 | warning | Decision perspective agent failed | Proceed with partial evaluation |
 </error_codes>
@@ -78,6 +78,6 @@ Append insights to `lessons.jsonl` (source: "retro-git" or "retro-decision"). Di
 - [ ] Lens selection parsed correctly
 - [ ] Git lens: metrics computed, sessions detected, hotspots identified
 - [ ] Decision lens: decisions collected, 3 agents spawned in parallel, lifecycle classified
-- [ ] Unified report written to retro-{date}.md + retro-{date}.json
-- [ ] lessons.jsonl appended with insights (stable INS-ids)
+- [ ] Unified report written to KNW-retro-{date}.md + KNW-retro-{date}.json
+- [ ] specs/learnings.md appended with insights (stable INS-ids)
 </success_criteria>

package/.codex/skills/learn-second-opinion/SKILL.md

@@ -11,7 +11,7 @@ Structured second-opinion for code, decisions, or plans. Three modes:
 - **challenge**: single adversarial agent via spawn_agents_on_csv (1 worker)
 - **consult**: interactive Q&A (no CSV wave — direct orchestration)
 
-Findings persist to `lessons.jsonl`. Decoupled from phase lifecycle.
+Findings persist to `specs/learnings.md`. Decoupled from phase lifecycle.
 </purpose>
 
 <context>
@@ -28,7 +28,7 @@ $ARGUMENTS — target and optional flags.
 - `--mode challenge` — Adversarial single-agent analysis
 - `--mode consult` — Interactive Q&A session
 
-**Output**: `.workflow/learning/opinion-{slug}-{date}.md`
+**Output**: `.workflow/knowhow/KNW-opinion-{slug}-{date}.md`
 </context>
 
 <execution>
@@ -61,8 +61,8 @@ Single agent via spawn_agents_on_csv (1 worker). Adversarial analysis with forci
 Interactive loop via AskUserQuestion. Agent studies target, answers questions with code references. Compile Q&A into report on exit.
 
 ### Phase 3: Persist
-1. Write `opinion-{slug}-{date}.md` with per-persona findings + synthesis
-2. Append non-trivial findings to `lessons.jsonl` (source: "second-opinion")
+1. Write `KNW-opinion-{slug}-{date}.md` with per-persona findings + synthesis
+2. Append non-trivial findings to `specs/learnings.md` (source: "second-opinion")
 3. Display summary with verdict and next steps
 
 **Next steps:** `/manage-issue create`, `/learn-decompose <path>`, `/learn-follow <path>`
@@ -81,6 +81,6 @@ Interactive loop via AskUserQuestion. Agent studies target, answers questions wi
 - [ ] Target resolved and context loaded
 - [ ] Mode executed: review (3 parallel agents), challenge (adversarial), or consult (interactive)
 - [ ] Synthesis produced with agreements, disagreements, verdict
-- [ ] Report written to `opinion-{slug}-{date}.md`
-- [ ] Non-trivial findings appended to `lessons.jsonl`
+- [ ] Report written to `KNW-opinion-{slug}-{date}.md`
+- [ ] Non-trivial findings appended to `specs/learnings.md`
 </success_criteria>