Skip to content

ADR 0004 — Five-layer agent hierarchy is sufficient for v1.x

Status: Accepted Date: 2026-05-25 Deciders: principal-architect (eric) Supersedes: PRD §9 open question "Is the 5-layer agent hierarchy sufficient for nested specialization?"

Context

The framework defines five layers:

Layer Role Count today
L1 Global orchestrator (Cortex) 1
L2 Domain orchestrators (frontend, backend, ai_ml, …) 10
L3 Task orchestrator (ephemeral per story) dynamic
L4 Specialist agents 25
L5 Workers (code-writer, file-operator, …) 5

The open question was whether 5 layers gives enough room for nested specialization, or whether some teams would want L6+ for very deep domains (e.g. backend → python → fastapi → auth → oauth2-flows).

Decision

Keep 5 layers as the hard ceiling for v1.x. Don't expose mechanisms to add L6 or beyond.

Instead, nested specialization is handled inside L4 specialists via:

  1. Skill composition (SkillChain from Sessão #5) — a specialist composes smaller skills inline rather than delegating to a nested specialist
  2. Skills marketplace — depth is a property of skills (676 of them), not of agents. Adding deeper skills doesn't require deeper agents.
  3. primary_orchestrator re-routing — a specialist can defer back up to its domain orchestrator if a sister specialist is a better fit

Consequences

Positive

  • Schema simplicity: ROUTING-COMPASS, agent-registry, capability-graph stay flat
  • Fewer permutations in conflict resolution (orchestrator handoffs)
  • Cache locality: 5 layers means small prompt-prefix variation across agents
  • Performance: each layer adds a round-trip; capping at 5 keeps p95 latency bounded

Negative

  • Very deep domains may feel cramped — a python-fastapi-oauth-specialist doesn't get its own agent; it's a skill chain on backend-python-specialist
  • No "team of teams" abstraction within a single agent

Risks + mitigations

  • R: a domain explodes to 50+ skills that don't fit one specialist → M: split that L4 into two L4s (peer expansion is allowed — see Sessão #5's +5 specialists in the writing/automation/analytics/etc. domains)
  • R: cross-domain workflows hit too many handoffs → M: L3 task orchestrator already coordinates this; deeper nesting wouldn't help

Open follow-ups

  • Revisit at v2.0 with data on AgentMetrics.duration_ms per layer — if L4 routinely takes >10s due to skill composition overhead, consider L4a/L4b split
  • Add to _meta.expansion_policy in _agents-registry.yaml: "peer expansion at L4 yes; vertical nesting no"

References