sharaf/agentic-harness-architect
Design, build, or audit a coding agent, agentic loop, tool-use harness, or autonomous coding system — covering loop architecture, action space, context strategy, observation formatting, evaluation, error handling, prompt engineering, and task decomposition. Use when the user wants to design an agent, build a coding agent, scaffold an agentic system, architect a tool-use loop, review an existing agent harness for improvements, fix context bloat or compaction problems, tune observation formatting or tool output handling, debug agent loop or termination issues, design a system prompt or evaluator prompt for an agent, set up or redesign an agent evaluation pipeline, plan multi-agent orchestration, or specify how an agent should manage context, tools, prompts, evaluation, or recovery (greenfield design or audit mode).
100
100%
Does it follow best practices?
Impact
100%
1.23xAverage score across 4 eval scenarios
Passed
No known issues
phase-02-architecture-selection.mdreferences/
Phase 2: Architecture Selection — Single vs. Multi-Agent
Start with the simplest architecture that can work. Complexity must be justified.
Default to single agent when
- Task fits one context window
- Steps are sequential and interdependent
- Shared context is essential throughout
- Cost matters (multi-agent uses 15x more tokens than chat)
Escalate to multi-agent when
- Task exceeds single-agent context capacity
- Self-evaluation produces unreliable quality signals (subjective tasks)
- Task has genuinely parallelizable subtasks (research, testing)
- Output quality justifies the cost premium
- Verifiable evaluation criteria exist
If multi-agent, select topology
| Topology | When to use |
|---|---|
| Pipeline (PGE) | Deterministic workflows with clear phase boundaries |
| DAG | Known dependency structure with parallelizable branches |
| Hierarchical | Complex tasks needing dynamic decomposition and error recovery |
| Fan-Out/Gather | Parallel research or exploration with synthesis |
| Cascade | Verification-routable — single agent first, escalate on failure |
| Peer-to-Peer (A2A) | Resilience where no single point of failure is acceptable |
Agent count heuristic
Saturation threshold is ~4 agents. Start with 2 (generator + evaluator). Add planner only if generator consistently underscopes. Add parallel workers only for truly parallelizable read tasks. Unstructured multi-agent networks amplify errors up to 17x.
Orchestration maturity model
Move through levels incrementally:
- Level 0: Single agent with good context engineering (start here)
- Level 1: Generator + Evaluator separation (highest ROI)
- Level 2: Planner + Generator + Evaluator
- Level 3: Parallel workers for read operations (keep writes serialized)
- Level 4: Composite patterns with schema enforcement + full observability
evals
scenario-1
scenario-2
scenario-3
scenario-4
references