Architecture

How it fits

Claude Code fires the events. Bassclef answers with six building blocks — all files in your repo. Chronicles feed the next session, so the next session starts loaded with what the last one shipped.

Where bassclef fits

"I already have Claude Code. What is bassclef adding?"

Claude Code is the agent harness. It runs the model, handles tool calls, and executes your session. Bassclef is a development substrate installed around Claude Code and your repo. It brings product and engineering disciplines, durable project state, composed workflows, practitioner lenses, and lifecycle hooks. All as files you can read.

Claude Code can plan, review, and hold context inside one session. Bassclef makes those disciplines explicit, persistent, inspectable, and reusable across sessions. The distinction is not what Claude Code can do. It is what stays around after the session ends, and what the next session inherits without you re-explaining.

Adjacent methodologies for coding agents (Superpowers, GitHub Spec Kit) sit in the same layer as bassclef — opinionated development practice packaged for coding agents to consume. They are closer comparisons to bassclef than Claude Code itself. Each has its own shape. Bassclef's shape follows a specific flow — see below.

How bassclef turns intent into work

The diagram above shows what bassclef IS. This flow shows what bassclef DOES:

INTENT (your paragraph)
  ↓
UNDERSTANDING  (lite: /interpret-input + /pick-luminaries in-session ·
                ultra: /extract-intent with Voyage embeddings + Haiku judge)
  ↓
DISCIPLINES    (relevant skills + rules + luminary lenses matched to intent)
  ↓
COMPOSITION    (composer skills like /launch, /longrun orchestrate
                atomic skills like /verify, /sprint)
  ↓
EXECUTION      (Claude Code runs the model with the composed context)
  ↓
STATE          (chronicles + whereami + state spine persist
                what shipped, what's blocked, what's next)
  ↓
LEARNING       (you promote reusable patterns via /promote into
                rules + skills the next session inherits)

The flow is not a strict runtime chain. Bassclef is files Claude Code reads. Hooks fire on Claude Code lifecycle events. Skills dispatch when you type a slash-command. State persists between sessions as JSON and markdown in your git repo. Claude Code runs the model with all of that composed into its context.

Composed workflows

Some skills are atomic. /verify runs a checklist. /sprint reads state. /luminary opens a lens file. Others compose atomic skills into a workflow. /launch runs /interpret-input, /pick-luminaries, /spec, /decompose, and more. /longrun paces a multi-hour session with checkpoints at phase boundaries.

You see a narrow interface. The substrate runs the chain underneath. That is why bassclef is not a flat catalog of slash-commands. Composer skills carry the discipline — extract intent, pick lenses, audit writing, verify — so you do not have to type each step.

The pieces

Three layers make up bassclef.

Substrate primitives

The six building blocks in the diagram above. All live as files in .claude/.

• Skills (.claude/skills/) — named slash-commands you dispatch.
• Rules (.claude/rules/) — project conventions auto-loaded every session.
• Hooks (.claude/hooks/) — lifecycle gates that fire at Claude Code events.
• Luminaries (.claude/luminaries/) — practitioner profiles you consult on demand.
• State spine (state/) — typed persistent JSON with markers.
• Chronicles (chronicle/) — session paragraphs written at every Stop.

Durable development artifacts

The record of decisions and discoveries the substrate produces over time. These live in docs/.

• ADRs — architecture decisions with Context, Decision, Consequences, Rejected alternatives, Exit cost.
• Discoveries — weekly write-ups of what bassclef ran into and what it taught.
• Failure-mode playbook — six named failure classes with runnable diagnose commands.
• Goals, personas, specs, plans, user stories, standards — the everyday artifacts each phase produces, referenced by the skills that write them.

Composed workflows

The skills that orchestrate other skills into a full workflow.

• /riff — sketches 2-3 clickable mocks from a paragraph.
• /launch — turns a mock into a buildable plan (spec + user stories + decomposition).
• /build — implements the plan and opens a pull request.
• /longrun — paces a multi-hour session with checkpoints at phase boundaries.

Supporting mechanisms

• State spine — deep-dive on the authoritative state layer, JSON-on-git with typed accessors.
• Accessor library — lib/state.sh, the API every substrate consumer uses to read and write state safely.
• Whereami primitive — the singleton project-state snapshot, queried via /whereami.
• Chronicle — deep-dive on how session paragraphs get written and read.