89 lines
6.1 KiB
Markdown
89 lines
6.1 KiB
Markdown
|
# 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)
|