agentic-patterns

Imported from AdamKrysztopa/architectural-decisions (build/codex/skills/agentic-patterns/SKILL.md). Install upstream with npx skills add AdamKrysztopa/architectural-decisions --skill agentic-patterns. Copyright stays with the author.

agentic-patterns : design the simplest agent that meets the requirement, or audit the one you have

The single most important principle in agentic design: the best agentic system is the simplest one that meets the requirement. Start at the bottom of the autonomy spectrum — a single well-prompted call — and climb to a workflow, then a single agent, then multiple agents only when the level below demonstrably can't do the job. Every loop, hand-off, and extra call multiplies cost, latency, and failure modes; each must earn its keep. Most agentic failures in the wild are not a missing exotic pattern — they're an over-built system, or a basic missing guard (no step budget, no human gate, no tracing).

Agentic patterns compose into layers (like an architecture stack, not a single pick): a reasoning loop on Tool Use, optionally inside a topology, with memory, reliability, governance, and an integration seam.

Knowledge lives in two references you read on demand:

• references/decision-tree.md — the layered design interview, bottom of the autonomy spectrum up.
• references/catalog.md — every pattern (when / cost / review cue) and the nine-point checklist (seven over-building defects, one under-building check, one stale-scaffold check) to check existing agent code against.

Neither reference covers evidence: for scaffold tests and semantic evals — what to assert about the deterministic wiring and what to evaluate about the model's output — hand off to arch-crew:test-patterns, which owns that decision tree.

Step 0 — Establish where the user is

Branch on greenfield or refactoring? Designing a new agentic system, or assessing one that exists (code, a running agent, a described setup)?

The request usually tells you: "how should I build…" / "I want an agent that…" = greenfield; "review my agent" / "is our multi-agent setup right?" / a repo to read = refactoring. Ask only if ambiguous.

Also detect whether autonomy is an open question or a fixed constraint. "Should this be an agent?" is open — run the autonomy gate. But "I've committed to an agent (a product decision, an org standard, a capability I'm building to learn) — help me build it well" is fixed: acknowledge the constraint, name the cost once, and proceed to the design layers. Don't relitigate Q1 every turn when the user has already closed it — in real work they've often already decided and want the layered design, not a re-argument of whether to build at all.

The system under discussion may not be this repository. A third branch sits beside greenfield and refactoring: the user describes a system that is not the code you can read — another team's service, a product they are evaluating, an architecture on a whiteboard, or a repository you have no access to. Reason about the system they describe, and say plainly which claims rest on their description rather than on something you read. Do not substitute this repository for the one they meant, and do not refuse the question because the code is absent — an absent codebase makes conclusions provisional, not impossible. Where a step here calls for reading code, say what you would look for and what it would change.

What "finding" means in this skill's output

A finding is a specific, actionable conclusion — what's wrong, where, why it matters, and the fix — never a bare impression, and never a substitute for a tool's own verified result (a violation, reported on its own).

Mode A — Greenfield: the layered design interview

Read references/decision-tree.md and walk it from the autonomy gate up.

1. Push down the spectrum first — but the gate cuts both ways. Genuinely test whether a single call or a workflow suffices before recommending an agent — this is the highest-leverage thing the skill does, and the honest answer is often "you don't need an agent." Don't over-correct, though: autonomy is genuinely required — say so as readily as "no agent" — when the model must choose the next action at runtime, when retrieval is adaptive (deciding whether/what/how-many-times to fetch and re-querying on weak evidence — that's agentic RAG, not preprocessing), when a step needs an observation that doesn't exist until an earlier step runs, or when the path space is too large to hardcode. Demote to "no agent" only when none of those hold. Don't skip the gate to get to the fun part — and don't force a genuinely open task into a rigid pipeline either.
2. Walk the layers in order, skipping branches that don't apply (workflow designs skip the agent-only layers; single-agent designs skip topology; a single call goes straight to governance and the input boundary). Ask one layer at a time.
3. Compose the design — stack the selected layers, each naming its pattern and the one-line reason it's there, with the cost from references/catalog.md.
4. Add the baseline and surface the standing notes. Every design gets tracing and, if shipped, offline evaluation; every agent design gets a step budget. Then the notes the active branches trigger: cap loops + early-exit, compaction for long loops, durable execution for runs that must survive a restart, single-agent-first, HITL for irreversible actions, guardrails on untrusted input.

Output — a "Your agentic design" the user can build from:

## Your agentic design

| Layer | Pattern | Why it's here | Watch out for |
|-------|---------|---------------|---------------|
| Autonomy | <single call / workflow / agent> | ... | ... |
| Reasoning loop | <ReAct / Plan-and-Execute / Reflection> (+ Tool Use) | ... | ... |
| ...only the layers that apply... |

**Baseline and guardrails from day one:** <tracing and offline evaluation always; step budget for
any agent; loop caps, HITL gates, input/output/tool guardrails — per the active branches.>

**The least-autonomy check:** <one or two sentences confirming nothing here is more autonomous than
the task requires — or flagging a layer to drop.>

If the autonomy gate already answered "no agent" or "a workflow", don't force the table. That outcome is the recommendation — and it's the most valuable one this skill gives. Say plainly what to build instead (a single well-prompted call, optionally with retrieval; or the one workflow shape and its guardrails), why it's sufficient, and the single signal that would later justify climbing the spectrum. It still gets the baseline (tracing, offline evaluation) and, where they apply, HITL for irreversible actions and guardrails on untrusted input. Two honest lines beat a padded multi-layer design for a problem that didn't need one.

Mode B — Refactoring: agent-system review

The deliverable favours subtracting autonomy and adding guardrails over adding machinery. A huge fraction of real agent problems are fixed by removing agents, not adding them — but the other tail is real too: occasionally a workflow or single call is silently doing an agent's job badly (most often an under-built retrieval pipeline that can't re-query). Weigh both directions; don't only ever subtract.

1. Map the current design. From the code or description, name each layer: autonomy level, reasoning loop, single vs. multi, memory, reliability, governance, integration.
2. Run the nine-point checklist from references/catalog.md — seven over-building defects, one under-building check, and one stale-scaffold check: (1) agent where a workflow/call would do, (2) multi-agent where one agent would do, (3) loops without a step budget + early-exit, (4) unvalidated tool outputs, (5) no durable memory when runs outlive the context window, (6) ungated irreversible actions, (7) no tracing, (8) — the other direction — a workflow/single call silently doing an agent's job badly (e.g. hardcoded retrieval that can't re-query), and (9) a scaffold (context resets, sprint splits, evaluators) not re-tested since the last model upgrade. Most findings live in (1)–(7); (8) keeps the review honest. The checklist is a lens, not a form to fill: many real systems are a workflow or a workflow-of-single-calls (e.g. a LangGraph StateGraph with fixed edges), so translate each defect to what the system actually is rather than scoring it as if it were an autonomous agent — and if you find a genuine issue that none of the nine name (a dead tool, a disabled checkpointer, an unbuilt "agent" that's really a stub), report it anyway. Also handle the pre-build case: if the agentic layer is only designed-on-paper / stubbed, review the intended design and flag the defects to preempt before they're written.
3. Recommend conservatively. Prefer collapsing a multi-agent design to one good agent, or a workflow to a single call, over adding a new pattern. Add only the guardrails the system actually lacks.

Output:

## Agentic system review

**Current design:** Autonomy: <…> · Loop: <…> · Agents: <…> · Memory: <…> · Governance: <…>

### Findings
1. **<defect>** — <where, file ref> · Impact: <cost/latency/risk> · Fix: <pattern to add, or
   autonomy to remove> · First step: <smallest safe change>
2. ...

**Simplify:** <agents/loops to collapse or remove.>
**Sound as-is:** <parts that are already right.>

Recording the outcome (write the file)

A design that lives only in a chat transcript is lost. Persist it.

Greenfield → one decision file. After presenting the design, follow references/recording-decisions.md: read the constitution first, then write a single status: proposed decision file — no separate ADR file. Its prose is the ADR:

# <decision title, e.g. "Single ReAct agent with HITL gates for the support bot">

## Context
<the task and its forces — what the system must do, the autonomy genuinely required, the stakes /
latency / cost constraints that drove each layer.>

## Decision
<the composed design: the layer · pattern · why table you just presented>

## Consequences (cost)
<the cost/watch-out for each layer, the guardrails included from day one (step budgets, loop caps,
HITL, tracing), and the least-autonomy caveat: what was deliberately *not* built and the signal
that would justify climbing the spectrum.>

Classify every rule honestly (default narrative) and regenerate the constitution.

Refactoring → a review report. Write the review to docs/agentic-review-<YYYY-MM-DD>.md (create docs/ if absent — Current design + Findings from the nine-point checklist + Simplify / Sound-as-is). If the system is already sound, say so plainly and keep the report short — a clean bill of health is a valid, useful outcome, not a failure to find work. If a finding is a direction the user commits to, capture it the same way — one decision file, following references/recording-decisions.md.

Write the file(s) and report the path(s). Ask first only if the repo layout is unclear or the user is clearly still just exploring rather than deciding.

Asked instead to consolidate existing ADRs into this schema, or to propose a baseline for a codebase that has none? Read references/migrating-decisions.md and follow it.

Why this shape

The autonomy gate leads on purpose: the costliest agentic mistakes are made before any pattern is chosen, by reaching for an agent (or a swarm) when something simpler and more reliable would serve. Naming the cost beside every layer, and leading review mode with the nine-point checklist, keeps the focus where real failures happen — over-engineering and missing guardrails — rather than on collecting exotic patterns.

Read-only mode

Present the complete recommendation without creating or modifying repository files whenever writing is off the table. Two different things put it off the table, and both count:

• The user asks for it. "Review only", "don't change anything", "dry run", "just tell me", or an explicitly read-only target.
• The environment imposes it. You have no write access, the repository is not checked out, the session is sandboxed or read-only, the system under discussion is not this repository, or a tool call to write has already been refused. An environment-imposed constraint is not a reason to ask the user for permission you already know you do not have, and it is not a reason to skip the recommendation — produce the whole thing, and say once at the end that the artifact was not written and where it would have gone.

Otherwise persist the outcome. Do not ask for confirmation when repository context is sufficient to proceed.

Record the decision

Covered above: every greenfield recommendation — including an explicit refusal — and every review finding the user commits to is persisted as the one decision file described in "Recording the outcome." A review otherwise writes only its report. Do not record when the run only answered a question without recommending anything.

Notice drift later

At a checkpoint — before a commit, or when a session start notice says edits are queued — drain the observations and classify them: references/observing-drift.md. Report a violation only where a tool actually failed.