SCHEMA

Agent Schema v2

> Single source of truth for the shape of every agent in this pack. > One schema, one pool — `agents/index.json` is generated from these files, > and the orchestrator routes tasks to agents via that index. > > **See also**: `agents/STYLE.md` — how the body of an agent should *read* > (mission shape, critical rules, Deep Reference convention, retrofit > checklist). SCHEMA enforces the frontmatter contract; STYLE shapes the > prose.

---

File layout

Every agent lives at `agents/<category>/<slug>.md` and has three parts:

---
<YAML frontmatter — required fields + optional fields>
---

<Markdown body — the agent's system prompt>

Anything under `agents/` that is **not** an agent file (README, SCHEMA, index.json, playbooks, templates, scripts) MUST NOT start with `---` as its first line. The linter uses the first-line `---` check to discriminate.

---

Frontmatter — required

Every field below is mandatory. Missing any → lint error.

| Field | Type | Values | Meaning | |-------|------|--------|---------| | `schema_version` | enum (string) | currently `"2"` | Declares which version of this schema the file conforms to. Linter rejects unknown / outdated versions; `scripts/migrate_schema.py` rolls older versions forward automatically. See the "Schema versioning" section at the bottom of this doc. | | `name` | string | human-readable display name | Shown in integrations, UI surfaces, and the agent's self-reference in the body. May be kebab-case (e.g. `qa-verifier` for strict reviewers) or human-formatted (e.g. `Backend Architect`, `DevOps Automator` for persona agents). Does NOT have to match the filename. The identity key used for routing, state, and hooks is the **slug** — see below. | | `description` | string | 1–2 sentences | What it does, when to invoke it. Used by the orchestrator for routing. | | `category` | enum | see list below | Top-level bucket. Must match the parent directory. | | `protocol` | enum | `strict` \| `persona` | How the agent behaves (see "Protocol" section). | | `readonly` | bool | `true` \| `false` | `true` = reviewer/scout, cannot edit files. `false` = write agent. | | `is_background` | bool | `true` \| `false` | `true` = long-running (tests, lint, builds). Default `false`. | | `model` | string | a Cursor model slug, e.g. `claude-opus-4-8` | Concrete model the dispatched subagent runs on. Defaults to the strongest model. See "Model" below. | | `tags` | list[string] | lowercase kebab | Searchable labels used by `index.json` for task-to-agent matching. |

Slug — identity key (derived, not frontmatter)

The **slug** is the agent's stable identity across the whole system: routing, `index.json` lookups, hook `AGENT: <slug>` markers, memory entries, telemetry, `distinguishes_from` references. It is NOT a frontmatter field — it is the filename stem (`agents/<category>/<slug>.md` without the `.md` extension).

Rules:

• Must match `[a-z0-9][a-z0-9-]*` (lowercase, kebab-case).
• Must be unique across the entire `agents/` tree (enforced by the linter).
• Chosen once at creation time; renaming a slug is a breaking change

because every consumer that cites it (other agents' `distinguishes_from`, hook AGENT markers in logs, cached memory entries) must be updated.

• Catalog agents imported from upstream libraries keep their

`<category>-<slug>` prefix (e.g. `engineering-backend-architect.md`) to preserve recognizability.

The orchestrator uses the slug; `name` is cosmetic.

Category enum

orchestration      — task routing, repo mapping, delegation
review             — readonly reviewers (security, quality, qa, sre, regression)
engineering        — backend, frontend, devops, data, embedded, AI engineering
design             — UI/UX, brand, accessibility, visual
testing            — QA, performance, API testing, evidence
product            — PM, sprints, feedback, trends
project-management — planning, studio ops, coordination
marketing          — growth, SEO, content, social, localization
paid-media         — PPC, tracking, campaign audits
sales              — outbound, deals, discovery, proposals
finance            — FPA, bookkeeping, tax, investments
support            — customer support, compliance, analytics
academic           — research, psychology, history
game-development   — Unity, Unreal, Godot, Roblox, Blender
spatial-computing  — XR, visionOS, WebXR
specialized        — blockchain, MCP, Salesforce, ZK, niche

Tags — recommended vocabulary

Use these when they apply. Add new ones freely — the index just aggregates whatever is there. Prefer 3–8 tags per agent.

# Skill tags
backend frontend fullstack devops infra database cache messaging
security auth authz secrets owasp crypto
testing qa e2e unit performance load observability slo

# Domain tags
fintech banking payments escrow wallet
blockchain ethereum solana ton evm zk
gamedev unity unreal godot
healthcare hipaa pci gdpr
ai ml llm rag embedding
mobile ios android react-native
web react vue angular next svelte
saas b2b multi-tenant

# Function tags
review audit scout orchestration writer reviewer

---

Frontmatter — optional

| Field | Type | When to use | |-------|------|-------------| | `domains` | list[string] | Project types where the agent is relevant. Default `[all]`. Members MUST be in the controlled vocabulary (see "Domain vocabulary" below). Used by the integration prompt to filter out agents irrelevant to the current project (e.g. a TON project hides WeChat / Xiaohongshu specialists). | | `distinguishes_from` | list[string] | Slugs of agents that are often confused with this one. Used by the orchestrator as a tie-breaker when tag intersection alone is ambiguous. Every entry MUST be a valid slug under `agents/`; self-reference is rejected by the linter. | | `disambiguation` | string | One-line guidance (≤ 240 chars) that tells the orchestrator when to pick THIS agent versus the ones in `distinguishes_from`. Written as "Use me for X; for Y delega