AGENTS.md: scratch space, refusals, one todo at a time, gate timeout, commit -F

From the combined Ornith guidance (~/projects/ornith/GUIDANCE.md, §4):
experiments go under the ignored .state/scratch/, never /tmp (which
reconciles I16 with crossbar's in-repo experiments); a refused tool call
does not end the turn; todo!() bodies are filled one at a time with
cargo check between; the gate runs with a 600000 ms shell timeout;
Cargo.lock is staged when it changed; commit messages are written to a
file and committed with -F, since quotes broke -m in crossbar.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-09-26 00:15:36 -07:00
co-authored by Claude Opus 5.5
parent f98ec2a908
commit 0356c877dd
+14 -3
View File
@@ -19,6 +19,9 @@ Unix sockets. You are implementing it one task at a time.
5. Work only from files inside this repository. Never read another checkout or worktree (such as
`~/src/boxmaker-ref`), and never search the file system for code (`find /`, `locate`). If you
are stuck, stop as in point 4; copying code from elsewhere is not finishing the task.
To try something out (a small program, a script, a copy of a file), work under
`.state/scratch/`, which git ignores, and delete it before you commit. Never use `/tmp` or any
other directory outside the repository.
6. If you hand a task to another agent, tell it to read `AGENTS.md` and the task file itself. Do
not pass on your own summary of either. Log what the agent did, as it did it.
@@ -63,6 +66,9 @@ These come from defects found in review. The evidence is in `docs/implementer-le
- Report every problem you find, not only the first.
- Log every attempt, including one you abandon.
- Never end a turn by describing what you are about to do. Do it, then report.
- A refused or failed tool call is not a reason to end your turn. Read the error, then continue
with another tool call.
- Fill `todo!()` bodies one at a time, and run `cargo check` after each.
- If a tool you were told to use does not exist, stop and say so. Do not invent a command in its
place.
- A `read` returns as soon as it has any data to give and blocks only when it has none.
@@ -79,12 +85,14 @@ These come from defects found in review. The evidence is in `docs/implementer-le
tokens when you read it.
- When a test outside your task fails, check once whether it fails without your change, then stop
and report both results. Do not keep experimenting, and never add a file the task does not list,
not even a temporary one.
outside `.state/scratch/`.
- Write your log row from `git diff` after staging, naming only what the diff shows.
## The gate
`make gate` must print `gate: ok` before a task is done. It runs offline: rustfmt, clippy with
`make gate` must print `gate: ok` before a task is done. Run it with a shell timeout of 600000 ms:
it takes longer than the default 2 minutes, and a gate cut off by the timeout is not a failure of
your code. It runs offline: rustfmt, clippy with
warnings denied, all tests, cargo-deny, and the scripts in `scripts/`. Run `cargo fmt --all` before
the gate; rustfmt decides the order of `mod` and `use` lines, not you. After you add a dependency,
run `cargo build` once so that `Cargo.lock` is updated, then run the gate.
@@ -95,12 +103,15 @@ Useful while working: `cargo test -p <crate> --test <file>` runs one test file,
## Git
- Work on the branch the task names. One task is one commit.
- Stage only the paths the task lists: `git add <path> ...`. Never `git add -A` or `git add .`.
- Stage only the paths the task lists, plus `Cargo.lock` if it changed: `git add <path> ...`.
Never `git add -A` or `git add .`.
- Never push, amend, rebase, reset, or switch to another branch.
- Commit message: the subject line the task gives, a blank line, then the `Co-Authored-By` line
your session prompt gives, exactly, for example
`Co-Authored-By: ornith-1.5-35b-a3b <agent@wntrmute.dev>`. If the prompt gives none, stop and
report.
- Write the message to `.state/commit-msg.txt` and commit with `git commit -F
.state/commit-msg.txt`, never with `-m`: quotes and apostrophes in a message break `-m`.
## The implementer log