The Agent Loop Is the Easy Part: Designing the Workbench
The repository’s agent section takes the control-flow decision from the previous checkpoint seriously: an agent is useful only when the task needs adaptation. The next question is what must surround that loop so adaptation becomes reliable repository work. This chapter examines the workbench surfaces that carry instructions, scope, state, feedback, verification, review, and handoff. The practical result is a way to tell a capable model from a system that can work across files, turns, and sessions without declaring its own success.
A prompt-only run can look convincing. A model may open several files, write plausible code, and report that a change is complete. The tests may fail. The diff may include unrelated files. No one may know which assumptions guided the work or what should happen when the session ends. The repository frames this as a workbench failure, not simply a model failure. The model produces actions, but the workbench determines how those actions are bounded, recorded, checked, and resumed.
The loop needs more than a tool registry
An agent loop has a clear operational shape. A message buffer carries the task, prior responses, tool calls, and observations. A tool registry maps a selected name to a real capability. A stop condition ends the loop when the model finishes, no tool call is emitted, a guardrail trips, or a budget is exhausted. A turn budget limits the damage from repetition. An observation formatter turns tool output into an input the model can interpret.
Each ingredient has a failure path. A message buffer can preserve a mistaken assumption and amplify it across turns. A tool registry can expose a capability whose side effects are broader than the task requires. A stop condition can be too weak, allowing an endless loop, or too eager, allowing early completion. A turn budget can prevent runaway cost while still cutting off a task that needs one more diagnostic step. An observation formatter can hide the error line that would have changed the next decision.
These parts make an agent loop executable, but they do not make a repository task accountable. The loop knows what happened in its current trajectory. It does not necessarily know which files it was allowed to change, whether its state will survive a crash, whether a command actually ran, whether the final diff matches the goal, or what the next session should do. Those responsibilities belong to the workbench.
The repository’s workbench lesson names seven surfaces: instructions, durable state, scope, feedback, verification, review, and handoff. They are not seven documents to collect. They are seven responsibilities that answer different questions about work:
- What rules and acceptance conditions apply before action?
- What state must survive the current conversation?
- Which files, operations, and approvals are inside the task?
- What did the runtime actually return?
- What deterministic checks decide whether the task is complete?
- Which qualitative questions require a separate review?
- What should the next person or session load first?
A workbench is reliable when these answers are connected without being collapsed into one instruction block.
State belongs in a durable system of record
The repository’s state lesson starts with an ordinary problem: chat history is volatile, while repository work persists. If the next session has to reconstruct progress from a transcript, it may repeat completed work, miss a known failure, or edit a file that was deliberately left unchanged.