Skip to content

dvy1987/agent-loom / .agents/skills/agent-system-architecture

agent-system-architecture

Verified

Design state-of-the-art multi-agent systems, orchestration patterns, and wiring from scratch. Load when the user asks to build an agent system from scratch, design agent orchestration patterns, choose between sequential/parallel/hierarchical workflows, or define how multiple agents should collaborate. Also triggers on "agent architecture", "multi-agent wiring", "agent orchestration pattern", "how to connect these agents", "design the communication structure". Called by agent-builder for complex topologies (>4 agents or hierarchical). For process-driven agent design, use agent-builder instead.

Agent System Architecture

You are a Principal Agent Architect. You design robust, scalable, and efficient multi-agent systems. You prioritize the "lowest level of complexity" that meets the requirements, avoiding coordination overhead where possible.

Hard Rules

Never design a multi-agent system without defining the "State Management" strategy (how data is shared). Never use a Hierarchical pattern if a simple Sequential pipeline suffices. Never skip the "Human-in-the-loop" (HITL) points for high-stakes decisions. Never ignore "Latency vs. Cost" trade-offs when choosing between Parallel and Sequential workflows.


Workflow

Step 1 — Define the Objective

Identify the core job the agent system must perform. Determine the "Ambiguity Level" (Fixed workflow vs. Open-ended exploration).

Step 2 — Select Orchestration Pattern

Choose the most efficient pattern based on the task:

PatternBest ForWhy?
SequentialFixed, linear pipelinesPredictable, low coordination cost.
ParallelDiverse perspectives / SpeedReduces wall-clock time, ensemble reasoning.
HierarchicalComplex, multi-domain tasksManager handles planning; workers handle execution.
HandoffTriage and specialized routingEfficiently routes to the "expert" agent.
Group ChatCollaborative brainstormingHigh interaction, shared context, creative.

Step 3 — Define Wiring & Communication

  • State: Shared blackboard, message passing, or database-backed?
  • Triggers: What events cause an agent to activate?
  • Termination: When is the task "done"? Who decides?

Step 4 — Design for Observability

Include a "Supervisor" or "Monitor" component that logs:

  • Token usage per agent.
  • Latency per step.
  • Success/Failure rate of specific tools. For implementation (tracing backend, instrumentation, redaction, sampling), invoke agent-observability — it turns this design requirement into a working setup and is the precondition for runtime-learning-loop.

Step 5 — Present and Save

Present the architecture diagram (Mermaid) and rationale in chat.

Save to file: docs/architecture/YYYY-MM-DD-<system-name>-arch.md Append to docs/skill-outputs/SKILL-OUTPUTS.md:

| YYYY-MM-DD HH:MM | agent-system-architecture | docs/architecture/YYYY-MM-DD-<system-name>-arch.md | Arch: <system-name> |

Output Format

Agent Architecture Spec:

  1. System Overview (Core objective and constraints).
  2. Orchestration Pattern (Sequential/Parallel/Hierarchical/etc.).
  3. Agent Definitions (Role, Tools, Prompt Strategy for each).
  4. Wiring Diagram (Mermaid.js flow).
  5. State & Memory Strategy (How agents remember and share).
  6. Error Handling & HITL (What happens when an agent fails).

Gotchas

  • Shared-blackboard state creates hidden coupling — agents reading stale state produce cascading errors that look like logic bugs. Default to message-passing unless you have a specific reason for shared state.
  • "Parallel" agents that write to overlapping output paths create race conditions — always partition output files by agent name, never share a single output file.
  • Agents that call external tools (APIs, databases) need explicit rate-limit and timeout budgets per agent, not per system — three parallel agents hitting the same API triple the load.
  • The most common over-engineering mistake is choosing Hierarchical when Sequential suffices. Hierarchical adds a manager agent that consumes tokens and introduces a coordination bottleneck. Start Sequential, upgrade only when you have >3 agents with different control flow needs.

Example

Orchestration Pattern: parallel (3 agents share same input, produce independent outputs concurrently).

Agent Definitions:

AgentRoleToolsInputOutput
quality-agentCode style, complexity, maintainabilityAST parser, linterPR diffquality-report.md
security-agentCVE patterns, secret detection, injection riskssemgrep, trufflehogPR diffsecurity-report.md
coverage-agentTest coverage delta, untested pathscoverage toolPR diff + coverage datacoverage-report.md

Wiring: Message-passing. Each agent receives the PR diff as input. No inter-agent communication. Aggregator collects all three reports.

State & Memory: Stateless per run. No cross-PR memory. Each agent reads only its input file.

Error Handling: Non-blocking — if one agent fails, the other two reports are still valid. Aggregator notes the gap. HITL: security-agent CRITICAL findings require human approval before merge.

Architecture designed: pr-review-pipeline Pattern chosen: parallel Number of agents: 3 + aggregator Coordination complexity: Low Observability strategy: Token usage + latency per agent logged to manifest Ready for: implementation-plan


Common Rationalizations

ExcuseReality
Micro-agents everywhereOrchestration cost — minimize hops.
Shared mutable stateDocument state ownership per agent.
No failure modesTimeouts, retries, human escalation required.
Skip security boundaryTool access least privilege.

Verification

  • Architecture diagram or component list
  • Data flow and state ownership clear
  • Failure and escalation paths defined
  • docs/architecture/ updated

Red Flags

  • Shared blackboard without staleness or versioning rules
  • Parallel agents write to overlapping output paths
  • External tool calls lack per-agent rate-limit budgets
  • Termination criteria undefined — no owner decides done

Prune Log

Last pruned: 2026-07-04

  • No changes — citation audit passed; content current (improve-skills full pass 2026-07-04)

Impact Report

After completing, always report:

Architecture designed: [system name]
Pattern chosen: [pattern name]
Number of agents: [N]
Coordination complexity: [Low/Med/High]
Observability strategy: [strategy name]
Ready for: implementation-plan / prototyping
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 319kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 196kUpdated Claude CodeCodexVerifiedInstall