Agents

41 Claude Code agents, grouped by domain. This folder is the browsable, installable copy of .claude/agents/, which Claude Code loads automatically when you work in this repo. The two must stay identical (see Keeping the copies in sync).

Contents

• How they work together
• Roster
• Stack agents and their house rules
• House practices
• Memory
• Install
  • A personal agent set
  • One repository
  • A set of repositories
• Adding an agent
• Keeping the copies in sync
• Other runtimes

How they work together

host-agent hosts: it holds the house rules and decides who handles what. eng-manager-agent decomposes multi-domain work and launches the specialists. Subagents can nest three layers below the main session, so run host-agent as the main session (claude --agent host-agent) to leave room for the layers.

flowchart TD
  H["host-agent<br/>(main session)"] --> E[eng-manager-agent]
  H --> ST[stacy-agent]
  H --> PE[principal-eng-agent]
  H --> X["any specialist or skill"]
  E --> K["kotlin/ · java/ · swift/ · golang/ · web/"]
  E --> D["design/ · product/ · data/ · platform/"]
  E --> G["generic/ · conversation/"]
  E --> ST
  E --> PE

Roster

Stack agents and their house rules

Each stack agent’s House practices names the platform/ rules it follows and the CI workflow that checks its work.

House practices

Every agent except stacy-agent and host-agent ends with a House practices (team memory, 2026-10) section; those two read the source directly. It has three layers:

1. Evidence, for every agent. Check repo state against origin/main, list every hit before claiming “zero X”, stay in scope, verify before “done”, treat pasted secrets as compromised, follow the rooms in AGENTS.md and the platform/ files for each stack in the diff.
2. Code, for agents that write or review it. No speculative refactors, no defensive code or leftover noise, load-bearing comments only, tests that call the changed function, commit only when asked.
3. Domain notes, e.g. lint enforcement drift and multiplatform-first helpers for the Kotlin agents, cross-platform parity for iOS and design, ticket workflow for product, and each stack agent’s rules and CI.

stacy-agent carries the same lessons in its working-style defaults. When a lesson changes, update the memory first, then the agents that cite it.

Memory

project memory lives in the repo you are working in. host-agent’s working memory for the current effort is machine-local: .claude/agent-memory-local/host-agent/WORKING.md, ignored by git.

Install

flowchart LR
  A[agents/] -- "link_agents.sh SET" --> P["~/.claude/agents/SET/<br/>symlinks, every project"]
  A -- "link_agents.sh --scan SET PATH" --> S["~/.claude/agents/SET/<br/>only the agents a project needs"]
  A -- "rsync" --> R["REPO/.claude/agents/<br/>copies, shared with the team"]

A personal agent set

./agents/link_agents.sh --list                 # show the roster
./agents/link_agents.sh house                  # symlink all into ~/.claude/agents/house/
./agents/link_agents.sh --scan house ~/code/app  # pick agents for a project's stack
claude --agent host-agent                      # start a hosted session

Links point back into this repo, so git pull here updates every set. --scan detects the project’s stacks, recommends the matching agents plus a bench (host-agent, stacy-agent, eng-manager-agent, principal-eng-agent, product and research), asks before linking, and writes a SYSTEM.md in the set recording the choices. It runs on the stock macOS bash 3.2.

The script finds agents in the category folders next to it, so this README is never linked. If ~/.claude/agents/ already has another copy of these agents, remove it first or every agent shows up twice.

One repository

Copy, don’t link, so everyone who clones the repo gets the same agents:

rsync -a --exclude README.md --exclude link_agents.sh --exclude sdk agents/ ../your-app/.claude/agents/
cp -R .claude/agent-memory ../your-app/.claude/   # team memory, optional

Never put a README in .claude/agents/: Claude Code reads every .md file there as an agent definition.

A set of repositories

Use one personal set (above), and start host-agent from one repo with the others added: claude --agent host-agent --add-dir ../other-repo. Each repo’s own AGENTS.md still governs that repo. To give each repo a shared copy instead, repeat the rsync per repo.

Adding an agent

1. Put it in the matching category folder with standard frontmatter (name, description, tools). If it delegates, include Agent in tools.
2. Add a House practices section built from .claude/agent-memory/stacy-agent/, plus its platform/ rules if it is a stack agent.
3. Add a row to the roster above and to eng-manager-agent’s roster, then sync the copies.

Keeping the copies in sync

Edit one copy, then mirror it:

rsync -a --delete --exclude README.md --exclude link_agents.sh --exclude sdk agents/ .claude/agents/
diff -r -x README.md -x link_agents.sh -x sdk -x .DS_Store agents .claude/agents   # must print nothing
scripts/export-agents.py && scripts/export-agents.py --check                   # regenerate the other runtimes

Other runtimes

Copilot and Cursor read .claude/agents/ directly. For Codex (.codex/agents/*.toml), Gemini CLI (.gemini/agents/*.md) and Copilot’s own .github/agents/*.agent.md, run scripts/export-agents.py; the outputs are generated from this folder and checked in. sdk/openai_agents_house.py builds OpenAI Agents SDK agents from the same files at runtime (python3 agents/sdk/openai_agents_house.py prints the roster with each agent’s capabilities). What each runtime honors, and what it ignores (tools:, memory:), is in PORTABILITY.md.