The Spine — the files
Five downloads, one source. Take the whole directory, one file, or just the fragment that teaches your coding agents to read it. What the spec is is a separate page — this one is only the artefacts.
Version 0.2 · Generated 9 Sept 2026 · No email required
Downloads
There are five rather than one because the reasons to take this are different, and a single zip serves only the first of them.
- Download
spine-template.zip
ZIP archive · 12.0 kBThe whole arch/ directory: spine.yaml, twelve concern files with prompts instead of prose, and a first ADR already numbered.
Take this one if: Starting a new repo, or retrofitting one this afternoon.
- Download
spine.md
Single Markdown file · 14.2 kBEvery concern concatenated into one file. Smaller systems do not need twelve; collapse first and split when a section earns it.
Take this one if: A service small enough that twelve files would be a lie.
- Download
spine.yaml
YAML · 6.5 kBThe machine layer on its own, commented line by line, validating against the published schema.
Take this one if: You already document elsewhere and only want the machine layer.
- Download
AGENTS.spine.md
Markdown fragment · 2.6 kBPaste into AGENTS.md or CLAUDE.md. Teaches a coding agent to read arch/ before it writes, cite the decision it relied on, and open an ADR instead of silently contradicting one.
Take this one if: Any repo where agents write a meaningful share of the code.
- Download
spine.schema.json
JSON Schema (draft 2020-12) · 10.0 kBVersion 0.2 of the machine layer. Point your editor or CI at the URL and spine.yaml gets completion and validation for free.
Take this one if: Editor autocomplete, and a CI check that the spec parses.
What the zip contains
A single top-level arch/ directory — 16 files — so it unzips into a repo root without scattering anything.
The concern files contain prompts, not prose. Every line either asks you a question or tells you what the section is for; there is no sample content to delete and no lorem ipsum pretending to be an example.
ADR-0001 is already written and numbered: the decision to keep decisions. It doubles as the format example, so nobody has to guess what an ADR should look like here.
Delete the concern files your system has not earned. Four you maintain beat twelve you wrote once.
- arch/spine.yaml
- arch/README.md
- arch/01-decisions.md … 12-vocabulary.md
- arch/decisions/ADR-0001-…md
- arch/AGENTS.spine.md
Wire the schema into CI
Optional, and it is the difference between a spec and a file. One check that the machine layer still parses stops the whole directory rotting quietly.
# One step. Fails the build when the machine layer stops parsing.
- name: Validate arch/spine.yaml
run: |
curl -sLo /tmp/spine.schema.json \
https://ruchitsuthar.com/architecture/spine.schema.json
npx --yes js-yaml arch/spine.yaml > /tmp/spine.json
npx --yes ajv-cli@5 validate --spec=draft2020 \
-s /tmp/spine.schema.json -d /tmp/spine.jsonFor editors, the template already carries the yaml-language-server comment on line one — VS Code, JetBrains and any Neovim YAML LSP pick it up with no further setup.
The agent bundle, specifically
AGENTS.spine.md is a fragment you paste into your repo’s AGENTS.md or CLAUDE.md. It does four things: tells an agent which files to read before it writes, which guardrails are binding, when to stop and draft a superseding ADR instead of choosing, and what to cite in the pull request.
Delete any rule your repo cannot back up with a real file. A rule pointing at something that does not exist teaches an agent to treat the whole section as optional, which is worse than having no section.
Frequently asked
Do I need to give an email address?
No. Every file on this page is a direct download from this domain, there is no form, no account and no tracking pixel in front of it. If you want to be told when the schema version changes, the newsletter is opt-in and separate.
What licence is the template under?
Free to copy, fork, modify and use commercially, with no attribution requirement. It is a template: the value is in your filled-in copy, not in the blank one.
Which file should I start with?
The zip if you are putting this in a repo — it contains a top-level arch/ directory, so it drops in without scattering files. The single Markdown file if you are still deciding whether the artefact is worth adopting and want to read all of it in one scroll. The agent bundle on its own if you already document architecture somewhere and only want your coding agents to respect it.
How do I validate spine.yaml in my editor?
Add the yaml-language-server schema comment at the top of the file, pointing at the published schema URL. VS Code with the YAML extension, JetBrains IDEs and Neovim with a YAML language server all pick it up and give you completion, enum validation and inline errors with no further configuration.
Will the format change?
Yes — this is version 0.2, and the machine layer will change as the practice does. Additions are backwards compatible: 0.2 added the optional context block, and a spine.yaml still declaring 0.1 validates against the same published URL. Anything that could invalidate an existing file gets a new schema version, and the old URL keeps working.