What Makes Agent Workflows Worth Documenting

The default state of an agent workflow is invisible. It lives in a script, in a notebook, in a prompt someone wrote once and kept copy-pasting. It works, occasionally. It is not written down. When the person who wrote it moves on, the workflow is gone, and the next person writes a worse version of it from scratch.

The reason to document an agent workflow is not to brag about using agents. It is to make the workflow reusable — by other people, by your future self, and by the next agent that has to interoperate with it.

Three things make a workflow worth writing down:

1. A narrow job. “Summarise the pending drops and propose tags” is worth documenting. “Help me with my work” is not.
2. A clear contract. What it reads, what it writes, what it is allowed to decide on its own, and what it must hand back for confirmation.
3. A failure mode. What it does when it is wrong, and how that is caught. Workflows without a described failure mode are workflows that fail silently.

Hermes is built around these three. Each agent has a narrow job, a contract written in files, and a failure mode that falls back to “propose, do not persist.” The documentation is the system, not a description of the system.