JamBuddy/.claude/skills/kb-expand/SKILL.md

name, description

name	description
kb-expand	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.