entityprocess/agent-architecture-design

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:

1. Is the goal working software or optimizing a metric?
2. Is this a single discrete task or multiple coordinated parts?
3. How much human involvement is acceptable during execution?
4. 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:

1. Phases — What sequential or parallel steps does the workflow execute?
2. Artifacts — What does each phase produce? (specs, designs, tasks, code, reports)
3. Gates — What must be true before proceeding to the next phase?
4. Tooling — What tools/MCPs does each agent need?
5. Context flow — How is information passed between phases/agents?
6. 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:

1. Diagnosis — Software or metric shaped, task or project level
2. Recommended Pattern — Which agentic architecture and why
3. Workflow Design — Phases, artifacts, gates, context flow
4. Scaffolding Plan — Tools, MCPs, evals the agent needs
5. Management Model — Human role (Manager, Observer, or Spec-Writer)

Implementation Rules

1. Simple scales better — Do not recommend 3-level management if 2-level works. Simple configurations are more performant.
2. Context is everything — Agents depend entirely on the context and scaffolding provided by the architect. Design the scaffolding, not just the agent.
3. Human-centered → Agent-centered — For large projects, move from "human managing every agent" to "planner agent managing sub-agents" where the human observes.
4. 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.
5. 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