Directory layout
Every substrate-managed directory in your repo, what populates it, and what lives inside.
Use this when
You are trying to figure out where a bassclef artifact lives — where the last chronicle ended up, where a new ADR goes, where the state markers you keep hearing about actually sit on disk. This page names each directory and what fills it.
Skip this when
You are looking for one specific config file's schema. See Config for the per-file pages.
The layout
bassclef writes to a small number of directories in your repo. Everything is a file; every file is browsable; every artifact belongs to a specific concern.
Substrate directories (.claude/)
The Claude Code harness reads from .claude/ on every session. bassclef
copies its shipped substrate into these subdirectories when you run
npm install bassclef or bassclef sync.
| Directory | Populated by | Asset type | Example |
|---|---|---|---|
.claude/hooks/ | bassclef sync + adopter opt-in | Shell scripts firing at Claude Code lifecycle events | bassclef-sync.sh, pre-commit-gate.sh |
.claude/skills/ | bassclef sync + adopter authoring | Named slash commands with SKILL.md frontmatter | /riff, /launch, /build, /kiss |
.claude/rules/ | bassclef sync + adopter authoring | Markdown rules auto-loaded via additionalDirectories | plain-english-discipline.md, pr-body-shape.md |
.claude/luminaries/ | bassclef sync | Practitioner profile markdown (Norman, Beck, Cockburn, ...) | don-norman.md, kent-beck.md |
.claude/agents/ | bassclef sync + adopter opt-in | Agent role definitions (Builder, Reviewer, ...) | Builder.md, Reviewer.md |
.claude/settings.json | Claude Code harness + bassclef sync | Hook wiring + additionalDirectories + permissions | See /docs/config/settings |
.claude/bassclef-configs.jsonc | Adopter authoring | Adopter-facing config (plan tier, testing tiers, model routing) | See /docs/config/bassclef-configs |
Session artifacts (chronicle/ + docs/chronicles/)
Session-end paragraphs pinned to state. Read at session-start to restore context.
| Directory | Populated by | Asset type | Example |
|---|---|---|---|
chronicle/ | /session-end skill | Session log markdown (bassclef itself) | 2026-08-25-docs-polish-trio-option-a.md |
docs/chronicles/ | /session-end skill | Session log markdown (adopter repos) | 2026-08-25-*.md |
Only one of these applies to your repo — bassclef writes to chronicle/
at root; adopter repos write to docs/chronicles/.
Product artifacts (docs/)
Where bassclef writes the reusable products of a session — the canvas you shaped, the goal doc you committed to, the audit you ran.
| Directory | Populated by | Asset type | Example |
|---|---|---|---|
docs/canvases/ | /canvas, /lean-canvas, /value-prop-canvas | Product strategy canvases | 2026-07-29-npm-distribution-phase-1.md |
docs/iteration-bets/ | /longrun prep, /canvas (goal docs — also called bets) | Scope contracts for a session | 2026-07-29-npm-phase-1-buildout-spine.md |
docs/decompositions/ | /decompose | GRASP + pattern decomposition | 2026-07-01-d83e23-grasp.md |
docs/specs/ | /spec, /launch | Buildable spec docs | 2026-07-01-d83e23.md |
docs/personas/ | /personas, /empathy-map | One file per persona your product serves | engineer.md, operator.md |
docs/user-stories/ | /user-stories | INVEST-shaped stories | Story batches by feature |
docs/use-cases/ | /use-case | Cockburn use cases | Per-feature use case files |
docs/jtbd/ | /jtbd-tasks | Jobs-to-be-done + task analysis | Per-persona JTBD files |
docs/ia-models/ | /ia-model | Information architecture models | Per-surface IA models |
docs/interaction-designs/ | /interaction-design | State diagrams + sequence diagrams | Per-flow interaction docs |
docs/audits/ | Ad-hoc audits (/architect-review, this ticket) | Audit doc markdown | 2026-08-25-landing-docs-consistency.md |
docs/deferred-actions/ | /session-end (rescue), skill deferrals | Handoff notes to next session | <timestamp>-session-rescue.md |
docs/retros/ | /retro | Session retrospectives | Per-session retro files |
docs/whereami.md | /session-end, /whereami | The current project-state snapshot | Single file (schema-validated) |
docs/session-friction-log.md | post-skill-friction-check.sh hook | Friction findings from long sessions | Single append-only log |
Architecture (architecture/)
Design decisions and discoveries that outlive any one session.
| Directory | Populated by | Asset type | Example |
|---|---|---|---|
architecture/decisions/ | /architect-review, manual ADRs | Architecture decision records (ADRs) | ADR-001-docs-framework.md, ADR-002-docs-theming-strategy.md |
architecture/audits/ | /architect-review | Deep architecture audits | 2026-06-27-mechanism-fidelity.md |
design/discoveries/ | Ad-hoc discovery writeups | Earned-wisdom docs | 2026-07-26-cf-token-outage-narrative-flip.md |
State (state/)
Machine-readable state that bassclef reads and writes for gate enforcement. Adopters rarely edit these by hand; the hooks do.
| Directory | Populated by | Asset type | Example |
|---|---|---|---|
state/markers/temperance/ | pre-commit-gate.sh hook + /temperance | Per-branch scope-decision markers | <branch-slug>.marker |
state/markers/luminary/ | pre-commit-gate.sh hook + /luminary | Per-branch design-lens markers | <branch-slug>.marker |
state/markers/pre-mortem/ | pre-commit-gate.sh hook + /pre-mortem | Per-branch risk-ledger markers | <branch-slug>.marker |
state/markers/lead-lens-signoff/ | pre-commit-gate.sh hook | Per-branch lead-luminary sign-off | <branch-slug>.marker |
state/markers/adr-deviation/ | adr-deviation-challenge.sh hook | Per-branch ADR-consult markers | <branch-slug>.marker |
state/markers/orientation-gate/ | session-reflection.d/ hooks | Per-branch orientation gate | <branch-slug>.marker |
state/markers/verify/ | /verify skill + pre-commit-gate.sh | Per-branch verify markers | <branch-slug>.marker |
Standards + references
Where bassclef ships the reference material rules cite.
| Directory | Populated by | Asset type | Example |
|---|---|---|---|
standards/ | bassclef sync | Reference standards markdown | bassclef-internal-jargon.md, pr-body-discipline.md |
substrate.config.md | Adopter authoring | External resource references (doc IDs, URLs, env-var names) | Single file per adopter |
What is NOT in this list
- Your app source (
src/,app/,lib/) — bassclef does not populate these; you do. - Vendor directories (
node_modules/,.next/) — dependencies and build output. - Git internals (
.git/) — the version control system. - Adopter-private (
docs/operator-private/,operator-private/) — gitignored operator content. Never ships publicly.
Where to look next
- bassclef-configs.jsonc — adopter behavior config
- settings.json — Claude Code harness config
- Substrate config (
.bassclef-source.json) — sync config - Session log (chronicle) — the session-end artifact
- Whereami — the project-state snapshot