| name | agentic-architecture |
| description | Explain an existing agentic system — a codebase where an AI agent is the central "CPU" surrounded by agent-native organs (reasoning loop, memory, context, tools, skills, MCP, subagents, hooks) — or design one from requirements. Covers agent runtimes/harnesses and capability/steering packs. Use when the user invokes it by name (`agentic-architecture`) or near-match. |
| metadata | {"version":"2026-07-15"} |
Agentic Architecture
One lens, two directions. Produce a single document mapping an agentic system as the core
plus its surround — not just packages and classes.
The core reframe (the thesis)
A conventional codebase runs deterministic control flow. An agentic system puts a
non-deterministic LLM at the center as the "CPU," and everything else is agent-native
scaffolding wired around that core:
┌──────────── THE CORE (the agent) ─────────────┐
BRAIN │ model/provider layer · system prompt · │
│ reasoning LOOP (ReAct / plan-execute / graph)│
└───────────────────────────────────────────────┘
CONTEXT context window · compaction/summarization · memory (working ↔ persistent)
CAPABILITY tools (registry→dispatch→exec) · skills · MCP (external tools/resources)
ORCHESTRATION subagents (spawn/isolate/merge) · hooks·triggers·scheduling ·
permissions/guardrails/HITL · session/state/event bus
A generic architecture pass would describe the repo as "a monorepo with packages" and never
surface the loop, memory, and MCP as first-class organs — that is the gap this skill fills.
Where a sibling skill judges the outward surface an agent drives (ax-interface),
this skill maps the inward anatomy.
Mode: explain or design
Infer the mode from repo state and the prompt's verb; ask when ambiguous.
- Explain — reverse-engineer what exists. Evidence = the repo's real source and
authored content: real file paths, function, class, tool, and skill names. Never invent
an organ — the failure mode is confabulation. Unverifiable → "Open Questions".
Output:
_docs/<system_name>_agentic_architecture.md (snake_case project name; create
_docs/ if missing).
- Design — compile the user's inputs (PRD, rough design, this conversation) into the
same document shape. Evidence = those inputs only. In this mode every organ is a
decision: needed / not needed / undecided — don't silently settle the undecided ones;
they go to "Decisions needed".
Output:
docs/design/<nn>-agentic-architecture.md (next free number) unless the user names
a path.
Core principles
- Ground every claim in the mode's evidence (above). When unsure, say so in the
uncertainty section rather than guessing.
- Significance over completeness. Cover the architecturally significant organs; skip
generated code, vendored deps, and delivery-surface boilerplate — unless they reveal
how the agent is wired. An organ often lives in the surface (permission/HITL gates in
the interactive or RPC mode, not the core loop): follow the organ, don't skip the file
because of where it sits.
- Classify first, then adapt depth. The system type drives what the document
emphasizes and whether an organ is code or authored content.
- Absence is a finding. A missing organ (no MCP, no persistent memory, no compaction)
is informative — record it in the organ matrix, don't silently omit it. (Design mode:
absence is a decision — record why.)
- One file. Always a single Markdown file. Do not split.
Classify the system
The type decides where each organ lives — implemented in source, or authored as content.
- A. Capability / steering pack (content for a BYO harness): organs appear as
authored files —
SKILL.md, AGENTS.md/CLAUDE.md, slash-command .md, subagent
defs, hook scripts, MCP config. No loop / dispatch / token machinery; it installs INTO
a harness.
- B. Agent runtime / harness (the engine itself, in source): organs appear as source
subsystems — a real loop calling an LLM until a stop reason, tool registry + dispatch,
provider layer, memory store, compaction, subagent orchestration. It IS the harness that
loads packs.
- C. Embedded / hybrid — an application with an agent inside it, and/or a repo that
both implements agent infra AND ships agent-native content. Cover both angles.
Disambiguation trap: a Runtime repo almost always also carries Pack-style dotfiles
(.claude/, AGENTS.md, .mcp.json) for its own development. Judge by src/, not
the dotfiles — if the loop/dispatch machinery lives in source, it is a Runtime (B).
State the classification and its evidence early in the doc.
Exploration order by type (explain mode): Runtime → find the loop first — it is the
heart; everything else hangs off it. Pack → inventory the primitives first — enumerate
skills/commands/subagents/hooks and which harness(es) they target. Then walk the organ
checklist, and trace one representative agent turn end to end:
prompt → model → tool_use → dispatch → result → re-reason → … (Runtime); or
trigger → skill loaded → instructions steer the harness → effect (Pack).
The agentic anatomy (the organ checklist)
Locate (or, in design mode, decide) each organ. For each: where it lives, how it's
provided, and present / partial / absent / n·a. "How it's provided" has three values,
not two: core code (baked into the engine), authored content (a SKILL.md/prompt/
config the harness loads), or extension-provided (supplied through a plugin/extension
seam rather than core). Extension-provided is common in mature harnesses; mark it
⚠️ partial and name the seam.
| Cluster | Organ | What it is | Where to look |
|---|
| Brain | Reasoning loop | control flow driving the model until a stop reason (ReAct / plan-execute / graph) | the loop function; LangGraph assembly; while+tool_use |
| Model / provider layer | the LLM substrate; multi-provider normalization | providers/, provider SDK calls, model registry |
| System prompt / constitution | the durable instructions defining the agent | system-prompt, AGENTS.md, prompt templates |
| Context | Context window mgmt | how the transcript is assembled for each call | message-building at the LLM boundary |
| Compaction / summarization | trimming when the window fills | compact, summariz, transcript-limits |
| Memory | working (in-context) ↔ persistent store; budget/eviction | memory, store, backends/, checkpoint |
| Capability | Tools | registry → dispatch → execution backend | tools/, tool-registry, _tools.py, exec/VFS/shell |
| Skills | loadable instruction capabilities | SKILL.md, skills loader |
| MCP | external tools/resources/prompts protocol | mcp/, MCP client, .mcp.json |
| Orchestration | Subagents | spawn / isolate / merge child agents | subagent, spawn, orchestrator, Task( |
| Hooks · triggers · scheduling | event-driven / autonomous runs | hooks/, cron, scheduler |
| Permissions / guardrails / HITL | safety gates, human-in-the-loop, least privilege | permission, approve, confirmation gates |
| Session / state / event bus | conversation state, streaming to surfaces | session, event-bus, state, checkpointer |
When you find the loop, capture its distinctive control shape, not just a generic turn:
single or nested (inner tool-call loop + outer follow-up loop)? Does it inject
steering/interrupt messages mid-run? Where is the one boundary that converts internal
messages to the provider wire format? These specifics are the most illuminating part of a
Runtime — the generic "call model → run tool → repeat" is table stakes.
Emphasis by type: Runtime → trace the code subsystems (loop first). Pack → most
organs are authored files; emphasize the primitive inventory, install/registry glue, target
harness(es), and multi-harness variants. Hybrid → cover both, and say where the agent
sits in the product.
Write the document
Cross-link: check the output directory for related docs and add a "See also" line under
the title for each — match on topic, not just filename suffix (a hand-named
ARCHITECTURE.md counts as the structure doc). Canonical siblings: system-architecture
(generic structure), ax-interface output (the agent-facing surface, judged),
surface-architecture / data-architecture (the outside / the data).
Use this skeleton. Keep prose tight; let the diagrams carry the structure.
# <Project> — Agentic Architecture
> Source: <repo origin/URL or design inputs> · Date: <date> · Mode: <Explain | Design> · Type: <Pack | Runtime | Hybrid>
> See also: [System & OOP Architecture](<sibling>) · [AX Analysis](<sibling>) <!-- omit lines for docs not present -->
## 1. Overview
- One-paragraph purpose: what this agentic system does.
- Type classification (Pack / Runtime / Hybrid) and the evidence — cite `src/` vs dotfiles.
- Substrate: language(s), agent framework(s), provider(s), which harness it targets or is.
## 2. Agentic Anatomy <!-- the signature diagram: the core + its surround -->
```mermaid
flowchart TB
subgraph Core["Agent Core"]
model["Model / Provider"]
prompt["System Prompt"]
loop["Reasoning Loop"]
end
mem["Memory + Context / Compaction"]
tools["Tools · Skills · MCP"]
orch["Subagents · Hooks · Permissions"]
loop --> model
loop --> tools
loop --> mem
loop --> orch
Populate every node with a real name/path from the evidence.
3. The Core
Model/provider layer, system prompt, and the reasoning loop. Trace one agent turn:
sequenceDiagram
participant L as Loop
participant M as Model
participant T as Tool Dispatch
L->>M: assemble context, call
M-->>L: tool_use(name, args)
L->>T: dispatch
T-->>L: result
L->>M: re-reason (until stop)
4. Context & Memory
Window assembly, compaction/summarization, and memory stores (working ↔ persistent, budget).
5. Capabilities
| Organ | Where it lives | Code or content |
|---|
| Tools | ... | ... |
| Skills | ... | ... |
| MCP | ... | ... |
6. Orchestration & Autonomy
Subagents (spawn/isolate/merge), hooks/triggers/scheduling, permissions/guardrails/HITL,
session/state/event bus.
7. Extension Points
How a developer adds a tool, skill, subagent, provider, or hook.
8. Organ Presence Matrix
| Organ | Present? | Where | Notes (absence is a finding / a decision) |
|---|
| Reasoning loop | ✅/⚠️/❌/n·a | ... | ... |
| ... | | | |
9. Glossary & Open Questions
Domain terms a newcomer must know; and what the evidence cannot determine — assumptions,
choices still open. Uncertainty goes here, not into the diagrams.
## Mermaid (GitHub-reliable rendering)
- Every diagram in a ```` ```mermaid ```` fenced block.
- `flowchart`/`graph` with `subgraph` for the anatomy, `sequenceDiagram` for the agent
turn, `classDiagram` only if OOP structure of a subsystem matters.
- Keep each diagram ≤ ~15 nodes; split dense views under sub-headings.
- Quote labels with spaces/special characters; identifiers match real names from the
evidence.
## Quality checklist before finishing
- [ ] Mode and system type stated with evidence (`src/` vs dotfiles; loop-in-source ⇒ Runtime).
- [ ] The anatomy diagram is populated with real names/paths, not placeholders.
- [ ] Every organ walked; each marked present/partial/absent/n·a (or decided/undecided) with a location.
- [ ] The reasoning loop (or the pack's steering mechanism) is located and traced.
- [ ] Absences recorded in the organ matrix, not silently dropped.
- [ ] Every file/function/tool/skill named in the doc exists in the mode's evidence.
- [ ] Sibling lens docs cross-linked if present.
- [ ] Uncertainties live in "Open Questions" / "Decisions needed", not disguised as facts.
- [ ] Exactly one Markdown file.
