The agent contract#

How a machine drives this CLI. The rules are fixed by ADR-0017; this document is generated from the source so it cannot drift from it.

The rules#

1. One JSON document per invocation. In --json mode stdout carries exactly one JSON document. Prose, progress and warnings go to stderr, so cmd --json 2>/dev/null | jq . always parses.

2. One diagnostic envelope, everywhere:

   {
     "severity": "error" | "warning" | "info",
     "code": "snake_case_stable_string",
     "message": "human sentence",
     "target": "the thing at fault (optional)",
     "fix": "one actionable sentence or command (optional)",
     "file": "relative/path.md (optional)",
     "line": 42
   }

   Branch on code, never on message. message is prose and may be reworded; code is the published surface.

3. Failure carries the command's null-shape. A failure prints { ...nullShape, "status": [diagnostic] } and exits 1 — never bare stderr, never a partial document. A consumer never has to tell "it failed" apart from "it printed nothing".

4. camelCase everywhere in command output. (The on-disk formats are not command output: pack.yaml keeps schema_version and .specops.lock keeps pack_id.)

5. --json and --format json are the same flag. The second spelling predates the contract and keeps working.

Exit codes#

A gate command exits 1 when it finds something, which is not the same as failing to run. The status array tells the two apart: a gate that could not run reports an error about itself.

Commands#

The document key is what the payload carries on success and what is set to null on failure. Every document also carries status: an array of diagnostics, empty when there is nothing to report.

Diagnostic codes#

Harvested from the source. A trailing * marks a family whose suffix is computed — strict_tdd_* covers strict_tdd_1 through strict_tdd_3.

Worked example#

specgate change instructions specs --json 2>/dev/null | jq -r '.instructions.rules[]'

An agent that reads fix self-corrects; one that reads only message retries the same mistake. That is why a check without a fix is treated as unfinished.