Where the files are
Each domain of the specification is kept under specs/<domain>/, opening with its header in specs/<domain>/00-<domain>.json, contracts under specs/contracts/, the technical appendix under specs/tech/, each of its sections in a file of its own — a domain's in <domain>.json, the stack's in stack.json, the technical debt's in debt.json — and the guidelines under specs/_guidelines/: a project's own guidelines in project.json, and, in the repository the SpecSheriff guidelines are written in, the base in spec.json and the appendix of the tools in tools.json, which every other project reads from the plugin of its agent (§s-zh2vcr3xjumppg5, §s-2pdy9gw2jrjvfb4). A part divided into one file per section keeps its files in its directory.
The schema is kept in specs/_schema/ of the repository the SpecSheriff guidelines are written in, and every other project reads it from the plugin: node.schema.json for a node and its metadata, section-file.schema.json for the file of a part.
Confirmations are kept in specs/_confirmations.jsonl, the archive of removed nodes in specs/_archive/<name>.json. specs/_viewer/ (the map) and md-version/ (the readable export) are rebuilt after every change to the specification and not stored in git.
The SpecSheriff tools provide the command sheriff. In a terminal it is run from the tools a plugin keeps on the machine (§s-4mej6ccn7xu3d3p), as node <tools>/dist/cli.js, <tools> being the data directory of the plugin for Claude Code or the tools/ of the plugin for Codex CLI in Codex's cache.
Their plugin for pytest, the package pytest-specsheriff, is installed by pip from the branch release: pip install "pytest-specsheriff @ git+https://github.com/non4me/SpecSheriff@release#subdirectory=skills/pytest-specsheriff".
The settings of the SpecSheriff tools that a project shares are kept in sheriff.config.json at the root of the repository; those of the reviewer's runs, which each user confirms, are kept in the user's git configuration (§s-xr5xxa9cxf2mq5u). Among them, glob patterns name where the system's code lives and where its tests live: the code is read for tags, the tests for the sids they declare, and a file neither names for neither — which is how the repository's tools, its configuration and its tests are exempt from tags by where they live. The repository the SpecSheriff guidelines are written in says so by the setting "writesSpecSheriffGuidelines": true.
The documents are the markdown files the repository keeps outside specs/. The tools of the specification are the files of the SpecSheriff tools: a project keeps only the files sheriff init writes, and the repository the SpecSheriff guidelines are written in keeps them under skills/, where the tests are read for the sids they declare and no file is read for an address.
The specification's owner is the one the top node of project.json names, and the levels its domains stand at are the members of the list carried by the rule of project.json that refines §s-nkyty4dy9x2v2a4.
The links it makes
- implements → A part of the specification can be read alone
- implements → The structure of the specification is defined by its schema
- implements → Removal goes through the archive when the node was ever confirmed
- implements → The guidelines hold their base and the appendix of their tools
- implements → Only its owner confirms a node
- implements → Every domain stands at a level
- cites → The plugin for Claude Code carries everything its work needs
- cites → A git hook runs the SpecSheriff tools a plugin keeps on the machine
- cites → The plugin for Codex CLI carries everything its work needs
- cites → Who runs the reviewer
The decisions taken on it
- Problem
The toolset SpecSheriff provides was spelled the toolset, SpecSheriff's toolset and the tools: three names for one thing, the first a general word that does not say whose.
- Ruling
The owner: it is named the SpecSheriff tools.
- Problem
No package installed the command
sheriffany more: an agent found the SpecSheriff tools through the plugin for Claude Code, and a person's terminal had no command at all.- Ruling
The owner: nothing new is built. In a terminal the command is run from the copy of the tools the plugin keeps in its data directory, whose path is the same on every machine; the agent's skills run it from the tools the plugin carries.
- Problem
pytest-specsheriff, installed by pip, does not follow the plugin for Claude Code when Claude Code updates it.- Ruling
The owner: nothing is built and no rule says how it is updated. It registers the mark, checks its form and opens the reported name with the sid, while the checks read the sid from the test's source, so an older copy breaks no check; updating it is a person's action, which the practitioner's guide gives.
- Problem
By the owner's rule of 2026-10-29, what only the repository the SpecSheriff guidelines are written in does leaves the guidelines for an internal document; this rule says where that repository keeps the guidelines, their schema and its tools, and what it is not read for.
- Ruling
The owner: those clauses stay. They say what the SpecSheriff tools do in a repository that writes the guidelines, which every project's copy of the tools carries out; the procedures only that repository runs — a release, the build, running its own plugin — are in its internal document.
- Problem
The rule kept every setting of the SpecSheriff tools in sheriff.config.json, which every clone shares, while the settings of the reviewer's runs are each user's to confirm (§s-xr5xxa9cxf2mq5u).
- Ruling
Following the owner's ruling on §s-xr5xxa9cxf2mq5u: the settings of the reviewer's runs are kept in each user's git configuration rather than in sheriff.config.json.
The tests bound to it
- skills/tools/test/unit/binding.test.ts · s-zefk589ykh37b8u reads no file of the tools for an address where the SpecSheriff guidelines are written
- skills/tools/test/unit/config.test.ts · s-zefk589ykh37b8u reads the code for tags, the tests for sids, and a file neither names for neither
- skills/tools/test/unit/config.test.ts · s-zefk589ykh37b8u reads the globs naming where the system's code and its tests live
- skills/tools/test/unit/config.test.ts · s-zefk589ykh37b8u reads this repository's settings, whose tests are the tools' own
- skills/tools/test/unit/config.test.ts · s-zefk589ykh37b8u reads whether the SpecSheriff guidelines are written in the repository
- skills/tools/test/unit/config.test.ts · s-zefk589ykh37b8u refuses a model or an effort in the project's settings, naming the key of the user's git configuration that holds it
- skills/tools/test/unit/config.test.ts · s-zefk589ykh37b8u refuses settings that are missing, not JSON, or hold a key nobody declared
- skills/tools/test/unit/generated.test.ts · s-zefk589ykh37b8u keeps the readable export and the map out of git
- skills/tools/test/unit/model.test.ts · s-zefk589ykh37b8u tells a file's part and whether it holds the SpecSheriff guidelines
- skills/tools/test/unit/spec-files.test.ts · s-zefk589ykh37b8u finds each node with the file it stands in and its parent
- skills/tools/test/unit/spec-files.test.ts · s-zefk589ykh37b8u outside the repository the SpecSheriff guidelines are written in, reads them and their schema from the SpecSheriff tools
- skills/tools/test/unit/spec-files.test.ts · s-zefk589ykh37b8u reads every file of the specification under specs/, and neither the schema nor the archive as a part
- skills/tools/test/unit/spec-files.test.ts · s-zefk589ykh37b8u refuses a file of the specification that is not JSON, naming the file