Config Spine

Config Spine is a compiler for engineering analysis configuration. It is a tool that enforces ICD as code. It is used to allow interface contracts between your analyses — which today may be a Word doc ICD, a spreadsheet, or tribal knowledge. And allows them to become typed, unit-aware, Git-versioned artifacts that a compiler checks before anything runs.

The value add of this config-compilation step is that it will catch most misconfiguration errors that might error any of your simulations/analyses ahead of time and allow quick config review and error detection. This can save you hours/days/weeks of expensive simulation/analysis time.

A good example is the Mars Climate Orbiter failure, which was lost because one side of an interface produced lbf·s and the other consumed N·s. In Config Spine that is a specific error code SPINE-E004, which surfaces unit mismatch errors. If that project had used Config Spine, it might have caught a the mismatch which resulted in a $327M failure.

Core features and use cases include

• Catch interface errors before execution — units, shapes, references, and schema conformance, with stable error codes and located diagnostics.
• See the whole process — the N×N (N²) design structure matrix, feedback loops and all, generated as a build artifact (live demo review pack), plus Mermaid/DOT graphs and an offline HTML review pack.
• Manage iteration deliberately — feedback cycles are first-class: declared convergence strategies, fixed-point execution, spine sequence reordering to minimize feedback (the DeMAID job).
• Prove any result — provenance (git commit, content hashes, fragment origins), baselines and diffs, field-level history from Git, margins against requirements.
• Keep your tools — analyses stay in your Python, legacy executables, and vendor codes; adapters wrap them. Config Spine replaces the brittle glue between tools, never the tools.
• Safe for AI agents — deterministic CLI, JSON everywhere, validation-gated writes, 13 shipped agent skills, and an MCP server. The workflow becomes: AI drafts, the compiler validates, the engineer approves.

Who it's for

The integration lead on a 5–50-engineer multidisciplinary hardware team (launch, satellite, eVTOL, fusion, motorsport, process plant…) who owns a coupled analysis loop across heterogeneous tools.

Who it's not for: single-tool workflows with no coupling (a Makefile is enough), or teams wanting a hosted GUI.

Security design

This project is open-source and designed to be local-first, git-first and air-gap-safe — see SECURITY.md.

Install

Into your own project (Python 3.11+; full guide: docs/installation.md):

uv tool install config-spine        # or: pipx install config-spine

spine init          # scaffold a workspace in your repo
spine validate      # green compile

Working on Config Spine itself: clone, then uv sync && uv run spine --help.

Adopting Config Spine on an existing codebase

Your ICD is probably already written — in Python. Point the tool at your repo and it mines the evidence (signatures, unit-suffixed names like thrust_n, file handoffs, import edges, hand-rolled convergence loops) into a map your agent turns into draft contracts:

spine adopt path/to/your/repo   # survey + printed next steps

The funnel: spine survey collects evidence deterministically (no LLM, authors nothing, works air-gapped) → the spine-codebase-cartographer agent skill proposes draft analyses, artifact types, mappings, and adapters — every inference citing its file:line evidence, every unknown an explicit gap → spine validate gates the writes → spine review renders your own process as an N² matrix in the first session.

The whole funnel is written up as a step-by-step worked example — a simulated team repo (hand-rolled convergence loops, an imperial legacy tool, and a silent lbm/kg bug the compiler catches) taken from zero to a validated, rebuild-on-demand model: see [examples/zero_to_adopted/README.md](https://gitlab.com/config-afficianados/config_spine_project/-/blob/main/examples/zero_to_adopted/README.md).

Demo workspace

The repository root is itself a working demo workspace: a toy aeroelastic sizing loop (aero_vlm <-> structures_beam feedback cycle, feeding a mass_rollup).

uv run spine validate            # phases 1-3: syntax, structural, semantic
uv run spine compile             # build IR, link, emit build/<run_id>/compiled_plan.json
uv run spine plan                # show execution plan (layers, cycles, data flow)
uv run spine graph               # emit build/arch.mermaid (or --format dot)
uv run spine review              # offline HTML review pack incl. the N² matrix
uv run spine codegen             # emit generated/models + generated/stubs
uv run spine run                 # compile + phase-4 checks + execute the plan
uv run spine status              # changed files / stale outputs since last build

spine run is the top rung of the runtime adoption ladder — you never have to hand over your execution loop to get the contract enforced:

Level	Posture	Who owns the loop	Cost to try
0	spine survey / spine validate	nobody runs anything	minutes
1	shadow validation — your orchestrator + spine.shadow / spine check-io	the team	one line per seam
2	spine run — the executor	Config Spine	adapter manifests

Both levels enforce the same compiled ICD; teams that stay at Level 1 forever are a success, not a failure. Shadow checks are opt-in per call site and never mutate values; SPINE_SHADOW=off makes them no-ops (overhead numbers in docs/shadow_performance.md). See docs/integration/external_orchestrator.md.

The same workspace also contains a second, harder example: a launch-vehicle sizing loop with nine analyses, two disjoint feedback cycles, an imperial legacy trajectory tool (psf/fps/lbm with explicit unit_convert mappings to SI consumers), a CSV drag table flowing between analyses, a fan-in multiplicity-list mass port, and a [3, 3] inertia-tensor array artifact. Select it with --run on any command (see docs/examples.md):

uv run spine plan --run projects/vehicle_sizing/runs/vehicle_sizing.yaml
uv run spine run  --run projects/vehicle_sizing/runs/vehicle_sizing.yaml

Exit codes: 0 success, 1 validation error, 2 compilation error, 3 execution error, 4 environment error.

Layout

Path	Role
schemas/spine/	Meta-schemas for manifest types (workspace-global)
lib/	Shared schemas, analyses, mappings, adapters, and demo implementations
projects/<id>/	Program-specific authored trees and run manifests
src/spine/	The compiler: frontend/, semantic/, ir/, backends/, runtime/ (executor + shadow* validation), survey/, inspectors/, scaffold/, templates/, api/, mcp/, history/, cache/, cli/
generated/, build/<run_id>/, .spine/	Build artifacts (gitignored, reproducible)
outputs/	Runtime artifacts per run: results, logs, provenance (gitignored)
docs/diagrams/	Architecture diagrams (draw.io sources + rendered PNGs)

Each run manifest selects an ordered library of roots (inferred from projects/<id>/runs/ when omitted). Later roots shadow earlier ones on duplicate symbol ids. Run inputs bind project-specific instance data.

Validation phases

1. Syntax - files parse (YAML/JSON/CSV well-formed)
2. Structural - instances conform to schemas (JSON Schema + Frictionless)
3. Semantic - references resolve; units, shapes, and mappings are compatible; cycles have declared iteration strategies
4. Execution - adapters callable, files present, environment ready

Every diagnostic carries file, line/column, JSON Pointer, schema path, analysis/port id, and an error class (see docs/validation_strategy.md). Run spine explain SPINE-E004 to look up any code's meaning, guidance, and fix from the terminal; the full table is generated into docs/error_codes.md.

Status, stability, and security

Pre-1.0 and moving deliberately: diagnostic codes, authored file formats, and JSON output shapes carry explicit stability guarantees — see docs/versioning_and_stability.md and CHANGELOG.md. All authored artifacts are plain YAML/JSON/CSV in your own repo, so the exit cost is low by design. No network calls, no telemetry, air-gap-safe: SECURITY.md.

Tests

uv run pytest -n auto

Code quality

Formatting and linting are automated — format-on-save in VS Code/Cursor, ruff + pyright via pre-commit and CI. One-time setup after uv sync:

uv run pre-commit install --install-hooks

Day-to-day commands (see Justfile):

just format      # ruff format
just lint        # ruff check
just lint-fix    # ruff check --fix
just typecheck   # pyright (standard mode)
just test        # pytest -n auto
just check       # lint + typecheck + pre-commit — run before committing

Conventions, the # type: ignore[code] policy, and agent tooling are documented in AGENTS.md (see "Code Quality").

What spine review gives you

Worth a look even if you never adopt the compile-time checking. One command — spine review — turns a coupled analysis process into a design-review deliverable: static HTML, no server, no network, generated in seconds and regenerated in CI on every commit, so it cannot drift from the model. Everything below is emitted output from the nine-analysis launch-vehicle demo in this repository; none of it was drawn by hand.

The N² design structure matrix — feed-forward above the diagonal, feedback below it, the artifact named in every cell, cycle members badged with their cycle and iteration count, external file-bound inputs in the leading column, owning team on every row:

The same process as a graph, with each cycle boxed alongside the convergence strategy it declared and each node tinted by what happened on the last run:

See an example of the full review pack using the links below:

• Live demo — the real pack, zero install.
• The full tour — every section, with the honest caveats.
• Committed snapshot — the same pack as one self-contained, JavaScript-free HTML file.

You never have to hand over your execution loop to get this: spine review works straight off validate/compile, and --with-provenance merely overlays run results when you have them.

Background & FAQ

Why this project exists, how it was built (candidly), and the questions people tend to ask:

• Why I built this — developer thoughts
• FAQ

Interested in contributing? See CONTRIBUTING.md. If you are interested in contributing, you may want to look over the /planning_and_roadmaps/ to see what kinds of considerations were thought of in developing this project. In particular the business_case_and_target_engineer and market_driven_roadmap were core design documents.

License

Apache-2.0.