AGENTS.md · git:20261014.9571e8f · 2026-10-14 · sha256 abd34d558ca0b9cd
AGENTS.md git:20261014.9571e8fA
Immutable. This exact content never changes and is served at /api/v1/blob/abd34d558ca0b9cd.
# Agent Catalog
A catalog of specialized agent definitions. Each agent is a self-contained package:
an identity, a way of reasoning, and the resources it needs to operate. Any model
reading an agent's `AGENTS.md` should be able to orient itself and act with the
intended judgment — not follow a recipe.
## Structure Convention
```
agents/
├── AGENTS.md # This index
└── {agent-name}/
├── AGENTS.md # Identity, reasoning model, heuristics, limits
├── skills/ # Loadable knowledge (one folder per skill, SKILL.md inside)
└── scripts/ # Executable tools the agent may use (optional)
```
Rules for this catalog:
1. An agent definition encodes **decision criteria**, not task lists. If a section
could be replaced by "just do X", it doesn't belong here.
2. Skills follow the Agent Skills spec: `skills/{name}/SKILL.md` with frontmatter
(`name`, `description` with trigger, `license`, `metadata`). `metadata` keeps
the spec's canonical `author` + `version` shape, and **`version` is not a
chore**: don't bump it per edit. Which catalog commit a copy came from — and
what moved since — is answered by the provenance stamp `install.py` writes
(`--status`), because git already knows it exactly and a hand-kept number
does not. Bump only for a deliberate release marker. `metadata` also
carries **`local-agents-id`**: an opaque `sk-<6 hex>` given once and never
changed, a rename included. It is how `install.py` tells our copy of a skill
from a stranger's with the same name — 26 of our 48 names already exist in
public registries, and a host's skills dir is shared. A new skill gets a
fresh one; `validate.py` checks they are present, unique and unchanged
(`skill-ids`).
3. Each agent's `AGENTS.md` opens with YAML frontmatter holding a curated
`description:` — one paragraph of "use this agent for X" plus `<example>`
blocks that show WHEN to delegate to it. `install.py` reads this to generate
each tool's agent-file description; without it, it falls back to the first
sentence (a weaker delegation signal). Keep the body below the frontmatter.
The frontmatter also declares `inherits:` — the full, ordered list of agents
whose `CORE.md` gets inlined (`[generalist]`, `[senior-dev, generalist]`, or
`[]` for the base). The installer reads only this list; the prose that
explains the inheritance can be reworded freely. Inheriting from X means
listing what X inherits too; `validate.py` checks it.
4. Every new agent gets a row in the table below, and a routing row in
`eng-manager`'s [lh-orchestration](eng-manager/skills/lh-orchestration/SKILL.md)
skill — the only component that knows the whole roster.
5. **Identity is stack-agnostic; skills carry the stack.** An agent is defined
by how it thinks and decides, never by a language or vendor tool: the same
judgment has to survive the project switching from TypeScript to Go, or from
Figma to Penpot. Naming a technology is fine in an `<example>` (that is how
the delegation signal is taught) and in body prose as a concrete
illustration — but not in the sentence that says what the agent IS. Deep
stack knowledge lives in a skill (`lh-react-next`, `lh-dev-handoff`), which is
swappable per project and is the pattern to copy when adding another.
The exception is a PLATFORM agent whose name states its scope — `apple-dev`
is Apple platforms and says so; the failure mode is a generic NAME hiding a
specific agent, which is what `senior-dev` used to be. `validate.py` enforces
this on the description; the allowlist is `PLATFORM_AGENTS`.
6. **Language register convention.** Character-archetype agents (modeled on a
real or fictional person — e.g. `visionary`/Jobs, `stark`/Stark,
`security`/Elliot Alderson) speak **Neutral Spanish** — the film-dub cadence
that makes a character feel real. Real-teammate agents (`architect`,
`senior-dev`, `ux-ui`, `gamification`, `qa`, `apple-dev`) speak **Rioplatense
Spanish (voseo)** — an actual colleague. The `generalist` base stays
register-neutral ("respond in the user's language"). Pick the register by
asking: is this a PERSON being portrayed, or a peer at the next desk? The
shared part — reply in the user's language, and a question to the user is
a full stop — lives once in `generalist/CORE.md`; each agent's Persona
states only its register, in one line.
7. To wire an agent into a tool config (opencode, SDK, etc.) see
[INTEGRATION.md](INTEGRATION.md) — reference the file, never copy the prompt.
8. **One plan, brochures on the side.** The English docs are the single
source of truth. A file named `*.es.md` — such as
[REFERENCE.es.md](REFERENCE.es.md), the human-facing quick guide — is a
brochure written natively in Spanish, holding only what can't be derived
from the English files. It is not a translation and must never become one:
do not translate a brochure into English, do not translate the English docs
into Spanish, and do not keep ES/EN twins of any doc. A second copy of the
plan has to be kept identical to the first by hand, and nothing can check
that it is. This applies to agents and LLMs editing the repo as much as to
people. Fix a stale brochure in its own language. The one English passage
a brochure may carry is its opening do-not-translate note, so that a reader
who does not read Spanish still meets the rule before acting on the file;
it states the rule and nothing else, and is not a twin.
9. Tool-specific setup recipes (Claude Code, opencode, Kiro CLI, Codex,
Antigravity CLI), global
and per-project: [USAGE.md](USAGE.md).
10. To COPY an agent/skills into a tool's global config automatically, use
`install.py` — see [INSTALL.md](INSTALL.md) for the how-to.
11. **Section scope.** Three optional `##` sections carry relationship content,
and each answers a different question. Keep them apart:
- `## Handoffs` — *where does work go when it stops being mine?* The routing
summary. Required once an agent routes work to another; links to
`../{agent}/AGENTS.md` belong here.
- `## External skills` — *what ships outside this catalog?* Host-provided
skills only, referenced **by name and conditionally** (never by path — the
catalog installs into several tools, each with its own layout). No agent links.
- `## Where you sit in the team` — *how do I differ from the agent next to
me?* Disambiguation, for agents whose scope overlaps a neighbour's.
A handoff mentioned inline in `## Persona` or a judgment section as a rule
of conduct ("if it turns technical, hand it to senior-dev") stays put — it's
behaviour, not a routing table. `validate.py` enforces the `## External
skills` boundary; the rest is review.
12. `validate.py` checks these conventions and regenerates the derived blocks in
[GRAPH.md](GRAPH.md). Run it before committing; CI runs it on every PR.
What a SCRIPT does is tested apart, in `tests/`, with the standard
library's `unittest` (`python3 -m unittest discover -s tests`): a
convention is a property of the catalog's files, a behaviour is a
property of running code, and one check per behaviour names what broke.
CI runs those tests before installing anything, which also proves the
scripts need nothing beyond the standard library.
CI also runs `skills-ref validate` — the Agent Skills authors' own reference
implementation — over every skill, so conformance is judged by the spec
rather than by our reading of it. It is pinned to a commit on purpose: it
ships as source only and calls itself a reference implementation, so an
unpinned clone would put someone else's main branch in our build.
13. Docs that describe the catalog as a whole — [README.md](README.md) (front
door), [GRAPH.md](GRAPH.md) (how everything is wired), [LICENSE](LICENSE),
[ESTADO-DEL-ARTE.es.md](ESTADO-DEL-ARTE.es.md) (dated industry survey and
measured host facts; a rule-8 brochure),
[BACKLOG.es.md](BACKLOG.es.md) (the work, with stable IDs, a checkable
"done when" and the commits that closed each item; a rule-8 brochure) —
live at the root. Adding one means adding it to this list.
14. **Skills add method; the base is never restated.** Every installed agent
carries `generalist/CORE.md` inlined (peers also `senior-dev/CORE.md`), so
a skill that re-explains a CORE rule is paid for twice on every load — cite
it in a clause and move on. A skill MAY open a pattern with one sentence of
its own agent's belief, because skills are consumed cross-agent by readers
who do not have that body loaded; it may not re-argue the belief. Triggers
name a threshold: a skill that would load on every turn is base content,
not a skill. `## When to Use` is optional and exists only to say what the
description's trigger cannot — a `NOT` exclusion, or an ordering against a
named skill. A section that repeats the trigger is deleted; `validate.py`
enforces that part (`when-to-use`), the rest is review.
15. **Preferences stay in the harness.** A user's CLI tool choices, pet
analogies, or the name of a provider-specific host skill belong in that
user's own config (`CLAUDE.md` and its equivalents), which every installed
agent already reads. They don't go in the catalog: it installs onto
teammates' machines and into CI, where those tools may not exist and those
names mean nothing, and an agent told to run a tool that isn't there fails
where nobody is watching. A stack identifier is fine as an illustration
when it is one of several (`NEXT_PUBLIC_*`, `VITE_*`); alone, it reads as
the default. The test is whether the rule states an OUTCOME with a
fallback or a TOOL without one: "search respects `.gitignore` and returns
line numbers; `rg` if present, else say so" is catalog content and lives
in `generalist/CORE.md`; "never use grep, use rg, install it if missing"
is a preference and stays in the harness.
16. **Access is declared, not assumed.** Every agent's frontmatter carries
`access: read` or `access: full`, and `install.py` renders it into what
each host can enforce: a tool allowlist in Claude Code, `permission` in
opencode, tool tags in Kiro, a `tools:` allowlist per tier in Antigravity
(written for `full` too: an agent without one gets almost no tools),
`sandbox_mode` in Codex, a stated limit in the shared roster. `read` is
for the two agents whose deliverable is never an artifact — `visionary`
(a verdict) and `eng-manager` (a route) — for whom building is a ROLE
error, not a rarity; they read, search, fetch and delegate. Everyone else
is `full`: an architect who writes the example or the spike, a product
manager who writes the backlog file, a designer who writes the mockup.
Measured before choosing: with the tools inherited, `architect` applied a
requested change AND respected a contract it found in the tests — that is
participation, not a violation, and a tier that forbids it protects
nothing. This is a floor: a guardrail in prose ("qa never fixes product
code") is a promise, a guardrail in the tool list is a fact. What no host
can express by tool name stays a promise and gets a scenario (rule 17).
`validate.py` enforces the field (`access-policy`).
17. **A promise ships with its scenario.** A new judgment, handoff or hard
rule in an agent is a claim about behaviour, and the catalog's own checks
can only see its text. The behavioural harness (the `interaction` repo,
`run.py`) is where the claim gets tested against the installed agent, on
the model in daily use, with a neutral judge. Add the scenario in the same
change as the promise, run it against the previous version first so the
baseline failure is on record, and let the criterion measure what the
reply DELIVERS — never its tone, length or dialect, which belong to the
host.
## Agents
| Agent | Purpose | Entry point |
|-------|---------|-------------|
| `generalist` | Multipurpose agent. Encodes the core reasoning loop: verification habits, task decomposition, and next-step decision-making. Base layer for any task without a specialized agent. | [generalist/AGENTS.md](generalist/AGENTS.md) |
| `architect` | Senior Architect mentor. Inherits the generalist loop; adds architectural judgment (tradeoffs, boundaries, design review) and a teaching model. Helpful first, challenging when it matters. | [architect/AGENTS.md](architect/AGENTS.md) |
| `senior-dev` | Senior Software Engineer as a work peer. Inherits the generalist loop; adds developer judgment, the peer contract, and pairing habits. Language and framework are context, not identity — the stack comes from skills. Builds with you, not above you. | [senior-dev/AGENTS.md](senior-dev/AGENTS.md) |
| `ux-ui` | Senior Product Designer (UX/UI) as a daily work peer, dev-fluent. Inherits the generalist loop and the senior-dev peer contract; adds design judgment, dev-handoff translation, and mockup production. | [ux-ui/AGENTS.md](ux-ui/AGENTS.md) |
| `gamification` | Gamification Analyst — product voice, never dev-speak. Walks flows, simplifies them, applies game thinking (loops, progression, habit) with an explicit ethics line. Inherits the generalist loop and the peer contract. | [gamification/AGENTS.md](gamification/AGENTS.md) |
| `visionary` | Product Visionary modeled on Steve Jobs's documented thinking. Brutally honest about the work, never the person; focus as subtraction, benefit over specs, teaching from product history. Inherits the generalist loop. | [visionary/AGENTS.md](visionary/AGENTS.md) |
| `qa` | Senior QA Engineer as a close peer of dev and ux-ui. Hunts unconsidered flows, writes test code (never fixes product code), reports with reproductions. The bug is the adversary, never the dev. | [qa/AGENTS.md](qa/AGENTS.md) |
| `stark` | The Tony Stark archetype: polymath engineer-inventor for complex problems, 0→1 products, and crises. First principles, build-to-think, wit aimed at the problem never the person. Inherits the generalist loop and the peer contract. | [stark/AGENTS.md](stark/AGENTS.md) |
| `apple-dev` | Senior Apple-platforms engineer (Swift/iOS/macOS) as a sustained MENTOR: Socratic teaching with a calibrated ladder, severity-tagged reviews, curriculum awareness. Grows the user into an engineer who solves alone. | [apple-dev/AGENTS.md](apple-dev/AGENTS.md) |
| `security` | Security Engineer (Elliot Alderson archetype) for DEFENSE: exhaustive threat modeling, adversarial code audit, and actionable remediation. Attacker mindset pointed at securing the user's own product; the vuln is the adversary, never the dev. | [security/AGENTS.md](security/AGENTS.md) |
| `devops` | Senior DevOps/SRE: owns the path from "works on my machine" to "runs reliably". CI/CD, infrastructure-as-code, observability, SLOs. Automate toil, make deploys boring and reversible. Inherits the generalist loop and peer contract. | [devops/AGENTS.md](devops/AGENTS.md) |
| `dba` | Database Engineer and OWNER of the data model: schema design, migrations, indexing and query cost, integrity under concurrency, data lifecycle. Sets the constraints architect and devops design within. Inherits the generalist loop and peer contract. | [dba/AGENTS.md](dba/AGENTS.md) |
| `data-ml` | Senior Data & ML Engineer: data pipelines, honest ML modeling, and LLM integration. Start from the decision not the model; evaluation is the deliverable; LLMs are components with contracts and costs. Inherits the generalist loop and peer contract. | [data-ml/AGENTS.md](data-ml/AGENTS.md) |
| `eng-manager` | Engineering Manager / Delivery Lead: the orchestration layer. Routes work across the roster, unblocks, keeps delivery predictable and honest. Knows every agent. A multiplier, not a hero. Inherits the generalist loop. | [eng-manager/AGENTS.md](eng-manager/AGENTS.md) |
| `product-manager` | Senior Product Manager: the vision→execution connective tissue. Owns the why/what/for-whom — discovery, backlog, prioritization — and leaves the how to the team. Outcomes over output. Inherits the generalist loop and peer contract. | [product-manager/AGENTS.md](product-manager/AGENTS.md) |