Agent Architecture Lens

Use this skill to review how an agent's control flow, state, and failure handling are structured. The ReAct loop — reason, act, observe, repeat — is the atom of every agent, and it is correct. It is also incomplete: as runs get longer and messier it does not break in one dramatic failure, it quietly stops being enough.

A loop is a graph with one node and one edge pointing back at itself. The governing principle is architecture follows the shape and duration of the task — never the elegance of the diagram.

Two leitwörter anchor every pass. A graph is not an upgrade: structure is a response to a requirement you actually hit, so a task with no such requirement keeps its loop and the review says so. The ledger, not the transcript: progress that must survive anything lives in a durable artifact, never in the message history the model is hoping to remember. State both by name as you review.

First pass: the six signals

Before recommending any structure, state which of the six signals fire, by number:

1. State exceeds one context window. The run tracks more than fits in the model's working memory.
2. The run must survive crashes. Losing it mid-execution is unacceptable — minutes of work, real API spend, a waiting user.
3. Human approval is required mid-run. A person must review before the agent continues, and they may take hours.
4. The workflow has parallel branches. Genuinely independent subtasks that should not be serialized.
5. Multiple models or agents must coordinate. Different steps need different models, tools, or permissions.
6. Execution must be replayable and auditable. Someone will ask "what exactly happened in this run?" after the fact.