# standards and conventions _Status: direction (Option B decided) — as of 2026-07-17_ _Connects to: [deterministic-gates](deterministic-gates.md), [agent-design-principles](agent-design-principles.md), [never-ask-twice](never-ask-twice.md), [self-improvement-loops](self-improvement-loops.md), [overview](../OVERVIEW.md)_ ## Purpose Defines once, and reuses everywhere, the coding standards and conventions the factory applies across many languages and frameworks (e.g. Sandi Metz 99-Bottles OOP for all OOP languages) — so a standard is authored a single time, not redefined per project. Load this before designing project onboarding, the green command, or any standard-carrying context packet for a pipeline agent. ## Design - **Three layers, separated on purpose:** 1. **The opinion** — language-agnostic prose (the Metz rules themselves). Written once. 2. **Per-language bindings** — executable configs (`.rubocop.yml`, eslint fragment, `ruff.toml`) each tagged with the standard + version it implements. One opinion, N bindings: this is where cross-language overlap resolves. 3. **Per-project adoption** — a project copies the right bindings, wires the green command, and records a repo ADR ("adopts `sandi-metz-oop` v2 for Ruby") linking the vault opinion. - **Layout — Option B (DECIDED).** Opinion lives in the vault as a `convention/` note (the cross-project source of truth, per [never-ask-twice](never-ask-twice.md)); executable bindings ship in the plugin because they are deployable, git-versioned/diffable artifacts and the vault is a knowledge graph, not an artifact store. Precedent: `plugins/cc-architect/references/conventions/cc-os-naming.md` (canonical repo copy; vault note defers to it). ``` ~/Documents/SecondBrain/convention/sandi-metz-oop.md # opinion; links to bindings plugins/os-sdlc/standards/sandi-metz-oop/ standard.md # canonical prose (vault note defers here) ruby/rubocop.yml javascript/eslintrc.json python/ruff.toml ``` - **The residue rule: anything lint-enforceable is in nobody's prompt.** An agent is never told the arity/length/naming limit — the green command's linter tells it, only on violation, injected into its own next turn (mechanism: [deterministic-gates](deterministic-gates.md)). Standing context cost of enforceable rules is therefore zero. Only the *judgment residue* a linter cannot check (abstraction choice, "composition over inheritance", pattern selection) is ever routed into a prompt — and only into the reviewer's ([pipeline-stages](pipeline-stages.md)). - **Routing key: standard × language × audience × facet.** Each standard's prose is sectioned by facet (interface / implementation / test) and audience-tagged, so the context packet is a mechanical section-filter, not a per-session judgment call: - **programmer** — gets *nothing* standing; learns quality rules only as gate feedback. - **test-writer** — is the interface designer in a red-first pipeline, so it gets test conventions **plus the interface facet** (naming, public message shape, arity-as-interface) — but not implementation-facing rules (method length, private structure, duplication). - **reviewer** — gets the judgment-facet residue; it is the designated judgment actor. - **How far linting reaches (Ruby, the deep case):** `rubocop` (metrics/style/naming, custom cops for house rules), **`reek`** (semantic smells — feature envy, data clumps, control coupling; much of "Metz taste" is reek findings), `flay`/`flog` (structural duplication / complexity), **`mutant`** (mutation testing — deterministically proves the tests *constrain* behavior, keeping the test-writer honest and mechanically answering the "gaming the green-assert gate" concern in [pipeline-stages](pipeline-stages.md)). JS (eslint+plugins) / Python (ruff) are shallower but workable. Ceiling: tools detect **symptoms, not choices** — they police the boundaries of good code; the reviewer polices the choices within them. - **Pre-seeding, not just mining.** The Mobbin move from [never-ask-twice](never-ask-twice.md) generalizes: our own standards are self-sourced pre-seeds — writing `convention/sandi-metz-oop` up front lets the "OOP approach" decision category start at `afk-ready` instead of being re-asked per project. This is the concrete cure for "defined Metz a dozen times." - **Sequencing (hard constraint):** all of this is **post-tracer-bullet**. v1 nails the flow with disposable code and trivial prompts; standards/gate-tuning land afterward, alongside [self-improvement-loops](self-improvement-loops.md). Do not add quality gates before the happy path is trusted. ## Open questions - **Adoption/update ownership.** First-time adoption (copy bindings, wire green command) is naturally an os-sdlc onboarding skill. Drift-checking (a project on an outdated standard version) *might* extend os-status — but os-status:fix is scoped to "the cc-os approach," whereas this layer targets arbitrary client projects in many languages. Ownership unsettled. - **Gate strictness is a tuning parameter, not an ideology.** A maximal cop wall can thrash a cheap model (fix one violation → trigger another) and burn the iteration budget. Tune strictness against iteration counts via autoresearch, same as prompt text — baseline at *zero* standards first (audit defaults before customizing) and admit each rule only if it beats that baseline. - **Auditing existing projects is deferred.** One cheap harvest now: seed the canonical Metz standard + first Ruby binding from the *best* of the dozen existing definitions. The other projects reconcile later via the version-check path, one at a time (like ADR rollout). - Bindings for non-OOP standards (functional, framework-conformance) — schema unproven. ## Sources - SecondBrain vault: `convention/` facet, `matt-pocock-skills-v1-1-changes.md` - `plugins/cc-architect/references/conventions/cc-os-naming.md` (Option B precedent) - Ruby toolchain: rubocop, reek, flay, flog, mutant - ADR-0037; [never-ask-twice](never-ask-twice.md) (vault-as-source-of-truth split) - 2026-07-17 design session (this doc's origin)