Design Agentic Architecture

Agentic complexity is a cost you pay down, not a default you start with. This skill turns a use case into a design document by climbing the ladder on evidence — adding structure only when a need forces it — on a foundation of durable state, wiring in memory, human-in-the-loop, and observability only where each earns its place.

The architecture rules are research-backed as of mid-2026 and live in PRINCIPLES.md — consult it as you design. Tools are checked live (step 7) because they age fast; never recommend them from memory. The output follows DESIGN-DOC-TEMPLATE.md.

Work the steps in order. Each ends on a completion criterion — do not advance until it is met.

1. Pin the use case

Capture the goal (one sentence), every action the agent can take (read vs. write/irreversible), the risk profile (irreversibility, blast radius, compliance), expected scale, latency/cost sensitivity, and the pricing regime (metered API vs. flat subscription — it sets how hard the cost arm pulls, and so how aggressively to optimize before climbing). If the goal is vague, interview the user before designing — a fuzzy use case yields an abstract, useless design.

Done when: you can state the goal in one sentence, have listed every action tagged read or write, and have captured the risk profile, expected scale, latency/cost sensitivity, and pricing regime.

2. Climb the ladder on evidence

Start at rung 1 (single agent + typed, validated tools). Add a rung only for an unmet need: correctness → reflection (a separate critic), structure → bounded planning, adaptivity → ReAct, hard org boundaries → multi-agent. Pick the lowest rung that meets the need. Before climbing, exhaust single-agent optimization — prompting, retrieval, caching, context engineering (curate/compact/offload), model upgrade; a window that is overflowing or rotting is a signal to fix the context first, not to add a rung. Multi-agent is the last resort (4–220× tokens, handoff latency, hard debugging) and only for boundaries — never for parallelism alone. If multi-agent, enforce the single-writer rule: one coordinator owns the plan and all writes; sub-agents return intelligence and full traces, not actions.

Done when: the chosen rung is named with the specific need that justifies it (or rung 1 is justified as sufficient), and single-agent optimization — including context engineering — has been exhausted before any climb.