agents: six-agent ensemble system + /jam-loop conductor

Adds a standing team that builds JamBuddy as both jam companion and open-source learning platform, collaborating through files (shared ledger + repo), conducted by one scheduled loop. - .claude/agents/{maestro,professor,luthier,muse,critic,herald}.md - dispatchable subagents, one per domain with file ownership + DoD - .claude/skills/jam-loop/SKILL.md - the conductor (main loop appoints workers, Critic gates, Maestro reconciles); generalises /kb-expand - docs/agents/ROSTER.md - team, ownership map, cadence weights - docs/agents/PROTOCOL.md - task-locking conflict guardrail, ledger lifecycle, appointment algorithm, scheduling, PR-via-API - docs/agents/LEDGER.md - live board seeded with sprint-jam-guide - GOAL.md - links the ensemble; build still green Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-06-14 13:57:09 +01:00
parent e180f85289
commit 3c3e30de75
11 changed files with 458 additions and 0 deletions
@@ -0,0 +1,43 @@
+# Ensemble Ledger — Live Task Board
+
+The shared queue all agents read and write. Lifecycle and rules: [`PROTOCOL.md`](PROTOCOL.md). Roster + cadence weights: [`ROSTER.md`](ROSTER.md).
+
+**Status:** `backlog` → `ready` → `claimed` → `in-review` → `done` / `returned`
+**Lock:** a task's `files` column is its lock — no two `claimed`/`in-review` tasks may overlap files.
+
+---
+
+## Active sprint: `sprint-jam-guide` (branch: not yet cut)
+
+Emphasis this sprint: **ship the Jam Guide MVP** (put the 8 guitar style packs on screen, synced to live detection) + **reframe the repo as a learning platform**. Weights this sprint: Luthier 3, Muse 3 (design-heavy), Professor 2, Herald 2, Critic gate.
+
+| id | title | domain | status | depends-on | files (lock) | definition of done |
+|----|-------|--------|--------|-----------|--------------|--------------------|
+| M-01 | Cut `sprint-jam-guide` branch; seed sprint | maestro | ready | — | (branch) | branch off main, ledger header set |
+| L-01 | Shared util: extract `findLoopPosition` + degree-relative loop matcher (rotation-invariant) from `ProgressionBanner.jsx` into `src/lib/match.js` | engineering | backlog | M-01 | `src/lib/match.js`, `src/components/ProgressionBanner.jsx` | matcher maps detected loop → style progression id, rotation-invariant; existing banner still works; build green |
+| L-02 | `JamGuide.jsx` panel shell: mounts last in `App.jsx`, reads `kb/index.js`, instrument+style tabs from registry, collapsed header → ~70vh | engineering | backlog | L-01 | `src/components/JamGuide.jsx`, `src/App.jsx` | panel renders, tabs generate from KB, matches current loop or shows fallback; build green |
+| D-01 | `ChordDiagram.jsx`: 6-string × 5-fret SVG, consumes the KB shape format (movable `rootStr`+`offsets`, open `frets`+`onlyRoot`), key-aware fret placement | design | backlog | L-01 | `src/components/ChordDiagram.jsx` | renders any KB guitar shape correctly in any key; uses design tokens; chord-tone colour tier |
+| D-02 | Jam Guide layout: CSS-grid (cols = progression chords, rows = plays), "more ways ▾" collapse, narrow-viewport reflow, active-chord highlight | design | backlog | L-02, D-01 | `src/components/JamGuide.jsx` (styling), `tailwind.config.js` | fits target viewport; active chord highlights in time; AA contrast; keyboard-reachable |
+| P-01 | Gospel guitar KB cell | content | ready | — | `src/data/kb/gospel/**`, `src/data/kb/index.js` | 5 progressions × 2 plays, validator green (run `/kb-expand`) |
+| P-02 | Pop guitar KB cell | content | backlog | P-01 | `src/data/kb/pop/**`, `src/data/kb/index.js` | 5 progressions × 2 plays, validator green |
+| H-01 | README reframe: lead with the learning-platform vision (detect → guide → learn), screenshot/gif placeholder, link `GOAL.md` + `docs/agents/` | community | ready | — | `README.md` | README states the dual vision; links resolve |
+| H-02 | `CONTRIBUTING.md` + issue templates: the data-contract path so a musician can PR a style without coding (point at `src/data/kb/SCHEMA.md`) | community | backlog | H-01 | `CONTRIBUTING.md`, `.github/ISSUE_TEMPLATE/**` | a non-coder can follow "add a style"; `/kb-expand` documented as the assisted path |
+| C-01 | Smoke-test harness: a `scripts/smoke.mjs` that imports `kb/index.js` + runs the matcher on sample loops, wired alongside `validate-kb.mjs` | quality | backlog | L-01 | `scripts/smoke.mjs` | catches a broken matcher/registry before merge; documented in PROTOCOL gate |
+
+> Critic (C-) reviews every L-/D-/P-/H- task as it reaches `in-review` — those reviews are the gate, not separate ledger rows, except where new test infra is itself the deliverable (e.g. C-01).
+
+---
+
+## Backlog (future sprints)
+
+- **Jam Guide phase 2:** `MiniPiano.jsx` + piano recipe resolver (unblocks piano packs); bass pattern renderer.
+- **Content:** piano packs (jazz → gospel → neo-soul first), then bass packs (blues → jazz → funk first) — see `docs/kb-backlog.md`.
+- **Learning features (Professor + Luthier):** drills tab seeded from `docs/learn-curriculum.md`; target-note highlighting; ear-training quiz on own chord history; pocket report from the onset pipeline.
+- **Progression Builder (GOAL G3):** key-relative palette, drag-reorder, Nashville-number toggle, voicing alternatives.
+- **Platform (Herald):** GitHub Pages docs site; "you're playing the Creep progression" engagement hook; contributor leaderboard for styles added.
+
+---
+
+## Iteration log
+
+_(Maestro appends one line per completed iteration: `<date> · <task ids done> · <next>`.)_
@@ -0,0 +1,123 @@
+# Ensemble Protocol — How the Agents Collaborate
+
+The operating system for the [six-agent ensemble](ROSTER.md). Agents are isolated subagents — they share **no memory**, only **files**: the live ledger ([`LEDGER.md`](LEDGER.md)) and the repo. Everything below makes that file-mediated collaboration safe and productive.
+
+---
+
+## 1. The unit of work: a great task
+
+An iteration is only as good as its tasks. Every ledger task MUST be:
+
+1. **Bounded** — one domain, one definition-of-done, completable in one session.
+2. **Owned** — exactly one agent appointed (domain → agent is 1:1).
+3. **Locked** — declares the files it will write; that set is its lock.
+4. **Justified** — content cites sources, code references the task id, design references tokens.
+5. **Gated** — Critic reviews before merge; nothing self-certifies.
+6. **Logged** — on completion: ledger updated, commit made, `GOAL.md` touched if scope shifted.
+
+If a task can't be written this way, it's too big — Maestro splits it.
+
+---
+
+## 2. The ledger lifecycle
+
+Status flow, managed in [`LEDGER.md`](LEDGER.md):
+
+```
+backlog → ready → claimed → in-review → done
+                     │           │
+                     └───────────┴──→ returned (with findings) → ready
+```
+
+- **backlog** — captured, not yet actionable.
+- **ready** — dependencies met; Maestro promoted it.
+- **claimed** — an agent is working it; its files are now **locked**.
+- **in-review** — work done, handed to Critic.
+- **done** — Critic passed it; merged.
+- **returned** — Critic failed it; carries specific findings; goes back to ready.
+
+**The locking rule (prevents file conflicts):** an agent may only claim a `ready` task whose declared files do **not** overlap any `claimed` or `in-review` task. This serialises conflicting work without a central daemon — the check happens at claim time against the ledger.
+
+---
+
+## 3. File ownership map
+
+Primary owner routes the task; co-reviewers must sign off on cross-domain files.
+
+| Path | Primary | Co-review |
+|---|---|---|
+| `src/data/kb/**` (content) | Professor | Critic (validator) |
+| `src/data/kb/SCHEMA.md`, `scripts/validate-kb.mjs` | Critic | Professor, Luthier |
+| `src/components/**`, `src/services/**`, `src/App.jsx`, `electron/**`, build cfg | Luthier | Critic; Muse if visual |
+| `tailwind.config.js`, visual layer, SVG renderers | Muse | Luthier (integration), Critic |
+| `src/lib/theory.js` | **shared** Professor (music) + Luthier (code) | Critic |
+| `docs/learn-curriculum.md`, `docs/progression-repertoire.md`, `docs/kb-*.md` | Professor | Herald (clarity) |
+| `README.md`, `CONTRIBUTING.md`, `LICENSE`, `.github/**` | Herald | Maestro |
+| `GOAL.md`, `docs/agents/LEDGER.md` | Maestro | all read |
+
+**Shared files** (`theory.js`) get strict task-locking: only one task touching them runs at a time, reviewed by Critic **and** the non-owning domain.
+
+---
+
+## 4. The appointment algorithm (each iteration)
+
+This is what `/jam-loop` (Maestro, run by the main loop) executes:
+
+1. **PLAN** — read `LEDGER.md` + `GOAL.md`. Promote `backlog → ready` where deps are met. Pick the next batch by `priority × cadence-weight` ([weights in ROSTER](ROSTER.md)), ensuring file-disjointness for any parallel batch.
+2. **APPOINT** — for each chosen task, dispatch the agent whose domain == `task.domain`.
+3. **DISPATCH** — choose the shape:
+   - **Serial (default, proven):** one task → one agent via the Agent tool. A dependent chain → run in order.
+   - **Sprint (opt-in / "ultracode"):** independent ready tasks → parallel; dependent tasks → pipeline; via the Workflow tool.
+   - **Parallel writes to disjoint files** → give each agent `isolation: "worktree"`.
+4. **GATE** — every completed worker task → **Critic** reviews (runs `npm run build`, `node scripts/validate-kb.mjs`, tests; applies judgment). Pass → `done`; fail → `returned` with findings.
+5. **RECONCILE** — Maestro commits passing work (one commit per task), updates `LEDGER.md` + `GOAL.md`, writes a one-line iteration log.
+6. **CONTINUE** — schedule the next iteration, or at sprint end open the PR (see §6).
+
+**Appointing correctly = the five rules of great iterations** (§1) applied at dispatch: bounded scope to one agent, files locked, sources/refs required, Critic gate wired in, honest status on return.
+
+---
+
+## 5. Scheduling
+
+The clean model: **schedule the conductor, not the band.** One recurring loop runs `/jam-loop`; each fire is one orchestrated iteration that appoints whichever agent the next ready task needs.
+
+- **Session loop** (runs while this terminal is open): `/loop 1h /jam-loop` — good for a focused build sprint you're watching.
+- **Cloud schedule** (durable, survives closing the session): `/schedule` → e.g. "run /jam-loop every weekday at 09:07" — good for steady background progress. Recommended for a standing ensemble.
+
+Per-domain cadence is the **weight**, not a separate cron: content advances most iterations, OSS/docs every ~4th. To shift emphasis for a stretch (e.g. "design week"), Maestro raises Muse's weight in the ledger header — no schedule change.
+
+**Advanced — true parallel cadences (not default).** You *can* run separate loops per agent (`/loop 1h /jam-loop --only professor`, `/loop 3h /jam-loop --only luthier`). Only do this with **worktree isolation mandatory** and **strictly disjoint file ownership per loop**, or they will collide on shared files (`theory.js`, `App.jsx`, the ledger). The single-conductor model avoids this entirely; prefer it unless you have a specific throughput need.
+
+---
+
+## 6. Branching, review, and PRs
+
+- One **sprint branch** off `main` (e.g. `sprint-jam-guide`); each task is a commit (parallel disjoint work uses worktrees off the branch).
+- Critic gates every commit; Maestro opens **one PR per sprint** to `main` summarising all tasks + validator/build status.
+- **Known constraint (this machine):** `gh` CLI is not installed. Open PRs via the GitHub API using stored git credentials:
+  ```bash
+  TOKEN=$(printf 'protocol=https\nhost=github.com\n\n' | git credential fill | sed -n 's/^password=//p')
+  # POST to https://api.github.com/repos/whattheflat/JamBuddy/pulls with {title, head, base, body}
+  ```
+  (Repo was renamed `whattheflat` → `JamBuddy`; origin URL still works for push.)
+
+---
+
+## 7. Conflict resolution
+
+- **File clash at claim time** → can't claim; pick another ready task or wait for the lock to clear.
+- **Cross-domain disagreement** (e.g. Muse wants a layout Luthier says is infeasible) → Maestro decides, records the call in the ledger, and if it's a product question surfaces it to the human instead of guessing.
+- **Critic vs author** → Critic's gate is binding on *correctness/quality*; on *taste/scope*, Maestro arbitrates. Returned work always carries specific, actionable findings — never a bare rejection.
+- **Scope creep** → if a task grows mid-flight, the agent stops, notes it in the ledger, and Maestro re-splits. Silent scope expansion is the cardinal sin.
+
+---
+
+## 8. State lives in files (because agents don't share memory)
+
+Every iteration must leave perfect context for the next, since the next agent starts fresh:
+- the **ledger** carries task status, locks, and findings;
+- the **commit** carries the change and its rationale;
+- **`GOAL.md`** carries shifts in direction;
+- a recalled **memory** file (`project_ensemble`) carries the standing setup.
+
+Write as if the next agent has never seen this conversation — because it hasn't.
@@ -0,0 +1,63 @@
+# The JamBuddy Ensemble — Agent Roster
+
+Six specialised agents build JamBuddy as both a **real-time jam companion** and an **open-source learning platform**. They collaborate through files (a shared ledger + the repo), never through live conversation — exactly like a git-based human team. The conductor (Maestro) appoints; the five workers do; the gate (Critic) approves.
+
+How they run: [`PROTOCOL.md`](PROTOCOL.md). What's queued now: [`LEDGER.md`](LEDGER.md). The product north star: [`../../GOAL.md`](../../GOAL.md).
+
+| Agent | Role | Realised as |
+|---|---|---|
+| 🎼 **Maestro** | Orchestrator / product lead | the `/jam-loop` skill (run by the main loop) + [`.claude/agents/maestro.md`](../../.claude/agents/maestro.md) for solo planning |
+| 🎓 **Professor** | Music & pedagogy | [`.claude/agents/professor.md`](../../.claude/agents/professor.md) |
+| 🔧 **Luthier** | Engineering | [`.claude/agents/luthier.md`](../../.claude/agents/luthier.md) |
+| 🎨 **Muse** | Design & UX | [`.claude/agents/muse.md`](../../.claude/agents/muse.md) |
+| 🔍 **Critic** | Quality & review (the gate) | [`.claude/agents/critic.md`](../../.claude/agents/critic.md) |
+| 📣 **Herald** | Open-source & community | [`.claude/agents/herald.md`](../../.claude/agents/herald.md) |
+
+---
+
+## Domains, ownership, and quality bar
+
+### 🎼 Maestro — orchestrator / product lead
+- **Mandate:** turn `GOAL.md` into bounded, dependency-ordered tasks; appoint the right agent; reconcile and merge; keep the ledger and goal honest. Writes the plan, not the feature code.
+- **Owns (write):** `GOAL.md`, `docs/agents/LEDGER.md`.
+- **Quality bar:** every task is single-domain, single-DoD, fits one session, declares files + deps. No task ships without a Critic pass logged.
+
+### 🎓 Professor — music & pedagogy
+- **Mandate:** the music brain. Research and author knowledgebase cells (the `/kb-expand` work, now a standing role), learning curricula, drills, and ear-training design; guard music-theory correctness.
+- **Owns (write):** `src/data/kb/**` (content), `docs/learn-curriculum.md`, `docs/progression-repertoire.md`; **co-owns** `src/lib/theory.js` (music correctness) with Luthier.
+- **Quality bar:** key-agnostic data only; `node scripts/validate-kb.mjs` green; named sources; pedagogically sequenced (intermediate, not step-one).
+
+### 🔧 Luthier — engineering
+- **Mandate:** build and revise the app — features, the audio pipeline, wiring the KB into the UI (the Jam Guide panel), refactors, performance, Electron.
+- **Owns (write):** `src/components/**`, `src/services/**`, `src/App.jsx`, `electron/**`, build config; **co-owns** `src/lib/theory.js` (code) with Professor.
+- **Quality bar:** `npm run build` green; no regressions to the audio callbacks' stability contract (see `CLAUDE.md`); diff matches the task; reuses design tokens, never raw hex.
+
+### 🎨 Muse — design & UX
+- **Mandate:** make it come to life on screen — visual design, layout, interaction, the "smart fit to screen" for the Jam Guide, SVG renderers' look, accessibility.
+- **Owns (write):** `tailwind.config.js` (design tokens), presentational components and their styling, SVG visual specs (`ChordDiagram`, `MiniPiano`).
+- **Quality bar:** uses `bg-surface`/`bg-panel`/`border-border`/`accent` tokens; responsive + fits the target viewport; WCAG-AA contrast; keyboard-reachable.
+
+### 🔍 Critic — quality & review (the gate)
+- **Mandate:** review every other agent's work before it merges; run the validator, the build, and any tests; apply judgment; return failing work with specific findings. Veto power.
+- **Owns (write):** `scripts/validate-kb.mjs`, test infrastructure, review notes in the ledger. **Never** silently rewrites feature work — returns it.
+- **Quality bar:** mechanical checks must actually be run (evidence, not assertion); findings are specific and actionable.
+
+### 📣 Herald — open-source & community
+- **Mandate:** make this a *platform*, not just an app — README that frames the learning-platform vision, CONTRIBUTING with the data-contract so musicians (not only coders) can PR a style, issue/PR templates, license, changelog, public roadmap.
+- **Owns (write):** `README.md`, `CONTRIBUTING.md`, `LICENSE`, `.github/**`, contributor-facing docs.
+- **Quality bar:** links resolve; instructions are runnable as written; a non-coding musician can follow the "add a style" path.
+
+---
+
+## Cadence weights (how the conductor balances the band)
+
+Per-domain rhythm is expressed as how often Maestro is *eligible* to pick that domain each iteration — not as separate schedules (see [`PROTOCOL.md` §Scheduling](PROTOCOL.md)).
+
+| Agent | Weight | Effect |
+|---|---|---|
+| Professor | 3 | content can advance every iteration |
+| Luthier | 3 | engineering every iteration (tasks are larger, span iterations naturally) |
+| Muse | 2 | when there is UI pending style (event-driven) |
+| Critic | — | mandatory gate stage every iteration, not weighted |
+| Herald | 1 | ~every 4th iteration, or when a contributor-facing change lands |
+| Maestro | — | plans + reconciles every iteration |