Overview

An engineering canon for AI-built software.

racecar is an opinionated engineering canon for AI-built software. It makes architectural rules explicit and checks them locally at file and line level. It distinguishes construction from conformance, keeps the specification independent of its implementation, and reserves ship decisions for the repository owner. The framework provides principles, checks, lenses, skills, and thin surfaces over a shared API.

Principles

The axioms that govern construction and conformance.

The canon distinguishes eight adopted principles (P-01–P-08) and twelve racecar positions (R-01–R-12). Each principle has one home in architecture/PRINCIPLES.md and an argument in its own architecture node. AXIOMS.md is the generated reduced baseline. The declaration tree carries rules, groups, and settings, with language-specific bindings kept separate from framework-neutral positions.

Adopted Axioms

Eight adopted axioms form the inherited foundation of the canon. Their authoritative formulations and arguments live in architecture/PRINCIPLES.md and the corresponding architecture/Pxx-* nodes. AXIOMS.md is a generated reduction, not an independently edited authority. The source bundle identifies this as a closed set; individual wording should be taken from the source tree rather than reconstructed from summaries.

Racecar Positions

Twelve explicit racecar positions extend the adopted canon. Among their governing commitments are deterministic enforcement rather than LLM judgment in the constant loop, repository-owner authority over ship decisions, state placement by persistence contract, surface separation, layering, and deployment discipline. Each argument belongs to its own architecture/Rxx-* node. The committed principles file remains the authoritative wording.

Declaration Tree

The architecture tree is both a human-readable argument and a machine-readable declaration system. Nodes declare their kind in frontmatter against the tree's own ontology. Rules, groups, and settings form a containment structure, with the parent relationship recorded by the tree. A principle belongs here when it remains valid across implementation languages; Python-specific bindings are recorded as bindings, not promoted into universal axioms.

Placemats

Understand the architecture through its governing distinctions.

These reference maps explain the relationships behind the engineering canon. They are editorial navigation aids derived from the source bundle, not additional normative specifications. Use the underlying principles, declaration trees, and check scripts as the authority.

Five Artifact Kinds

Principles define what must hold. Checks are deterministic, standalone scripts that report specific violations. Lenses collect review disciplines and the checks that enforce them. Skills are on-demand agent procedures. Surfaces expose a shared internal API over transports. These categories have different responsibilities and should not be collapsed into one generic idea of a framework or methodology.

Two Axes of Verification

Construction: Is the implementation built correctly? This includes import direction, forbidden cycles, and required structural boundaries. Construction can pass even when the wrong capability was built.

The Three-Layer Boundary

Surfaces translate and render. The API coordinates the operation and is the shared entry point. The library implements the work. Dependencies flow down from surfaces through API to library; peer API submodules are kept independent. A feature vertical can co-locate its library, API, and surface adapters without dissolving these dependency rules.

State & Delivery

State is classified by its persistence contract rather than by a convenient folder name. Some state ships with a release and admits no runtime writer; some changes only through an administrator's deliberate act; some is accumulated by the running system. Packaging, configuration, upgrade, and deployment should honor those distinctions so generated or operational state does not masquerade as committed source.

Knowledge Model

Declare meaning, containment, and relationships independently.

Ontology specifies the kinds and fields a corpus permits. Topology specifies containment and tier shape. A graph consists of actual nodes and edges, with declared sources and readers. These axes are orthogonal: a graph can be structurally valid yet semantically invalid, or the reverse. Conformance compares authored declarations to instances in both directions.

Ontology

An ontology declares which kinds of node exist and what fields or relationships each kind requires. Kinds are explicit data, not guessed from directory depth. Validation can therefore report missing properties, unknown kinds, and disallowed relationships. In racecar the architecture and lexicon trees each declare their own schema, enabling the system to check the corpus against rules authored separately from the instances.

Topology

Topology describes where nodes may occur and which kinds may contain others. It is orthogonal to ontology: the same kinds can be arranged in a permitted or forbidden shape. The lexicon's simple rule permits nouns to contain nouns and verbs, while verbs contain nothing. The architecture tree has its own parent and peer rules. A topology check inspects structure rather than prose.

Graph

The graph is the actual corpus: nodes and edges with identities, properties, and relationships. A graph declaration identifies its node, edge, source, and reader. Readers are named for the mechanism by which they read, not for a single graph they happen to serve. Materialization makes edges, orphans, and coverage inspectable. The manifest is a queryable projection of the authored graph, not a substitute for it.

Declared Graphs

The declared-graph inventory enumerates graphs from docs/graphs/declared/. Each declaration states the node, edge, source, and reader contract. Reader implementations are generic to a mechanism. This avoids embedding a new bespoke parser in every graph declaration and allows the same check machinery to validate distinct corpora. Source completeness and provenance matter: the graph must account for the source it claims to represent.

Lexicon

Give every noun, verb, and parameter one declared home.

docs/lexicon/ is a declared tree, not a glossary pasted beside implementation. Nouns own their nested nouns and verbs; verbs are leaves. Each node declares its kind in frontmatter; parameters are nodes too. The tree carries its own ontology and topology. Command documentation is authored beside the verb it describes, while CLI usage remains generated from the command itself.

Nouns

The nounspace is a directory tree. A noun occupies a path that serves as its address and may contain sub-nouns and verbs. Each node declares kind in frontmatter rather than relying on its filename alone. The authored structure gives commands, documentation, and generated surfaces one shared semantic vocabulary. A missing declaration is a defect even if an implementation happens to work.

Verbs

A verb is an operation node beside the noun that owns it. Verbs do not contain other nodes. Command documentation is authored with the verb, while runtime usage and options remain the CLI's own responsibility. The lexicon checker compares declaration to the implementation and can identify operations missing on either side. The aim is one contract across the authored vocabulary and the executable command tree.

Parameters

Parameters are declared nodes, not an informal list copied between help pages. The lexicon contains a param word tree whose nodes identify themselves with kind: param. Their names and relationships are checked against the operations that accept them. This makes a surface's callable vocabulary auditable while avoiding multiple hand-maintained definitions of the same option.

Surfaces

One internal API, multiple thin ways to invoke it.

A surface translates input, invokes the API, and renders output. It must not invent orchestration policy or duplicate the business operation. racecar itself offers CLI and agent-skill transports, and generates REST and MCP surfaces for adopting repositories rather than hosting those interfaces itself. Surface declarations and implementation are checked for drift.

CLI

The command line is a surface, not the owner of the underlying work. Its verbs are declared and checked against implementation. The CLI contract distinguishes success or nothing to do (exit 0), findings (exit 1), and inability to run (exit 2). Missing required arguments show the relevant verb's help, unknown arguments are named at that verb, and mistyped verbs receive a suggestion.

Agent Skills

Agent skills are an LLM-facing transport over the same internal API as the CLI. They load when invoked and describe how to perform bounded work. A skill should not shell out to the CLI as its own implementation strategy, because that creates unnecessary coupling and risks divergence. Its instructions are useful precisely because the checks and underlying operations have independent authority.

Generated REST & MCP

racecar can generate REST and MCP surfaces for software built with it. It does not itself expose REST or MCP services. Each generated adapter should translate a transport request into a declared API operation and render the result, without adding orchestration policy. Surface conformance checks compare the authored operation and its transport binding so a new entry point does not silently become a new behavior.

Packaging

Make dependencies, state, and delivery contracts explicit.

A repository's shape is inferred from its layout; the surface is a separate concern. The dependency direction runs surfaces → api → lib, with independent API submodules. Runtime dependencies are deliberately minimal; delivered checks use the Python standard library and must run without importing the racecar package. State belongs to its declared persistence class: release, administrator-controlled, or runtime-accumulated.

Package Shapes

A repository's package shape is inferred from its layout: src, src+server, server, or a flat Django arrangement. This is not the same as its public surface, which may be CLI, REST, MCP, a Django app, or an agent skill. Treating these dimensions independently prevents delivery structure from dictating interface semantics. The package can change shape without rewriting the underlying business capability.

Dependency Contracts

The package defines a strict direction of imports. Surface adapters depend on API, API depends on library, and independent API submodules do not import one another. Delivered check scripts remain standard-library-only and cannot import the racecar package, because an adopter receives the scripts without that package. The checkers must be runnable in the environment they are intended to grade.

Persistence Contracts

Release artifacts, administrator-controlled configuration, and runtime-generated state have different lifetimes and writers. Their placement must follow those distinctions. A file that changes during operation must not be treated as immutable package source; a released artifact must not silently become a runtime scratchpad. Explicit state ownership is part of reproducibility, auditability, and reliable upgrades.

SOPs & Skills

Give AI agents bounded, repeatable engineering procedures.

Skills are procedures loaded when needed, not a replacement for governing rules. They invoke the same API as the CLI. The system covers review, documentation, construction, package and server creation, security, deployment, upgrade, and diagnosis. Procedures must preserve independent verification and accountable human approval.

Planning & Building

Agent procedures begin with a bounded task, relevant contracts, and a defined result. Construction changes the smallest necessary implementation and runs applicable deterministic checks. The agent may explain findings and propose repairs, but cannot replace an independently authored specification with its own output or declare a violation acceptable because the result looks plausible.

Review Lenses

The three review lenses are arch-python, eng-review, and doc-coherence. Architecture covers the Python and Django expression of governing rules and structural checks. Engineering review covers code hygiene, tests, and review practice. Documentation coherence covers document contracts, updates, and the documentation graph. Generators and orchestrators are supporting machinery, not additional lenses.

Construction Cascade

The cascade moves through create-package, create-server, secure-server, and deploy-server. Each rung is idempotent and can satisfy prerequisites by invoking earlier rungs. The package is the reusable library; the server exposes it; security and deployment add operational obligations. The last rung does not edit application code. Distinct steps keep side effects and prerequisites visible.

Adoption & Maintenance

Adoption installs canonical checkers and procedures into another repository without making it depend on racecar's package. Sync and normalize reconcile delivered artifacts, upgrade reports mechanical divergence, and doctor inspects installation and wiring. The adopting repository owns its exceptions and ship decisions; the escalation path records where the canon itself needs correction.

Checks & Lenses

Verify structure without making a model the judge.

Checks are standalone standard-library scripts returning exit 0 (done or clean), 1 (findings), or 2 (unable to run). They identify concrete file:line defects and do not decide whether to ship. Construction asks whether a thing was built correctly; conformance asks whether it matches an independently authored specification, including both missing and undeclared elements. Three lenses cover architecture, engineering review, and documentation coherence.

Deterministic Checks

Checks use standalone Python standard-library scripts and run locally. They report concrete findings rather than asking a language model for a verdict. Exit 0 means completed or clean, 1 means the check ran and found violations, and 2 means it could not run. A skipped or broken check must never be mistaken for a passing check. Findings inform the owner; they do not decide release.

Independent Conformance

Construction checks whether an implementation obeys engineering constraints. Conformance compares it to an independently authored declaration of what should exist. It must catch both omissions and unapproved additions. If the declaration is generated from the implementation on every run, the comparison is circular and incapable of detecting drift. Independence is a property of the evidence, not just the tooling.

Findings & Verdicts

A finding records severity, file, rule, and message. The controlled severity vocabulary is Blocker, Major, Minor, and Nit. Review dispositions are Ship, Revise, or Rework. These are separate concepts: deterministic checks report violations, review disciplines interpret evidence, and the repository owner decides whether the result is acceptable. Green checks are not an automated merge verdict.

Delivery & Adoption

Move from a library to an operable service deliberately.

The cascade consists of create-package, create-server, secure-server, and deploy-server. Later rungs satisfy earlier prerequisites; the sequence is designed to be idempotent. Adoption syncs canonical scripts into a repository, checks drift, and retains the adopting owner's authority. The tracker rail carries concrete failures of racecar's defaults back for review.

Adopter Delivery

The delivery manifest inventories files racecar syncs into adopting repositories. It includes standalone scripts and shared lexicon schema read by their checkers. Templates create missing starting artifacts rather than overwriting user-owned changes. The manifest is checked against the canonical catalogue, so the description of delivery cannot quietly diverge from the delivered set.

Deployment

The delivery path is staged: build a package, create a service, secure it, and deploy it. Host tooling validates and expands seed configuration, inspects proposed changes without touching a host, and requires explicit execution for deployment. Long-running work can be chunked and resumed. Planning, checking, and irreversible operations remain distinct rather than hiding inside one opaque command.

Feedback & Escalation

When a default fails in an adopting repository, a structured tracker rail records evidence and escalates the problem. The operator approves the issue draft before sending it; unknown fields or headings are refused. A hash-chained egress receipt is recorded before external transmission, providing forensic observability without keeping a second copy of the payload. This is not an exfiltration control.