The AGENTS.md safety system

Restate what the customer should experience, what must not change, what proof is required, and exactly what approved means before work begins.

Nobody should build from a fuzzy promise. The team needs one visible finish line.

The agent finishes a task that looks busy but does not solve the real problem.

Everyone starts from the latest approved master copy, then works in a separate claude/ branch. Each teammate owns one workspace. After one teammate’s work is accepted, everyone else refreshes from the new master before continuing.

It is like ten editors working from the same book while keeping separate drafts—nobody writes over someone else’s pages.

People build from old copies, overwrite good work, or combine drafts that no longer fit together.

Read repository instructions, check branch and working tree state, inspect relevant code, then run related existing tests and record any pre-existing failures.

This separates existing problems from regressions and reveals user or agent work that must be preserved.

The agent overwrites unknown work or mislabels an old failure as a new regression.

Change only task-required files. Name protected files and require extra review for shared configuration, lockfiles, auth, billing, migrations, webhooks, admin, deletion, and deployment code.

Small changes in shared or sensitive files can affect every user and create merge conflicts.

A side refactor or casual protected-file edit introduces unrelated breakage.

Reproduce or trace the failure, identify its cause, check related behavior, and implement the smallest complete correction—not a symptom-hiding workaround.

A correct fix removes the reason the defect exists.

Retries, loosened validation, or swallowed errors hide a defect that later returns.

No placeholders, production mocks, hard-coded fixes, disabled checks, skipped tests, weakened assertions, swallowed errors, unsafe casts, force flags, commented-out behavior, or essential TODOs presented as complete.

‘No shortcuts’ is enforceable only when forbidden shortcuts are named.

The task appears finished because the difficult requirement was bypassed instead of implemented.

Never commit, expose, or log secrets. Never weaken authentication, authorization, payments, billing, usage limits, deletion, webhooks, or security checks just to make code or tests pass.

A tiny shortcut in sensitive code can expose data, money, or every customer account.

A passing build quietly introduces a security or financial vulnerability.

Never rewrite a deployed migration. Create a new one, preserve backward compatibility, and document the exact migration → verification → application deployment order.

The application and production database must stay compatible during every release step.

Code reaches production before its required schema and breaks purchases, scans, or sign-ins.

Run the repository’s lint, format, typecheck, unit, integration, end-to-end, and production build commands plus a final diff review. Only the user may authorize a skip.

One passing check never replaces the others, and a small diff can still carry large risk.

‘Looks fine’ substitutes for verification and a broken change reaches review.

Test the exact fix and existing adjacent workflows that share code, application programming interfaces (APIs), tables, auth, billing, or state. For bugs, add a test that fails before the fix and passes after it whenever practical.

New behavior can work while silently breaking an existing customer path.

The target feature passes, but sign-in, checkout, usage counts, or another related flow regresses.

Run SonarQube for the two designated businesses and Semgrep for the other eight. Fix what the outside inspection finds, then show Courtney the finished work and proof. Nothing ships until Courtney says push.

Like a home inspection, an independent checklist spots problems the builder may be too close to see.

The builder grades its own work, misses a hidden problem, and sends it live too soon.

Separate verified facts, reasoned inferences, untested assumptions, and uncertainty. Report exact commands and results from the current revision, skipped checks, files changed, risks, and required deployment steps.

A completion claim is useful only when its evidence is visible and current.

The agent says ‘done,’ ‘safe,’ or ‘tested’ when work was assumed, skipped, or checked on an older revision.

A separate read-only reviewer receives the original request, acceptance criteria, base branch, final diff, protected-file rules, test results, and scanner findings—not the author’s conclusions. It checks correctness, security, regressions, migrations, race conditions, test gaps, and maintainability.

A fresh agent can challenge assumptions instead of repeating the implementer’s reasoning.

The author reviews its own work, repeats the same blind spot, and approves itself.

The implementer addresses every valid reviewer or scanner finding. After any code change, rerun affected tests, regression checks, build, scan, and reviewer pass. Never mark a finding resolved without evidence.

Approval becomes stale the moment reviewed code changes.

A review fix introduces a new regression that is never rechecked.

Approved means the promise was kept, every required check passed, both inspectors signed off, no serious warning remains, the work matches the current master copy, and Courtney gives four clear words approving that one action. The ticket expires after use.

Approval should work like a boarding pass: one person, one trip, one use—not a permanent permission slip.

An old or vague yes is reused to justify a different push, release, payment, or risky action.

Merge one approved branch at a time. After each merge, every remaining branch updates from the new main, resolves conflicts deliberately, reruns all relevant checks, and receives fresh approval before merging.

A branch that was safe when work started can become stale after another agent changes shared code.

Several individually safe branches collide or silently remove one another’s behavior.

Stop and obtain explicit user approval before merging or deploying authentication, authorization, payments, subscriptions, billing, usage limits, production migrations, account deletion, secrets, security controls, destructive data operations, or production configuration. The hard stops in AGENTS.md override everything.

Agent review, Semgrep, SonarQube, and passing tests reduce risk but never replace accountable human judgment.

A technically passing change reaches production even though its business, data, or security consequences were never knowingly approved.