Agent Architecture Design
Overview
Guide the selection and design of the correct agentic architecture by diagnosing the problem type, mapping it to a proven design pattern, and defining the workflow structure, tooling, and management model.
Process
Phase 1: Problem Diagnosis
Categorize the request on two axes:
|
Task-Level (single job) |
Project-Level (coordination needed) |
| Software-Shaped (working code/system) |
Single-Agent Iterative Loop |
Autonomous Pipeline or Multi-Agent System |
| Metric-Shaped (optimize a number) |
Optimization Loop |
Optimization Loop + Multi-Agent System |
Diagnosis questions:
- Is the goal working software or optimizing a metric?
- Is this a single discrete task or multiple coordinated parts?
- How much human involvement is acceptable during execution?
- What scale justifies the architecture complexity?
Phase 2: Pattern Selection
Load references/agentic-design-patterns.md for full details on each pattern. Summary:
Single-Agent Iterative Loop (Agentic IDE)
- Human = manager, Agent = worker
- Decompose the problem into small chunks (UI, API, tests)
- Agent gets a workspace (terminal, files, search)
- Best for: individual developer productivity on discrete tasks
Autonomous Pipeline (Zero-Human Loop)
- Spec In → Autonomous Zone → Eval Out
- Heavy human involvement at start (specs) and end (review), zero in the middle
- Requires robust evals — iterations happen automatically until eval passes
- Best for: zero-human-intervention software delivery
Optimization Loop (Self-Improving Agent)
- Hill climbing against a specific metric
- Agent tries paths, fails, backtracks
- Needs a clear optimization target
- Best for: reaching peak of an optimization metric through experimentation
Multi-Agent System (Hierarchical/Supervisor Pattern)
- Specialized roles with defined handoffs (Researcher → Writer → Editor → Publisher)
- Complexity lies in context management between agents
- Only justified at scale (10,000 tickets, not 10)
- Best for: seamless coordination across specialized AI workers
Phase 3: Workflow Architecture
After selecting a pattern, define the workflow structure. Load references/workflow-patterns.md for framework-specific patterns.
For each pattern, define:
- Phases — What sequential or parallel steps does the workflow execute?
- Artifacts — What does each phase produce? (specs, designs, tasks, code, reports)
- Gates — What must be true before proceeding to the next phase?
- Tooling — What tools/MCPs does each agent need?
- Context flow — How is information passed between phases/agents?
- Resumption — How does the workflow recover from interruption?
Pattern → Workflow mapping:
| Agentic Design Pattern |
Typical Workflow |
| Single-Agent Iterative Loop |
Single-phase: decompose → implement → verify |
| Autonomous Pipeline |
OpenSpec-style: validate → propose → design → implement → verify |
| Optimization Loop |
Iteration loop: hypothesize → test → measure → backtrack/advance |
| Multi-Agent System |
Role pipeline: role₁ → handoff → role₂ → handoff → roleₙ |
Phase 4: Output
Produce a design document covering:
- Diagnosis — Software or metric shaped, task or project level
- Recommended Pattern — Which agentic architecture and why
- Workflow Design — Phases, artifacts, gates, context flow
- Scaffolding Plan — Tools, MCPs, evals the agent needs
- Management Model — Human role (Manager, Observer, or Spec-Writer)
Implementation Rules
- Simple scales better — Do not recommend 3-level management if 2-level works. Simple configurations are more performant.
- Context is everything — Agents depend entirely on the context and scaffolding provided by the architect. Design the scaffolding, not just the agent.
- Human-centered → Agent-centered — For large projects, move from "human managing every agent" to "planner agent managing sub-agents" where the human observes.
- Avoid pattern-confusion — Never use an Optimization Loop to build a novel. Never use a Single-Agent Loop for a project requiring specialized multi-agent orchestration.
- Scale justifies complexity — Multi-agent orchestration is only worth it at scale. For small problems, a single well-prompted agent outperforms a complex framework.
Skill Resources
references/agentic-design-patterns.md — Detailed pattern descriptions with examples and anti-patterns
references/workflow-patterns.md — Workflow patterns from OpenSpec, Superpowers, and Compound Engineering
Related Skills
- agent-plugin-review — Review an implemented plugin against architecture best practices
1---2name: agent-architecture-design3description: >-4 Use when designing an AI agent system, selecting agentic design patterns,5 planning multi-phase workflows, choosing between single-agent and multi-agent architectures,6 or when asked "what kind of agent should I build", "how should I structure this automation",7 "design an agent for X", or "which agentic pattern fits this problem".8metadata:9 source: https://skillmd.com/skills/entityprocess/agent-architecture-design10---1112# Agent Architecture Design1314## Overview1516Guide the selection and design of the correct agentic architecture by diagnosing the problem type, mapping it to a proven design pattern, and defining the workflow structure, tooling, and management model.1718## Process1920### Phase 1: Problem Diagnosis2122Categorize the request on two axes:2324| | Task-Level (single job) | Project-Level (coordination needed) |25|---|---|---|26| **Software-Shaped** (working code/system) | Single-Agent Iterative Loop | Autonomous Pipeline or Multi-Agent System |27| **Metric-Shaped** (optimize a number) | Optimization Loop | Optimization Loop + Multi-Agent System |2829**Diagnosis questions:**301. Is the goal working software or optimizing a metric?312. Is this a single discrete task or multiple coordinated parts?323. How much human involvement is acceptable during execution?334. What scale justifies the architecture complexity?3435### Phase 2: Pattern Selection3637Load `references/agentic-design-patterns.md` for full details on each pattern. Summary:3839**Single-Agent Iterative Loop** (Agentic IDE)40- Human = manager, Agent = worker41- Decompose the problem into small chunks (UI, API, tests)42- Agent gets a workspace (terminal, files, search)43- Best for: individual developer productivity on discrete tasks4445**Autonomous Pipeline** (Zero-Human Loop)46- Spec In → Autonomous Zone → Eval Out47- Heavy human involvement at start (specs) and end (review), zero in the middle48- Requires robust evals — iterations happen automatically until eval passes49- Best for: zero-human-intervention software delivery5051**Optimization Loop** (Self-Improving Agent)52- Hill climbing against a specific metric53- Agent tries paths, fails, backtracks54- Needs a clear optimization target55- Best for: reaching peak of an optimization metric through experimentation5657**Multi-Agent System** (Hierarchical/Supervisor Pattern)58- Specialized roles with defined handoffs (Researcher → Writer → Editor → Publisher)59- Complexity lies in context management between agents60- Only justified at scale (10,000 tickets, not 10)61- Best for: seamless coordination across specialized AI workers6263### Phase 3: Workflow Architecture6465After selecting a pattern, define the workflow structure. Load `references/workflow-patterns.md` for framework-specific patterns.6667**For each pattern, define:**68691. **Phases** — What sequential or parallel steps does the workflow execute?702. **Artifacts** — What does each phase produce? (specs, designs, tasks, code, reports)713. **Gates** — What must be true before proceeding to the next phase?724. **Tooling** — What tools/MCPs does each agent need?735. **Context flow** — How is information passed between phases/agents?746. **Resumption** — How does the workflow recover from interruption?7576**Pattern → Workflow mapping:**7778| Agentic Design Pattern | Typical Workflow |79|---|---|80| Single-Agent Iterative Loop | Single-phase: decompose → implement → verify |81| Autonomous Pipeline | OpenSpec-style: validate → propose → design → implement → verify |82| Optimization Loop | Iteration loop: hypothesize → test → measure → backtrack/advance |83| Multi-Agent System | Role pipeline: role₁ → handoff → role₂ → handoff → roleₙ |8485### Phase 4: Output8687Produce a design document covering:88891. **Diagnosis** — Software or metric shaped, task or project level902. **Recommended Pattern** — Which agentic architecture and why913. **Workflow Design** — Phases, artifacts, gates, context flow924. **Scaffolding Plan** — Tools, MCPs, evals the agent needs935. **Management Model** — Human role (Manager, Observer, or Spec-Writer)9495## Implementation Rules96971. **Simple scales better** — Do not recommend 3-level management if 2-level works. Simple configurations are more performant.982. **Context is everything** — Agents depend entirely on the context and scaffolding provided by the architect. Design the scaffolding, not just the agent.993. **Human-centered → Agent-centered** — For large projects, move from "human managing every agent" to "planner agent managing sub-agents" where the human observes.1004. **Avoid pattern-confusion** — Never use an Optimization Loop to build a novel. Never use a Single-Agent Loop for a project requiring specialized multi-agent orchestration.1015. **Scale justifies complexity** — Multi-agent orchestration is only worth it at scale. For small problems, a single well-prompted agent outperforms a complex framework.102103## Skill Resources104105- `references/agentic-design-patterns.md` — Detailed pattern descriptions with examples and anti-patterns106- `references/workflow-patterns.md` — Workflow patterns from OpenSpec, Superpowers, and Compound Engineering107108## Related Skills109110- **agent-plugin-review** — Review an implemented plugin against architecture best practices