Spec of Record (SoR)
Spec of Record is a development philosophy and toolchain for AI-built software, where one or many agents build from multiple spec files, aimed at mid-sized to large projects. It turns all specs into a centralized design document that always stays in sync with the code, so a team of different specialties can understand, review and change the software together. You write what your software should do in plain language, an AI agent turns it into code, and each piece of code stays linked to the statements in the spec and to its test results.
The spec is split into parts, so engineering, QA and UX can each work in their own field of expertise while sharing a common design document. You can change either side, the spec or the code, and the other one is updated to match.
To learn how this works, start at specofrecord.org. It covers the goal, an example, how to install it,
the tools and the questions people ask. This README only says what is in this repository.
What is in this repository
| Folder or file | What it is |
|---|
SPEC.md | The format. It covers files and hierarchy, the four sections of a part (Rules, Approach, Contract, Tests), items and ids, values and references, targets, code markers, the lock file (sor-lock.json), what a tool enforces and how agents work in parallel. It starts with a cheat sheet. |
tools/ | The sor command. That is tools/py/sor.py and the library behind it (tools/py/sorlib/), with its own tests and a coverage script. python3 tools/py/sor.py --help lists what it does. tools/js/ is a JavaScript copy of the commands an editor needs (markers, status and parts as JSON), which the VS Code extension runs so that it needs no Python. |
plugins/specofrecord/ | The Claude Code plugin, with the workflow skill, the edit guard and a copy of tools/. Its README has the requirements. |
.claude-plugin/marketplace.json | Lets the repository itself be added as a plugin marketplace. |
examples/solar-system/ | A complete project built with it, where planets orbit and you click one for a fun fact. Specs in sor/, the built page in out/. A good place to read real clauses next to their code. |
editors/vscode/ | The VS Code extension. It shows, inside the editor, which code comes from which clause and whether they still agree. It ships the JavaScript tool (tools/js) and runs it on the editor's own Node, so it needs no Python. |
.github/workflows/ | The builds. One makes the plugin zip, with tools/ bundled, and the other makes the extension's .vsix. |
SECURITY.md | How to report a security problem privately, and what is in scope. |
AGENTS.md, CLAUDE.md | How a coding agent works in a project with a sor/ folder. CLAUDE.md imports the plugin's skill, so the workflow is written once. |
index.html, social/ | The project page and its banner. |
Working on this repository
- Run the tests with
python3 -m unittest discover -s tools/py -p 'test_*.py'. They need no browser and touch only temporary
folders.
sh tools/py/coverage.sh runs them under coverage.- With
node installed (16 or later) the same run also checks the JavaScript copy in tools/js/ against the Python tool. Without it that test is skipped and says so.
- The plugin carries its own copy of
tools/ and of the cheat sheet, and the VS Code extension carries the JavaScript tool, tools/js.
After changing tools/ or the cheat sheet in SPEC.md, run sh plugins/sync-tools.sh (--check fails when a copy is
out of date).
- To release, set the version fields to the new version, commit, and push a tag
v<version>, for example
git tag -s v0.1.19 -m v0.1.19 && git push origin v0.1.19. The whole repository has one version, kept in
plugins/specofrecord/.claude-plugin/plugin.json, editors/vscode/package.json (and its lock file) and
tools/js/package.json, and a release fails when a build finds a version other than the tag's.
.github/workflows/release.yml builds the plugin zip with plugins/build-plugin.py
and the .vsix, then makes one GitHub release with both files (sor-plugin-v0.1.19.zip, sor-vscode-v0.1.19.vsix), a
checksum for the zip, and an attestation receipt for each file (<file>.attestation.jsonl). A download can be checked
against this repository with gh attestation verify <file> --repo sebastianrath/specofrecord, or offline by giving that
command the receipt as its bundle. It has to be one job, because GitHub locks a release once it is published. The .vsix is then
published to the Visual Studio Marketplace, once a publisher exists and the secret VSCE_PAT is set in the repository's
marketplace environment.
- Do not run
sor lock or sor claim against examples/ or editors/vscode to try the tool out. Use a temporary
folder.
License
The spec is CC BY 4.0 and the toolset is MIT. See LICENSE.md.
