By the end of week one your corrections live in files, a gate refuses a bad push without you, and the agent runs read-only work without asking. It covers Arcs 1, 2 and 3, plus the branch-and-authority part of Arc 8. Nothing here depends on which agent tool you use. The cards say what to build and why; the bootstrap prompt below has your agent build them, and you check its work against the cards.
How to read the cards
Each card names one intent, then the layers that can enforce it, strongest first, then a plain sample. Put each intent in the strongest layer your setup has. The rules file is the fallback: it works only while the agent reads it and chooses to follow it.
Layer
What enforces it
Who it binds
Where it falls short
Git hook or CI check
git, or the CI runner
Every pusher, agent or person
A local hook can be skipped; CI runs only after the push
Server-side branch protection
The code host
Every pusher
Guards branches, never commands
Container or sandbox
The operating system
The agent process
Limits reach, not judgment: anything mounted is fair game
Harness permission file
The agent tool
That agent only
Each tool has its own format, and a reworded command can miss a pattern
Rules file
The agent's own reading
That agent only
It can forget, misread, or reason its way past a rule
The order isn't absolute. A local hook gives feedback in seconds and covers people too, but anyone can skip it. When a card needs a guarantee, pair the hook with a CI check the host requires before merge.
Hook or CI check, for any rule a script can test. Move it there and delete it from the rules file.
Rules file, for the rest. Three scopes, each rule in exactly one: private (your home directory, not checked in), workspace (the directory above all repos, checked in), repo (each repo root, checked in). A repo rule beats a workspace rule inside that repo, and the agent flags the conflict so one gets fixed.
Start with ten one-line rules. Each states a behaviour, plus the reason when it isn't obvious. Keep facts and history in a separate memory folder, one file per fact; memory never restates a rule.
markdown
# Rules for this repo
- Run only the tests that cover what you changed. The full suite belongs to CI.
- Before calling a third-party API, read its docs for sync/async and return type.
- Never pin a version from memory; look up the latest release and pin it.
- Delete old code in the same change. No shims, no "moved to X" comments.
Card 2
Nothing reaches a shared branch without the cheap checks
CI check plus branch protection: CI runs the full suite, the host requires it before merge, and only a commit whose run passed deploys.
Git pre-push hook: the cheapest checks, in seconds, before CI spends a run. A plain git hook binds people as well as agents. Keep it in scripts/pre-push and symlink it from .git/hooks/pre-push.
Rules file: during a session, run only the tests that cover the change; never skip the hook; each stage has a named bypass, and the agent says so openly when it uses one.
bash
#!/usr/bin/env bash
set -euo pipefail
[ "${SKIP_LINT:-}" = 1 ] || scripts/lint.sh --gate # seconds: zero findings tolerated
scripts/lint_incidents.sh # seconds: one small rule per past incident
# the full suite runs in CI; deploy only a commit whose run passed
Container or sandbox: give the agent read-only credentials for shared systems, so a read command is safe by construction.
Harness permission file: an allow list of read-only commands, written on purpose. Clicking "always allow" adds one exact command line at a time; one repo's list grew to 567 rules that way and still prompted.
Rules file: run allowed commands bare, with no sleep; or cd … && in front, so the pattern still matches.
text
Allowed without asking (read-only):
git status, diff, log, show
cluster reads: get, describe, logs
cloud reads: list, describe
Allowed without asking, though they run repo code:
the linter; the test runner on named files
Card 4
Anything that changes production stops for a person
CI: the production deploy job waits for a person's approval.
Branch protection: only a person pushes or merges to the branch that deploys to production.
Container or sandbox: production write credentials aren't in the agent's environment at all.
Harness permission file: an ask list, the same in every repo.
Rules file: each pre-authorization in plain words (what, who granted it, when, and what it still doesn't allow), plus a short list of what is never pre-authorized.
text
Always ask, in every repo, when the target names production:
delete, patch, apply, scale, set, restart, edit, create
Pre-authorized (granted by the engineer, Oct 18):
actions an admin can take in the product's own UI, called through
its API as a signed-in member, so role checks and audit apply.
Not covered: direct database writes, deleting customer data.
Branch protection on every branch that deploys anywhere.
Rules file: a branches-and-authority paragraph at the top of each repo's rules file, plus one workspace rule: never carry a branch or authority rule from one repo to another. The same "push to main" is routine in one repo and a production release in another.
markdown
## Branches and authority
- `main` deploys to production on push. Only a person pushes it.
- Feature branches: the lane commits and pushes freely; PRs merge with a merge commit.
- A push to a deploying branch starts CI and a deploy. Iterate locally.
Bootstrap prompt
This prompt carries out the five cards. Read the cards to know what good looks like, paste the prompt into your agent at the root of one repo, then check its gap report card by card. It works out which tool it is running in, maps the five cards onto that tool and your repo, and commits its changes on a new local branch for you to review. It never pushes, and never changes settings outside the repo, such as branch protection; it lists those for you.
text
Set up "week one" for running coding agents unattended in this repository.
Work through the steps in order. Nothing leaves this repo and nothing is
pushed.
1. Your harness. Name the agent tool you are running in and its version.
Find its documentation (built-in help, local docs, or the official site)
and quote the section that describes each of these, or say it has none:
a. the instructions file it loads at session start, and its scopes;
b. its permission or approval settings (allow, ask, deny);
c. any hooks it runs on events (session start, before a command).
State how its instruction scopes map onto three: private (mine, not
checked in), workspace (shared by every repo), repo (this one).
2. This repo. Find the languages, the test and lint commands, existing
git hooks, the CI config, which branches deploy where, any existing
rules or instructions file, and whether you run inside a container.
Name the file you learned each fact from. List checks that already
fail; don't fix them.
3. Questions. Put everything you could not find in ONE message to me:
which branches deploy to production and who may push each; which
names mean production (clusters, accounts, databases); the three
corrections I give agents most often. If nobody answers, continue on
stated assumptions and mark each one ASSUMED in the final report.
4. The cards. For each card, choose the strongest layer available here,
in this order unless the card names its own: git hook or CI check;
server-side branch protection; container or sandbox; your harness's
permission settings; the rules file. Name the layer and the file,
and propose the change as a diff.
Card 1: corrections live in a rules file the agent loads every
session, in the three scopes above; anything a script can
test moves to a hook or CI check instead.
Card 2: no push reaches a shared branch without the cheap checks:
a pre-push git hook that runs in seconds, the full suite in
CI, and a deploy only from a passing run. Each stage has a
named bypass that must be used openly.
Card 3: read-only commands run without asking, from an allow list
written on purpose. List commands that run repo code (tests,
linters) separately.
Card 4: anything that changes production stops for a person.
Strongest here: an approval step in CI, and production
credentials the agent doesn't hold.
Card 5: the rules file opens with a branches-and-authority
paragraph: who commits, who pushes which branch, where each
branch deploys.
5. Write the files on a new local branch, inside this repo only, and
commit. If nobody answers, that commit is your proposal; I review it
there. Never push or merge. Run the pre-push hook once by feeding it
the refs it would see on a push; never push to trigger it. Show its
output. For anything outside the repo (branch protection, CI
approvals, credentials, files in the private or workspace scope),
write the exact steps for me instead.
6. End with a gap report, one row per card: card, layer used, file,
what is still enforced only by the rules file or not at all, and
every ASSUMED item.
Checklist
0 of 5 done
Ticks stay in this browser only.
Ready for week two when
A push with a deliberate lint error is refused by the hook, and the same change on a pull request fails CI.
The agent works a full session without asking you to approve a read-only command.
A command aimed at production stops and asks, every time you try one.
Your last three corrections are in the rules file, and you didn't have to repeat them.