Glossary

The rules file that AI coding tools read before they work in a repository: how the project works, and what an agent must and must not do. Keep it short and point to longer guides. A rule written only there is a request, so back the rules that matter with a check.

An AI reviewer with one job: the spec, the tests, the architecture rules or security. It reads a change and reports what it finds, and never edits a file. Its verdict is advice for the author and the reviewer; it never blocks a merge.

A file that sets the rules everyone else works under, such as the check scripts, the CI workflow, the hook settings and AGENTS.md. Only its owner changes it. The guard stops an agent from writing one.

The far end of autonomy: specs go in, software comes out, and no person writes or reviews the code. The name comes from factories that run with the lights off. The factory taught here is not one: a person reviews every change before it merges.

A path that lets one narrow kind of low-risk change, such as a docs-only change, merge without a person. Fixed rules that a script can check decide what counts as low risk, and anything unknown counts as no. It first runs in shadow, scoring changes while a person still merges, and opens only by a recorded decision when the numbers support it.

One command that runs every check and says pass or fail; people, agents and CI run the same one. If an agent or a person can skip it, it helps. If it runs on every pull request no matter what, it's the gate.

A script that says no to a few dangerous actions before an AI tool runs them, such as a force push, a write to a secret file or a change to a control file. It is a help, not a wall: a guard that reads the text of a command can't catch everything. The wall is the required check on every pull request.

Everything around the model that lets an agent do the work and keeps it on track: the AI tool, the context and rules it reads, its hooks and the checks. The model can be swapped; the harness is where most of the engineering goes.

A test of your tests. A tool changes the code in small ways, for example a plus becomes a minus, and runs the tests after each change. A change the tests don't notice has survived, and points to a test that checks less than it seems.

A list of small tasks, each with its test, written by an agent from an approved spec. A person approves the plan before the build starts.

A score out of 100 for how ready a codebase is for agents, over five areas: setup, tests, written rules, docs and safety. Every lost point comes with a reason, and a check it can't read is unknown, not a fail. It is advice: it changes nothing and is part of no check.

One closed place for agent runs, so that no person has to watch a run as it happens. Nothing the agent does inside can reach a person's files, another machine or a key that can write to your repositories. The box is the boundary; the AI tool's own rules and hooks are help inside it.

A short document a person approves before any code is written: what to build, and how we know it is done. Each acceptance point can be checked with a yes or a no.

A hook that runs when an agent says it is done. If anything changed, the full check runs; if it fails, the agent is told why and sent back, at most twice. After a third failure the agent stops and a person takes over.

One piece of work, small enough for one pull request, with acceptance points that can be checked with a yes or a no. The best tasks name a command that says done or not done. A person decides which tasks an agent may build.