A good agent runbook status file tells a human or parent agent whether detached work is starting, running, done, or blocked, and what artifact proves it. It is not a journal. It is the minimum state needed to resume safely.
Quick answer
- Write the status file before going quiet.
- Name the current phase and attempt.
- Record expected artifacts and validation conditions.
- Use terminal states: done or blocked.
- Never resume a timed-out attempt in the same mutable path.
The file exists for handoff
Long-running agent work often crosses a boundary: a chat turn ends, a task times out, or a parent agent needs to validate the result. The status file is the handoff artifact. If it cannot answer what is running and how success will be checked, it is not doing its job.
Use a small schema
- state
- updatedAt
- phase
- attempt
- summary
- expectedArtifacts
- checks
- nextStep
Keep it boring. The goal is reliable recovery, not a second project-management system.
Terminal state comes before polish
Once the required artifacts and checks pass, write done before optional notes or cleanup. If the work is blocked, write blocked with the exact next action. Half-finished status files create expensive ambiguity.
Frequently asked questions
Should a status file replace task history?
No. It complements the task ledger with repo-specific artifacts, checks, and resume instructions.
Where should status files live?
Use a run folder or /tmp path for operational state. Durable plans and research should live in the repository.
What is the biggest mistake?
Creating the path after the long task starts, then going quiet before anyone can verify it exists.