Architecture
Rules catalog
The full list of lite-tier rules bassclef loads into every session. One row per rule with the path where bassclef-sync installs it in your repo.
What rules are
Rules are markdown files bassclef auto-loads into every Claude Code
session (via additionalDirectories wiring). You do not invoke them —
they steer the agent's behavior in the background. When a hook blocks
your work, the block message usually cites the rule that governs it.
That is when you would open the rule file to understand what happened.
Why this is a single catalog page
The rule file IS the docs. Rule bodies read cleanly in the terminal
and in your source tree. Rendering each rule as its own page here
would just be a second-hand copy of the file. INSTEAD we list every
lite rule and the path where bassclef-sync installs it in your
repo — open the file with your editor to read the body.
The catalog
| Rule | What it does | Tier | Installed at |
|---|---|---|---|
accessor-library-discipline | State spine consumers (skills, hooks, rules, scripts) MUST go through the typed accessor library lib/state.sh to read or write bassclef state. | lite | .claude/rules/accessor-library-discipline.md |
api-conventions | Universal API design principles — REST conventions, response shapes, status codes, auth, validation. Stack-specific globs + helpers live in per-stack siblings under standards/api-conventions/. | lite | .claude/rules/api-conventions.md |
arc-level-orientation-before-leaf | /sprint and /longrun prep walk the active goal's parent_bet chain UP TO THE ROOT before proposing scope. | lite | .claude/rules/arc-level-orientation-before-leaf.md |
architect-review-discipline | Every architect-review run MUST exercise both methods — static comprehension AND dynamic verification. | lite | .claude/rules/architect-review-discipline.md |
artifact-ingestion | Before producing any substantive generative output (canvas, prototype, spec, proposal, rubric, ADR, variant), the agent MUST read the referenced artifacts and enumerate them in… | lite | .claude/rules/artifact-ingestion.md |
assert-only-after-verify | Plain check: Before I make a claim in this turn, I read the source first and cite it. | lite | .claude/rules/assert-only-after-verify.md |
auto-fix-criteria | /auto-fix is the autonomous fix workflow for non-trivial narrow bugs. | lite | .claude/rules/auto-fix-criteria.md |
bassclef-hook-drift-blocker | The bassclef-sync.sh SessionStart hook emits a 🛑 BLOCKED block when the consumer repo's hook version differs from bassclef's current template version. | lite | .claude/rules/bassclef-hook-drift-blocker.md |
bassclef-models-discovery | This rule tells consumer-repo agents where bassclef's models live. | lite | .claude/rules/bassclef-models-discovery.md |
bassclef-workflow-parity | When modifying any file matching .github/workflows/bassclef-*.yml, grep the other files in the same directory for the pattern you just changed. | lite | .claude/rules/bassclef-workflow-parity.md |
blocked-items | Session-start hook output may contain lines prefixed with BLOCKED:. | lite | .claude/rules/blocked-items.md |
bootstrap-pair-discipline | Every substrate primitive ships with its paired bootstrap discipline. | lite | .claude/rules/bootstrap-pair-discipline.md |
branching | Trunk-based development — branch naming and flow | lite | .claude/rules/branching.md |
cold-adopter-harness-discipline | Substrate changes that touch any adopter-observable surface MUST pass the cold-adopter harness before merge. | lite | .claude/rules/cold-adopter-harness-discipline.md |
commit-conventions | Commit message format — Conventional Commits | lite | .claude/rules/commit-conventions.md |
compounding-axis-fresh-analysis | When /longrun prep proposes scope shapes, each shape's compounding-sequence row comes from fresh analysis. | lite | .claude/rules/compounding-axis-fresh-analysis.md |
compounding-sequence-fresh-analysis | When /longrun prep proposes scope shapes, each shape's compounding-sequence row comes from fresh analysis. | lite | .claude/rules/compounding-sequence-fresh-analysis.md |
context-engineering | The single most leverage-y discipline in bassclef. | lite | .claude/rules/context-engineering.md |
context-management | Context window management — thresholds, compaction strategy, survival kit | lite | .claude/rules/context-management.md |
cost-governance | Cost governance — budget enforcement from substrate.config.md manifest | lite | .claude/rules/cost-governance.md |
defensive-bash | Every bash hook + script in bassclef follows standards/bash-hook-safety.md. | lite | .claude/rules/defensive-bash.md |
deferred-actions | Deferred-actions manifest — capability-routed handoff across session modalities. Sessions write entries when capabilities don't satisfy an action; capable future sessions pick them up. | lite | .claude/rules/deferred-actions.md |
destructive-operations | The destructive-command-guard hook catches known patterns mechanically. | lite | .claude/rules/destructive-operations.md |
diagnosis | Three-step diagnosis before writing any fix | lite | .claude/rules/diagnosis.md |
discipline | Every load-bearing architectural decision MUST be recorded as an ADR (Architecture Decision Record) per Michael Nygard's lifecycle: proposed → accepted → deprecated → superseded. | lite | .claude/rules/adr-discipline.md |
file-rename-discipline | Every file rename in bassclef registers an entry in standards/file-renames.json AND ships a fixture test that asserts the migrate script cures adopters carrying the old name. | lite | .claude/rules/file-rename-discipline.md |
github-issue-flash-tweet | Every GitHub issue body opens with Problem (≤500 chars): + --- + technical detail. | lite | .claude/rules/github-issue-flash-tweet.md |
guardrails | Agent guardrails — behavior boundaries, escalation rules, capability ceilings for autonomous operation | lite | .claude/rules/guardrails.md |
hook-wire-on-author | Every new bassclef hook (a file under .claude/hooks/*.sh) MUST be added to project .claude/settings.json in the same PR that authors it. | lite | .claude/rules/hook-wire-on-author.md |
identifier-leak-prevention | Bassclef commits stay free of operator machine identifiers. | lite | .claude/rules/identifier-leak-prevention.md |
iteration-bet-brief-completeness | When Orchestrator (or any agent) delegates a Construction stack to a subagent (Builder, Designer, Architect), the brief MUST include, verbatim and with file paths, every artifact… | lite | .claude/rules/iteration-bet-brief-completeness.md |
lite-manifest-schema-change-discipline | Every lite-manifest schema change ships a migration-note ledger entry in the same PR. Adopters read the ledger before sync. | lite | .claude/rules/lite-manifest-schema-change-discipline.md |
longrun-prep-plan-doc-compression | When a plan doc at docs/next-session-plan-*.md (modified within 48 hours) carries a ## Recommended session sequence (or equivalent) section, /longrun prep MUST skip the full Steps… | lite | .claude/rules/longrun-prep-plan-doc-compression.md |
loop-discipline | Every step that ships code or substrate runs the six-step cycle for shipping code or substrate. | lite | .claude/rules/loop-discipline.md |
manual-prod-approval | Prod deploys require GitHub Environments with required_reviewers — no exceptions | lite | .claude/rules/manual-prod-approval.md |
marker-enrichment-discipline | Gate marker files (under state/markers/temperance/, state/markers/luminary/, state/markers/arc-walk/, state/markers/orientation-gate/, state/markers/roadmap-reconcile-gate/) MUST… | lite | .claude/rules/marker-enrichment-discipline.md |
mechanism-fidelity | Every rule that names a mechanical enforcement makes a contract: the mechanism exists, is wired, resolves paths under both install classes, has a Tier 0 test pinning behavior. | lite | .claude/rules/mechanism-fidelity.md |
mobile-ephemeral-session | Mobile/ephemeral session rules — state round-trips through git, no filesystem-only markers, explicit session-end | lite | .claude/rules/mobile-ephemeral-session.md |
new-dependency-check | New dependency check — verify before adding any package; loads per-pkg-manager sibling | lite | .claude/rules/new-dependency-check.md |
oo-ad-entry-point | OOA/D entry point — /decompose must fire for all Construction work, not just canvas-driven flow. Extended per bet 24a to cover hook + lib + script code paths per Cockburn ceremony tiering matrix. | lite | .claude/rules/oo-ad-entry-point.md |
operator-facing-prose | Any shorthand in operator-facing prose carries a plain-language gloss at first mention per response. | lite | .claude/rules/operator-facing-prose.md |
option-label-discipline | When presenting choices for the operator to pick from (shape A vs shape B; option 1 vs option 2; pick a/b/c; tier 1/2/3), labels MUST be characters the operator can easily type… | lite | .claude/rules/option-label-discipline.md |
pattern-annotation | Code that instantiates a named pattern from bassclef's catalog (patterns/<shelf>/<source>/<slug>.md) MUST mark itself with an @pattern <catalog-path> annotation. | lite | .claude/rules/pattern-annotation.md |
persona-name-leak-scrub | Adopter-observable body content across SKILLs plus rules plus luminaries plus docs does not carry bassclef persona names (Sam, Louis, Jamie, Morgan). Persona names are internal orientation words. Adopters have zero context on them. | lite | .claude/rules/persona-name-leak-scrub.md |
plain-english-discipline | All bassclef writing should be plain English at grade 8 with grade 10 as the ceiling for simple technical sentences. Drop bassclef-internal jargon. Keep standard tech vocabulary like API, hook, PR, schema. | lite | .claude/rules/plain-english-discipline.md |
plan-enumeration-needs-value-props | When the agent presents options the operator must pick from or evaluate, the whole proposal opens with a full pitch (claim + 3 reasons) and each option lands as a tweet (claim +… | lite | .claude/rules/plan-enumeration-needs-value-props.md |
pr-body-shape | Every PR body opens with a ## Problem section drafted by /state-a-problem brief + --- + ## Goal. | lite | .claude/rules/pr-body-shape.md |
pr-strategy | The default PR strategy for any multi-issue iteration is stacked atomic branches: one branch per issue, one PR per branch, each independently reviewable and revertable. | lite | .claude/rules/pr-strategy.md |
pr-title-shape | Sister rule to pr-body-shape.md. Encodes authoring-time discipline for the PR title surface. Titles show in gh pr list, GitHub search, and mobile views — they are the… | lite | .claude/rules/pr-title-shape.md |
prototype-production-coupling | Design prototypes are load-bearing artifacts, not sketches. | lite | .claude/rules/prototype-production-coupling.md |
prototype-workflow | Design prototypes (artifacts under docs/prototypes/**) are visual statements to Reviewer (\"this is what we want built\"). | lite | .claude/rules/prototype-workflow.md |
quick-fix-criteria | /quick-fix is the compressed fix workflow for trivial bugs. | lite | .claude/rules/quick-fix-criteria.md |
reserved-skill-names | Bassclef MUST NOT create a skill (.claude/skills/<name>/SKILL.md) with a name Claude Code's harness already claims. | lite | .claude/rules/reserved-skill-names.md |
schema-management | Schema management — never apply schema changes without a migration; loads per-ORM sibling | lite | .claude/rules/schema-management.md |
sdlc-gates | Universal SDLC gates — pre-build temperance + diagnose, post-build /verify, observed-failure chain. Stack-specific globs live in per-language siblings under standards/sdlc-gates/. | lite | .claude/rules/sdlc-gates.md |
security | Security scanning — loads when touching source, config, or infra files | lite | .claude/rules/security.md |
session-artifacts | Session artifacts — chronicle + journal entries at every phase transition and session end | lite | .claude/rules/session-artifacts.md |
sibling-smoke-after-substrate-change | When a PR touches an adopter-observable substrate path (.claude/hooks/.sh, .claude/rules/.md, .claude/skills//SKILL.md, .claude/agents/.md, lib/.sh, or… | lite | .claude/rules/sibling-smoke-after-substrate-change.md |
skill-composition-declarations | How and when skills declare composes_with (extends another skill) vs depends_on (needs a runtime predecessor) in frontmatter. Closes bassclef#862 Gap 3. | lite | .claude/rules/skill-composition-declarations.md |
skill-description-clarity | Every skill's frontmatter description field must be parseable by an engineer with no bassclef context in under 60 seconds. | lite | .claude/rules/skill-description-clarity.md |
skill-procedure-step-list | Before executing any SKILL procedure, I write the numbered step list into the response. | lite | .claude/rules/skill-procedure-step-list.md |
sprint-prep-preset-picker | /sprint next-work proposals pick one of three presets (converged / exploratory / reversible-small) based on mode signals. Sister rule to longrun-prep-plan-doc-compression at /sprint surface. | lite | .claude/rules/sprint-prep-preset-picker.md |
state-schema-validation | State-spine entity writes MUST conform to their JSON Schema. | lite | .claude/rules/state-schema-validation.md |
stuck-signal-diagnostic | When a hook emits the same BLOCKED signal across ≥3 consecutive sessions and the underlying state counter hasn't moved, the signal is stuck. | lite | .claude/rules/stuck-signal-diagnostic.md |
substrate-as-system | Per ADR-035: bassclef's substrate is a system, not a bag of files. | lite | .claude/rules/substrate-as-system.md |
substrate-config-schema | Substrate config + secrets schemas — single source of truth for external resource references and secret lifecycle | lite | .claude/rules/substrate-config-schema.md |
test-list-discipline | Every test file opens with a # test-list: commented block enumerating the assertions the step owes. | lite | .claude/rules/test-list-discipline.md |
test-sufficiency | The Tier 0 hook (bassclef#1037) enforces test PRESENCE + RECENCY. | lite | .claude/rules/test-sufficiency.md |
testing | Three-layer test strategy — loads when touching source or test files | lite | .claude/rules/testing.md |
testing-tier-config | Bassclef's testing discipline is configured per path-matcher in .claude/bassclef-configs.jsonc under the testing section. | lite | .claude/rules/testing-tier-config.md |
turn-estimate-grounding | Plain check: Before I ship a turn estimate to an adopter, I cite a past bet's actuals + write a range + name the shape. | lite | .claude/rules/turn-estimate-grounding.md |
usability | Usability check — loads only when touching UI files | lite | .claude/rules/usability.md |
visual-hierarchy | Long agent responses that mix summary + analysis + enumeration + action become walls of text. | lite | .claude/rules/visual-hierarchy.md |
we-dont-break-adopters | Bassclef adopts Linus Torvalds's rule: we do not break adopters. | lite | .claude/rules/we-dont-break-adopters.md |
whereami-load-bearing | docs/whereami.md is the authoritative project-state snapshot in every bassclef-substrate repo. | lite | .claude/rules/whereami-load-bearing.md |
writing-craft-discipline | Plain check. Before I ship any operator-facing prose in this turn, I run the six Ogilvy tests against my draft. If any test fails, I rewrite before I ship. | lite | .claude/rules/writing-craft-discipline.md |
wu-sequencing-compounds | WUs within a chosen goal shape ship as compounding builds. | lite | .claude/rules/wu-sequencing-compounds.md |
Related
- Skills catalog — commands you type
- Hooks catalog — bash scripts that fire on Claude Code events
- Failure mode — how bassclef fails safely when a rule blocks