specs
A small method for keeping software honest with coding agents: a living specification, testable requirements that cite it, and tests that cite the requirements. When they disagree, the specification wins, and behavior changes update the specification in the same pull request as the code.
It works with Claude Code, Cursor, GitHub Copilot, and Codex, and with people.
Site: https://justinmchase.github.io/specs/. Point an agent at that page, or paste the install prompt from it, to install the plugin and adopt the method.
Agents: start here
If you were asked to set up the specs method in a repository:
- Read
skills/specs-init/SKILL.mdand follow it. It adds.agents/SPECS, two index files, and a short block inAGENTS.md. It does not copy the method into the repository. - To write specifications or requirements afterwards, follow
skills/specs/SKILL.mdandskills/requirements/SKILL.md. - For an existing codebase, follow
skills/specs-extract/SKILL.mdto bring one area of existing behavior into the method. - To check the result with that repository's tests, follow
skills/specs-verify/SKILL.md.
If the repository already has an .agents/SPECS file, it has adopted the
method; read its AGENTS.md.
The method in one screen
| Layer | Lives in | Is |
|---|---|---|
| Specifications | .agents/specifications/ | The normative contract, as focused chapters. |
| Requirements | .agents/requirements/ | Narrow, testable statements citing a chapter. |
| Tests | anywhere | Executable checks citing requirements: req:{id}. |
| Implementation | anywhere | The code. |
- Higher layers win. Never edit a test or code to contradict a requirement or the specification; ask whether the higher layer should change.
- A behavior change updates the specification or requirement in the same change as the code. A behavior nobody specified is a gap to fill, not a license.
- Requirements cite specification sections (
spec_ref), tests cite requirements (req:{id}), and the repository's own local tests verify behavior.
The normative definition is in
.agents/specifications/. Unlike
per-feature spec tools such as GitHub Spec Kit or Kiro, the specification here
is not a plan that gets used up: it is the standing contract the code is held
to.
A repository that follows it
AGENTS.md a short pointer block (see below)
.agents/
SPECS "specs v1" and this repository's URL
specifications/
README.md the index
{topic}.spec.md
requirements/
README.md
{topic}/{NNN}-{name}.requirement.md
.agents/SPECS declares the method and its major version, like a LICENSE file
declares a license:
specs v1
https://github.com/justinmchase/specs
Optional key: value lines after a blank line change the layout
(specifications:, requirements:, tests:); see the
marker chapter.
The method is never copied into the repository. Agents get it from the plugin,
or from the pinned links in the AGENTS.md block
(skills/specs-init/assets/agents-block.md),
so it does not drift from repository to repository.
Install
Installing the plugin gives your agent the specs, requirements,
specs-init, specs-extract, and specs-verify skills. The plugin contains no
callable tools or MCP server.
| Agent | Install |
|---|---|
| Claude Code | /plugin marketplace add justinmchase/specs, then /plugin install specs@justinmchase |
| GitHub Copilot CLI | copilot plugin marketplace add justinmchase/specs, then copilot plugin install specs@justinmchase |
| Codex | codex plugin marketplace add justinmchase/specs, then codex plugin add specs@justinmchase |
| Cursor | Customize → search specs, or git clone https://github.com/justinmchase/specs ~/.cursor/plugins/local/specs, then reload |
Cursor teams can instead import this repository as a team marketplace. Agents
without the plugin can still follow the method through the links in the
AGENTS.md block. A prompt any agent can follow lives at
https://justinmchase.github.io/specs/install.md.
Verify requirements
Use the adopting repository's normal unit or local test suite. Each test cites
the requirements it verifies with req:{id}. The specs-verify skill guides
agents to inspect those links, add tests where coverage is missing, run the
repository's tests, and report remaining gaps. A citation alone does not prove
the requirement is tested; the assertions must exercise its behavior.
This repository retains a Deno audit for checking its own marker, requirement
documents, and test references. Its standalone CLI and GitHub Action remain
available for existing users, but they are not plugin tools or part of the
skills' adopting workflow. This repository runs the audit in deno task pre and
CI.
Versioning
Releases follow semantic versioning. The major version is the one a repository
names in .agents/SPECS; each stays available at the v{major} branch, which
the AGENTS.md links use. Publishing a release fast-forwards that branch to it.
The major version changes when the method's compatibility contract changes.