The standard for codebases that govern themselves at CI time.
Wiki pages don't enforce design principles — gates do. software/constitution™ is a language-agnostic, Apache-2.0 specification for codebases that encode their own rules as machine-enforceable artefacts, and prove it on every CI run. Read the spec. Run SCCT. Ship the verdict.
In the agentic era, software-writing becomes a commodity. What survives is the rules the codebase enforces on its own agents. Read the principles →
An open standard, not a framework or a tool.
A software constitution is the set of design principles your codebase enforces at CI time — versioned, machine-readable, blocking on violation. software/constitution™ is the Apache-2.0 specification that defines what such a thing requires and how to test for it. Closest analogues: 12-Factor App (heroku, 2011), OpenAPI, ADRs. We borrow from all three.
The specification
12 sections defining six required rule classes, five conformance levels, the canonical artefact contract, and the SCCT verdict format.
Copy-paste starting points
Master constitution index, deviations log, decay windows, implementation registry — JSON-Schema validated.
Drop-in CI implementations
Reference drift-gates that any project can wire into its CI. Node.js and Python shipping today; Go and Rust ports planned.
The conformance test
npx scct <repo> emits a JSON verdict at L0 / L1 / L2 / L3 / L4. External, objective, scriptable.
Machine-readable contract
JSON Schema 2020-12 files for every canonical artefact. Your CI validates against them on every push.
Apache-2.0 grant included
The spec, schemas, templates, and reference gates ship with the Apache-2.0 patent grant. Safe to adopt at any company.
Design discipline is a meeting decision; CI is the only thing that remembers.
Design principles live in wiki pages.
ADRs, RFCs, architecture diagrams, onboarding docs. They describe how the system *should* work. None of them block a merge.
Nothing enforces the principle in the diff.
The code that ships breaks the principle that was approved. By the time anyone notices, the violation is six months old and threaded through twelve files. Refactor cost balloons. Discipline erodes.
Every principle becomes a CI gate. Every merge is an attestation.
The standard defines what a "principle" is in machine terms, what a "gate" is, and what counts as conformance. Wire the gates, ship the verdict, your codebase governs itself by construction.
Every conformant constitution addresses all six.
Naming and numbering is project-specific. The conformance bar is: at least one passing gate per class, on every push. Canonical definitions live in SPEC.md §4.
Zero Competing Systems
Every named capability has exactly one canonical implementation. Drift gate blocks a second implementation of an existing capability.
Zero Repo ↔ Prod Drift
What's declared in the repo is what's running. A reconciler proves the bijection; CI fails if production diverges from main.
Zero Stubs / Mocks in Prod
No TODO, FIXME, placeholder content, or mock data reachable from production. The gate scans every shipping path.
Self-Governance + Canonical-First
Every privileged action emits the project's own audit chain. Vocabulary is declared canonically before it's referenced.
Zero-Deviation Mandate
Active deviations are a regression. Time-boxed exceptions allowed; the empty-Active-deviations state is the steady state.
Coherent Integration / No Orphans
Every named component is bidirectionally referenced — registry → component AND component → registry. Orphans on either side are violations.
Five levels. SCCT decides which one your repo is at.
External, objective, scriptable. Procurement teams can require L3 in their RFPs and have a test for it. OSS maintainers can publish their level as a badge.
None
No constitution found.
Structural
Canonical artefacts exist; schemas validate.
Gated
Every rule has a passing CI gate.
Self-governed
Project emits its own audit chain.
Platform-bijected
Every named surface is in a generated meta-index — declared = deployed.
Run it: npx scct /path/to/your/repo. Output is a single JSON verdict procurement teams can ingest.
Five steps. Hours, not weeks.
# 1. Copy the templates into your repo cp -r software-constitution/templates/* your-repo/constitution/ # 2. Author your rules (one document per rail, numbered) $EDITOR your-repo/constitution/00-INDEX.md $EDITOR your-repo/constitution/01-YOUR-FIRST-RAIL.md # 3. Declare your implementation registry $EDITOR your-repo/private/specs/implementation/registry.json # 4. Wire the reference gates into CI cp software-constitution/gates/*.mjs your-repo/scripts/gates/ # 5. Run the conformance test npx scct your-repo
Full walkthrough on GitHub. The reference gates ship in Node.js + Python; Go and Rust ports are in progress.
Production codebases governing themselves with the standard.
The standard's credibility is the codebases that ship it. Adopters publish their conformance verdict (L0–L4) and link to the public evidence. See the full directory on /adopters/.
Runtime authority + evidence protocol. Conforms at L4 — every named surface bijected in a generated meta-index; every privileged action emits its canonical audit chain. kyeprotocol.com →
If your repo conforms, list it here. Open a PR with your repo, verdict JSON, and a one-line description.
One standard, implementations free to multiply.
The spec is the root. Anyone can ship a conformant implementation — open-source, commercial, internal. We ship the spec; the ecosystem ships the products.
The standard. Apache 2.0. Six rule classes · five levels · SCCT verdict. Read the spec, conform on your own CI, run the test.
One conformant product. A GitHub App that runs the rule classes inline on every PR + emits a cryptographic evidence pack. codeconstitution.com →
Common questions.
What is a software constitution?
The set of design principles your codebase enforces at CI time — versioned, machine-readable, blocking on violation. Wiki pages don't count; gates do.
What is the Software Constitution Standard?
An Apache-2.0 open specification that defines six rule classes every conformant project addresses, five conformance levels (L0–L4), and the SCCT CLI that emits an objective verdict.
Who is it for?
Engineering leaders encoding principles as code; regulated buyers (banks, healthcare) requiring auditable evidence; OSS maintainers wanting forks to inherit governance; procurement teams scoring vendor engineering maturity.
Is it tied to one language or platform?
No. The specification is language-, provider-, and domain-agnostic. The conformance bar is the existence of a passing gate, not the language it runs in.
Is this safe for closed-source companies?
Yes. Apache-2.0 means adoption requires no relicensing of your code. The spec, schemas, templates, and reference gates carry an explicit patent grant. Your repo and your IP stay yours.
How does this relate to OpenAPI / 12-Factor / ADRs?
OpenAPI standardises the wire contract; 12-Factor standardises operational shape; ADRs document decisions. software/constitution™ standardises the rules you commit to and the CI gates that enforce them.
Is this a product or a standard?
A standard. The spec, schemas, reference gates, and SCCT are Apache 2.0. Products that implement the standard exist separately — for example, code/constitution™ is a conformant GitHub App. The standard does not require any specific product.