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.
Give this to an agent
Paste the prompt into any coding agent, or point the agent at this page.
Install the specs plugin from https://github.com/justinmchase/specs for the coding agent you are using, then adopt the specs method in this repository. Follow https://justinmchase.github.io/specs/install.md. Do not copy the method into the repository.
If you are a coding agent
You were pointed at this site to install specs. Follow install.md in the repository you are working in. In short:
- Install the
specsplugin for the product you run in (Cursor, Claude Code, GitHub Copilot CLI, or Codex). Do not copyskills/into the repository. - If
.agents/SPECSalready exists, the repository already follows the method. - Otherwise, if you were asked to set it up, follow specs-init.
The method
| Layer | Lives in | Is |
|---|---|---|
| Specifications | .agents/specifications/ |
The normative contract. |
| Requirements | .agents/requirements/ |
Narrow, testable statements citing a chapter. |
| Tests | anywhere | Executable checks citing req:{id}. |
| Implementation | anywhere | The code. |
Higher layers win. A behavior change updates the specification or requirement in the same change as the code.
Install
| Agent | Install |
|---|---|
| Cursor | Customize → search specs, or
git clone https://github.com/justinmchase/specs ~/.cursor/plugins/local/specs
and reload. Teams can import the repository as a marketplace. |
| 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 |
The plugin gives the agent the specs,
requirements, specs-init,
specs-extract, and specs-verify skills. It has no
callable tools. Agents without it can still follow the pinned links in
install.md.
Verify
Use this repository's own tests. Each test cites the requirements it
verifies with req:{id}. Follow
specs-verify.