specs logo

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 prompt
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:

  1. Install the specs plugin for the product you run in (Cursor, Claude Code, GitHub Copilot CLI, or Codex). Do not copy skills/ into the repository.
  2. If .agents/SPECS already exists, the repository already follows the method.
  3. 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.