/agent-architecture

name: agent-architecture
description: 'Design AI agent architectures through requirements discovery, or audit and diagnose architectural flaws in existing agents. Architecture only; excludes implementation and general code review.'
license: MIT

AI Agent Architecture

Help the user obtain a justified architecture for their task or an evidence-based audit of an existing agent. Deliver architectural decisions and ways to verify them, without implementing the agent. By default, completed work includes a PDF report and a visualization of the results. An “ideal architecture” fits the requirements, cost of failure, and team resources; it does not maximize the number of components.

Choose a route

| Request | Route | Read | |---|---|---| | New agent, requirements are not yet clear | Design: working cases → early design → requirements and decision coverage → delivery | [design.md](references/design.md), [architecture-contract.md](references/architecture-contract.md) | | Architecture from an existing specification | Design: fill in what is known and clarify only gaps | The same files; do not restart the interview | | Review an agent already written | Audit: reconstruct actual paths → verify → deliver findings | [audit.md](references/audit.md), and [architecture-contract.md](references/architecture-contract.md) as criteria | | Agent makes mistakes, has degraded, or falsely reports “done” | Diagnosis within the audit: case → hypotheses → discriminating checks → correction and closure criterion | audit.md and [diagnostic-review.md](references/diagnostic-review.md) | | Review and redesign | Audit first; its demonstrated problems become design inputs | audit.md first, then design.md |

In either mode, read [source-map.md](references/source-map.md) once: it explains the origins of the principles and the textbook's limitations. The original PDF is not needed for ordinary skill use. [scenarios.md](references/scenarios.md) is needed only to test the skill itself.

When choosing or revisiting the execution approach, use [architecture-selection.md](references/architecture-selection.md); when designing acceptance or reviewing quality claims, use [evaluation-design.md](references/evaluation-design.md). Develop the validation loop and completion evidence using [validation-loop.md](references/validation-loop.md); for long-running/background work, pauses, recovery, and competing sessions, use [execution-continuity.md](references/execution-continuity.md), including storage, RTO/RPO, budgets, the human decision queue, and scheduling. Develop delegation, mutable memory, execution isolation, and long-running/streaming interaction only when the task has these properties. A section's existence does not make its question mandatory: material gaps under discovery-protocol.md determine depth.

Shared decision rules

• First read the available specification, local instructions, architectural decisions, and relevant materials. Use code to reconstruct architecture, not to make unsolicited fixes. Do not run an application with external effects for an audit.
• Maintain a brief register: **source-confirmed / user requirement / proposal / assumption / open question / not applicable**. Identify where requirements came from. A user decision and an architect's hypothesis have different statuses.
• Corporate contracts and accepted decisions apply only within their own project. The textbook is an engineering reference, not a source of authority or a replacement for local canon. Identify conflicts rather than resolving them silently.
• First consider ordinary automation without an LLM, a single call, and a predefined workflow. Introduce an agent loop, RAG, persistent memory, MCP, or multiple agents only for a concrete need. For each added complexity, identify its benefit, cost, verification method, and simpler alternative.
• Do not select a model or framework before understanding the task. For a concrete selection, check current official documentation and version constraints. A documented capability is not yet demonstrated quality on the user's data.
• Separate probabilistic model decisions from programmatically enforced rules. Describe where permissions, parameters, budget, and action admissibility are checked **before** an external effect, including bypass paths and resumption.
• For a timed-out external write, a readback that finds nothing does not by itself prove that no effect occurred. Permit a retry only under an established downstream idempotency contract or authoritative proof of non-execution; otherwise retain `effect unknown` and reconcile or escalate. Apply this rule in concrete flows and examples as well as in the risk section.
• An audit or design does not authorize writing code, changing agent settings, publishing, or initiating external actions. On a subsequent explicit implementation request, hand the architecture to the appropriate process; this skill does not continue into implementation itself.

How to work

Before an interview or audit planning, read [discovery-protocol.md](references/discovery-protocol.md). Show a clear route and maintain a coverage map. By default, devote each turn to one decision or working episode; do not hide several independent topics inside one question. Material gaps and evidence determine depth. There is no fixed total round limit.

Deliver the first useful design as soon as context is sufficient, otherwise no later than the third answer; the count does not reset on continuation. This limits the wait for an early result, not the completeness of the interview. If the task is too unclear, show a map of what is understood and conditional options. After the sketch, continue investigating material gaps under the protocol; two or three rounds alone do not justify declaring readiness.

The first design includes the goal and boundaries, main capabilities and their outputs, recommended components, main flow and external actions, key constraints, assumptions, and open decisions.