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 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 `~/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. 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 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. 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. - Report every problem you find, not only the first.
- Log every attempt, including one you abandon. - Log every attempt, including one you abandon.
- Never end a turn by describing what you are about to do. Do it, then report. - 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 - If a tool you were told to use does not exist, stop and say so. Do not invent a command in its
place. place.
- A `read` returns as soon as it has any data to give and blocks only when it has none. - 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. tokens when you read it.
- When a test outside your task fails, check once whether it fails without your change, then stop - 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, 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. - Write your log row from `git diff` after staging, naming only what the diff shows.
## The gate ## 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 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, 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. 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 ## Git
- Work on the branch the task names. One task is one commit. - 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. - 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 - Commit message: the subject line the task gives, a blank line, then the `Co-Authored-By` line
your session prompt gives, exactly, for example 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 `Co-Authored-By: ornith-1.5-35b-a3b <agent@wntrmute.dev>`. If the prompt gives none, stop and
report. 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 ## The implementer log