PostgreSQL backup tool with Point-In-Time-Recovery and restore verification
agent-instructions Specification
Purpose
Keeps AGENTS.md and the repository's own skills stable: they hold rules of agent behavior, while descriptions of the system, inventories of what exists and the internals of tools live next to what they describe. This way an ordinary feature does not edit these files, and parallel branches do not conflict in them.
Requirements
Requirement: What belongs in agent instructions
Agent instructions are the git-tracked AGENTS.md files at the repository root and in subdirectories, and the repository's own skills, that is every skill except the generated openspec-* skills. Agent instructions SHALL hold only rules that change how the agent behaves and do not depend on which features already exist. Agent instructions MUST NOT hold:
- inventories of what already exists in the system: features, endpoints, checks, installed tools;
- statements about the current state of code with words like "currently" and "for now", except the rule about how to write about the current state;
- descriptions of how code, hooks and tools work: the internal steps of commands, hook trigger conditions, constant values, limits, models;
- retellings of another document's sections.
The root AGENTS.md SHALL name the place for each of these kinds of information: code and its comments, the API contract, docs/, the ADRs, a program's README, the hook docstring and prompts, the OpenSpec specs. An instruction MAY link to a file as an example or a source of values, when the link itself does not change with the file's contents. An instruction MAY hold:
- a table of documents with the topic of each;
- a table of commands the agent runs with the purpose of each, without its internal steps;
- the stack of a part: language and main frameworks;
- one sentence saying that a linter enforces a rule, without the list of its checks.
Scenario: A feature adds an endpoint
- WHEN a feature adds a backend endpoint
- THEN neither
AGENTS.mdnor any module doc changes, and the endpoint is visible in the code and the generated API description
Scenario: A module doc gets a new section
- WHEN a change adds a section to
website/AGENTS.md - THEN the
website/AGENTS.mdline in the rootAGENTS.mddoes not change, because it names the doc's topic rather than its sections
Scenario: A review hook changes
- WHEN a review hook changes its trigger, model, effort or reviewer prompt
- THEN the hook script, its prompt or its spec changes, and the root
AGENTS.mddoes not
Scenario: What the agent does with a finding category changes
- WHEN what the agent does with a full review finding category changes, for example it stops blocking the turn
- THEN the "Review hooks" section of the root
AGENTS.mdchanges, because that is a rule of agent behavior
Scenario: A new rule of agent behavior appears
- WHEN the team introduces a rule that changes how the agent writes code or answers
- THEN the rule is written in one place in the agent instructions, and other documents link to it
Requirement: The diff reviewer checks edits to agent instructions
The diff reviewer SHALL check every edit to agent instructions against the requirement "What belongs in agent instructions". When an edit adds an inventory of what exists, a statement about the current state of code, a description of how something works or a retelling of another document, the reviewer SHALL reject the turn and name the place to move that information to. An edit that adds or changes a rule of agent behavior MUST NOT be rejected under this criterion.
Scenario: An edit adds an inventory
- WHEN the agent adds "the backend currently has features X and Y" to a module doc
- THEN the diff reviewer rejects the turn and says that the state of the code is visible in the code
Scenario: An edit adds a rule
- WHEN the agent adds a rule that changes agent behavior to
AGENTS.md - THEN the diff reviewer does not reject the turn under the instruction content criterion