# Agent Supervision Field Notes

> Nine guardrails for supervising coding agents, attached to the failures that produced them and grouped by the system boundary where they apply.

This is a public, static account of how one solo builder supervises coding agents with firstmate. The Markdown, structured JSON, and human-readable sections come from the same build data; README.md remains canonical for the nine practices.

## Core

- [Field notes (Markdown)](https://fieldnotes.clayj.app/field-notes.md): Complete prose and all nine failure records.
- [Guardrails (JSON)](https://fieldnotes.clayj.app/guardrails.json): Structured flow, supervision claims, and guardrails with stable ids.
- [Human-readable site](https://fieldnotes.clayj.app/): The visual field notes and interactive failure walkthrough.

## Sections

- [A day at the helm](https://fieldnotes.clayj.app/#attention): One dated count of closed Toolroll records, distinct captain replies, and a customer-message decision that reached the builder.
- [The supervision loop](https://fieldnotes.clayj.app/#loop): Dispatch, work, review, validation, landing, and teardown.
- [Every worker gets a separate world.](https://fieldnotes.clayj.app/#dispatch): Tasks begin in separate copies of the repository. Worker state is durable on disk, so a crash, restart, or closed laptop does not erase what happened.
- [Questions go up. Work waits.](https://fieldnotes.clayj.app/#work): A worker can act inside its authority. A question above that boundary becomes a durable stopping state routed to the supervisor.
- [Models check each other.](https://fieldnotes.clayj.app/#review): Firstmate can run Claude, Codex, Cursor, Grok, OpenCode, Pi, Kimi, and Muse. The useful part is not the list. Review goes to a different model family, and work routes across providers with remaining quota.
- [Green is a request for proof.](https://fieldnotes.clayj.app/#validate): The validation pipeline can refuse a merge. A test has to demonstrate that it can fail, and a merge is never reported as landed without evidence from the repository.
- [Teardown gets one chance to be right.](https://fieldnotes.clayj.app/#teardown): Cleanup refuses to proceed when saved work or current ownership cannot be proved. A safety refusal is a result, not an invitation to keep retrying.
- [Landing proof](https://fieldnotes.clayj.app/#land): The evidence boundary between green checks and landed work.

## Optional

- [Limits](https://fieldnotes.clayj.app/#limits): What these controls do not prove.

## Authorship

Written by Clayton Johnson while building [Toolroll](https://toolroll.clayj.app), a snippet vault for iPhone and iPad. Every failure recorded here happened there. [clay@clayj.app](mailto:clay@clayj.app)