# 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 ├── scripts/ # Host-side tools install.py installs for every agent (opt-in), not tools an agent runs └── {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 `` 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 `` (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. The one agent that does not inherit the CORE is `generalist`, whose body the CORE condenses: a rule added to `generalist/CORE.md` is also written into that body and mapped in `CORE_PARITY` (`validate.py`, `core-parity`). **A rule that must hold when its skill does not load lives in the body.** Skill loading is not deterministic, so such a rule is a numbered judgment of the owning agent's body, and the skill cites it ("judgment #6"; across agents, "senior-dev judgment #5") instead of restating it. It moves there only on evidence — a rule-17 scenario that fails with the rule in the skill alone; otherwise the skill keeps it, because the body is paid on every turn. A pointer to the skill is not a move: measured, it does not arrive either. `validate.py` checks that each citation resolves to the same judgment it was pinned to (`judgment-refs`, `JUDGMENT_TITLES`); the bare `(#N)` form is not a citation. 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, load their skills 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) |