/agent-creation

name: agent-creation
description: Use when creating a new specialist agent for Gaia, or reviewing whether an existing agent follows the correct structure, tone, and component inventory

Agent Creation

Every section below is tagged **universal** -- it holds for any agent, the orchestrator included -- or **specialist** -- it holds for an agent dispatched as a subagent, and the orchestrator is exempt from it by role rather than by oversight. The exemptions are structural: the orchestrator carries no `routing:` block because it is what routes, no `skills:` field because the host preloads skills only for a dispatched subagent, and no CANNOT DO -> DELEGATE table in the specialist sense because delegating is its function rather than its edge.

What is an agent? -- universal

An agent is a contract over project-context plus a small identity. For a specialist that identity points at one domain surface; the orchestrator's points at the conversation and the routing between surfaces. If the component you are building has no distinct contract, no delegation surface, and could work as injected text, it is a skill, not an agent -- that decision belongs upstream and this skill assumes it has been made.

What the identity buys is posture, not capability: measured, a persona does not improve factual accuracy at all, and irrelevant persona attributes cost up to 30 points of it. What it genuinely moves is tone, escalation threshold, refusal bar and report shape, so write it for those and drop the seniority decoration -- "senior architect" buys nothing and is charged for.

Step 0: Route every rule to a place that can hold it -- universal

Ask of each thing you want true of the agent: can it be enforced?

| Can it be enforced? | Where it goes | |---|---| | Yes | The `write` contract, the frontmatter (`tools`, `disallowedTools`, `permissionMode`), a PreToolUse hook, or simply not granting the tool | | No, but it is posture | The prose, carrying the consequence that justifies it | | No, and it is not posture | Nowhere -- cut it |

The third row is the one authors skip, and skipping it is not free: a line no mechanism can hold and no posture can bias lowers the odds that every other line holds, and adds one more pair that can conflict.

Prefer the enforceable destination whenever one exists, because prose is a probability shift while a mechanism is a boundary: a PreToolUse hook that returns `deny` blocks the tool without consulting `permissionMode` at all (the Write/Edit protected-path gate decides on `hooks/modules/security/protected_paths.py::is_protected_hook_path`, which never reads it), which is the same reason the sandboxing documentation puts the frontier in the operating system "regardless of what the model chose to run". A hook is gaia-system's to implement -- propose one rather than settle for a sentence. And when an agent crosses a line already written, what the crossing reopens is the destination, not the wording: "do not cheat" left cheating exactly where it was at 80%, and "solve it the way the designer intended" raised it to 95%.

Step 1: Answer the bifurcating dimensions -- tagged per dimension

**D0 (decide first): What is the contract? -- universal, and degenerate for the orchestrator** Every agent carries one; the orchestrator's is `read: [project_identity]` and `write: []`, because it holds no domain and persists no domain artifact. For a specialist, name the `read` slices this domain reasons over and the `write` slices it owns. `read` is the token lever -- the menu (`can_read` in the dispatch kernel) the agent may pull on demand, nothing preloaded, so every extra slice dilutes its focus and its evidence scope. `write` is the security lever -- the allowlist the runtime checks before accepting any `update_contracts` clause, so a contract absent from it cannot be persisted whatever the agent emits. `developer` writes `application_services`, `platform-architect` writes `infrastructure` and `infrastructure_topology`, a read-only diagnostic writes nothing or the single observation contract it curates. Get this wrong and every other decision is built on it.

**D1: Does the agent mutate system state? -- universal** A "yes" means Write/Edit in `tools`, `permissionMode: acceptEdits`, the T3 approval flow in failure handling, and a Realization Package output type; a "no" means none of those and a read-only output. The hard `disallowedTools: [Write, Edit, NotebookEdit]` denylist is reserved for the read-only-into-prod case -- an agent that inspects live production and must be incapable of mutating it, e.g. `cloud-troubleshooter` -- because an accidental write to a live resource is a real incident. Builders are governed softly instead, by T3 consent and their contract, carrying at most `[NotebookEdit]`. Withhold a tool for what the role must not do, never as a rank: the orchestrator keeps `Read` deliberately, so it can settle a claim it is able to see for itself instead of spending a dispatch to have it confirmed.

**D2: Does the agent enter the orchestrator's automatic routing? -- specialist** Almost always "yes" for a specialist. A "yes" means the description is written as triggering conditions and a `routing:` block (surface, adjacent_surfaces, commands, artifacts, required_checks) is proposed for it. Those signals are proposals -- gaia-system applies them to the agent's own frontmatter, `tools/scan/seed_surface_routing.py` seeds the `surface_routing` table at install time, and `tools/context/surface_router.py` reads that table at runtime.

One fact that is not a dimension: a subagent cannot spawn subagents -- `Agent`/`Task` are inert in a subagent's frontmatter even when listed. A specialist surfaces what it cannot do through its CANNOT DO -> DELEGATE table and the orchestrator routes; only an agent run as the main thread via `--agent` dispatches.

Step 2: Apply the component inventory -- tagged per component

Obligatory in every agent, tagged where it is not:

1. **`project_co