> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gdilabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# The agent hierarchy

> > Implementation note (2026-05-13). The L1/L2/L3/L4 split below > remains the conceptual shape of code-build runs but is no longer > hardcoded in the worker. Every flow — code, writing, research, > security, Q&A — is now a versioned YAML...

Cerebrum's agents aren't a flat pool. They're organized in four levels, each with a defined role.

## L1 — Team Lead

Free-model orchestration. Reads the request, classifies it, and decides whether it's routine (stays inside free) or non-trivial (escalates to L2). Delegates work, doesn't execute it.

## L2 — Managerial roles

Paid-model leadership. Specializes by role:

* **Architect** — system design and structural decisions.
* **Tech Lead** — implementation plans and code-level direction.
* **Release Manager** — deployment and rollout decisions.
* **QA, Security, and Adversarial leads** — quality, risk, and red-team thinking.

L2 doesn't execute either. It plans and routes work to L4.

## L3 — Acceptance

Free-model verification. Reads the executor's output and checks it against the original ask. Returns pass/fail with deltas (what's missing, what needs revision). It doesn't rewrite.

## L4 — Executor

Paid-model production. Specializes in file writes — emits net-new files and surgical edits — and streams tokens with periodic heartbeats so long generations stay alive end-to-end.

## How escalation works

Within a level, conflicts retry up to three times. After three failures, the conflict moves up — to a more capable agent — rather than burning more attempts at the same level. Sub-job nesting is capped at depth two.

## Why this shape

* **Free models do orchestration cheaply.** L1 (classify) and L3 (verify) don't need a paid model, and using one would waste cost.
* **Paid models do actual work.** L2 plans, L4 builds. The hardest tokens land on the best model.
* **Acceptance is separated from execution.** The same agent doesn't get to grade its own work.

## Beyond code

The L1/L2/L3/L4 shape suits *code* flows. Non-code flows aren't shaped
the same way:

* **`document_writing`** is an editorial chain (outline → research →
  draft → fact\_check → polish).
* **`research_brief`** is a fan\_out across specialist subdomains (web,
  internal KB, academic) joined by a synthesis level.
* **`security_review`** is a triage + parallel static scans + LLM
  analyst + human approval + final report pipeline.
* **`quick_qa`** is a single free-tier level with a schema verifier.

These all run on the same scenario engine. The L1/L2/L3/L4 layering
remains the *default convention* for `code_build` and
`code_build_strict`; everything else picks its own level ids.