Racecar

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

P-01 through P-08

Racecar Positions

R-01 through R-12

Declaration Tree

Rules, groups, and settings

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, checks, lenses, skills, surfaces

Two Axes of Verification

Construction and conformance

The Three-Layer Boundary

Surfaces → API → library

State & Delivery

Release, control, and accumulated state

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

Kinds and their required properties

Topology

Permitted containment and tier shape

Graph

Instances, edges, provenance, and readers

Declared Graphs

Explicit sources and independent readers

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

Addresses and containment in the command domain

Verbs

Declared operations beside the nouns they act on

Parameters

Typed flags as governed nodes

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

A declared command tree over the shared API

Agent Skills

On-demand procedures, not a second implementation

Generated REST & MCP

Additional adapters for adopting repositories

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

Layout is distinct from interface

Dependency Contracts

Surfaces above API above library

Persistence Contracts

State has an owner and a lifetime

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

Bound work before agents implement it

Review Lenses

Architecture, engineering, and documentation

Construction Cascade

Create, secure, and deploy in bounded rungs

Adoption & Maintenance

Sync, normalize, upgrade, doctor

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

File:line evidence and explicit exit codes

Independent Conformance

Specification and implementation must not grade themselves

Findings & Verdicts

Evidence is distinct from authority

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.