docs: jam knowledgebase plan, backlog, curricula + /kb-expand loop skill

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-06-12 12:31:45 +01:00
parent f583979b3e
commit fdb2ce8175
6 changed files with 727 additions and 0 deletions
@@ -0,0 +1,51 @@
+---
+name: kb-expand
+description: Expand the JamBuddy jam knowledgebase by exactly one style × instrument cell — research, author, validate, commit. Run repeatedly (or via /loop) to fill the backlog in docs/kb-backlog.md.
+---
+
+# KB Expand — one cell per session
+
+You are expanding JamBuddy's jam knowledgebase: intermediate-level standard progressions and ways to play them, per style × instrument. **Do exactly one cell, end to end.** Small, validated, committed.
+
+## Steps
+
+### 1. Orient (always, every session)
+Read, in this order:
+- `docs/kb-plan.md` — architecture, schema conventions, quality gates, success criteria
+- `docs/kb-backlog.md` — the queue
+- `src/data/kb/SCHEMA.md` and the gold standard `src/data/kb/jazz/guitar.js` — **if they exist**
+- `docs/progression-repertoire.md` §1 — cross-check progressions for the style
+- `docs/learn-curriculum.md` — the intermediate level definition for the instrument
+
+### 2. Claim a cell
+Take the **first `todo` cell** in the backlog (respect the order: bootstrap → guitar → piano → bass). Mark it `in-progress` in `docs/kb-backlog.md`.
+
+**If the foundation doesn't exist yet (no `src/data/kb/`), this session is Session 0:** build `src/data/kb/` with `index.js` registry, `SCHEMA.md` (formats from kb-plan.md §1, one fully-worked example, the musician checklist from §2), `scripts/validate-kb.mjs` (all mechanical checks from kb-plan.md §2 — especially the pitch-class verification of guitar shapes against chord qualities from `src/lib/theory.js` CHORD_TYPES), and the **jazz/guitar** cell as the gold standard. That is one full session; stop after it.
+
+### 3. Research
+Dispatch 1-2 web-research subagents for the claimed style × instrument:
+- the style's standard progressions (verify against `docs/progression-repertoire.md`; add style-specific ones with named sources)
+- 2-3 genuinely different intermediate ways to play each progression on this instrument (voicings with exact frets/fingerings for guitar, degree recipes for piano, line patterns for bass)
+- comping rhythm(s) characteristic of the style, improv guidance (scales over each chord, target notes, 1-2 licks)
+- require named sources/URLs in the agent's report
+
+### 4. Author
+Write `src/data/kb/<style>/progressions.js` (if new style) and `src/data/kb/<style>/<instrument>.js` per SCHEMA.md. Key-agnostic only: degrees and movable shapes (`rootStr` + `offsets`), open shapes with `onlyRoot`. Qualities must be keys of `CHORD_TYPES` in `src/lib/theory.js`. Register the style in `src/data/kb/index.js`.
+
+### 5. Validate — hard gate
+- `node scripts/validate-kb.mjs` must pass. Fix content, don't weaken the validator.
+- Run the musician checklist in SCHEMA.md; cut or fix anything that fails it.
+- `npm run build` must pass.
+
+### 6. Record and commit
+- Backlog: mark the cell `done (YYYY-MM-DD, N progressions × M plays)`.
+- Commit on the current branch: `kb: add <style> <instrument> pack` (or `kb: bootstrap foundation + jazz guitar gold standard`). Do not push unless asked.
+
+### 7. Report
+Tell the user: what was added (progressions, plays, sources), validator result, and **the next cell in the queue**. If a UI milestone in the backlog just became unblocked (e.g. Jam Guide MVP after cell 0), say so explicitly.
+
+## Rules
+- One cell per invocation. Never start a second cell, even if the first went quickly.
+- Never commit content that fails the validator; never relax a validator rule to make content pass — flag the conflict to the user instead.
+- Intermediate level: no 5+ fret stretches, no advanced-only voicings without an intermediate alternative in the same play set.
+- Plays per progression must be idiomatically different (register/density/technique), not transpositions of each other.