agent-dev-team

A tiered engineering team for AI coding tools. 21 role agents across four seniority tiers, 26 portable workflow skills, and an escalation protocol that keeps work at the right level instead of letting one undifferentiated assistant attempt everything.

Works in Claude Code, Codex, Gemini CLI, Cursor, Windsurf, OpenCode, GitHub Copilot, and anything else that reads AGENTS.md or the Agent Skills format.

Why tiers

An assistant with no tier does the same thing whether the task is a typo or a schema migration: it tries. The interesting failures are not "it wrote bad code" but "it made a decision it had no business making" — a schema change inside a bug fix, an auth tweak inside a rename, a migration with no way back.

This encodes that as a ceiling per role, and a structured handoff when the ceiling is hit.

Confidence never raises a ceiling. A T0 that is sure about an auth change is still a T0 touching auth.

Install

Claude Code

git clone https://github.com/khuynh22/agent-dev-team.git
cd agent-dev-team
./scripts/install.sh

On Windows:

pwsh scripts/install.ps1

This registers the repository as a local marketplace and installs it as a plugin, so everything is namespaced (/agent-dev-team:team) and uninstalling is one command. Add --mode copy to place files in ~/.claude/skills/ and ~/.claude/agents/ instead.

Other tools

./scripts/install.sh --target codex --target gemini --target cursor

Skills are copied to that tool's skills directory. For the role definitions, point the tool at AGENTS.md in this repository — it carries the roster, the routing table, and the escalation protocol as plain text.

Per-tool notes: docs/.

Use

/agent-dev-team:team    add rate limiting to the upload endpoint

It classifies the work, names the role and the workflow, and stops for confirmation before starting.

Without slash commands, ask for a role or a skill by name, or read AGENTS.md.

The handoff packet

The thing that makes the ladder work rather than decorate. An escalation without this is incomplete work, not a judgement call.

## HANDOFF
- **From / To:** intern-engineer (T0) -> software-engineer (T1)
- **Trigger:** security-surface
- **Task as given:** Replace session tokens with JWTs across the service.
- **Done so far:** Nothing. Stopped before editing.
- **Files touched:** none
- **Blocking question:** Should token verification stay in middleware.js, or move behind a
  new auth boundary?
- **Options considered:** A: in place, smallest diff. B: new module, testable. I would
  pick B.
- **Reversibility:** reversible
- **Evidence:** src/routes.js:1 imports middleware directly; 4 files touch auth.

Downward delegation has a matching BRIEF block. A T0 brief missing any field is itself an escalation trigger — under-specified delegation is the delegator's defect.

Roster

Direction — product-manager, tech-lead

Ladder — intern-engineer, software-engineer, senior-engineer, principal-engineer

Gates — code-reviewer, test-engineer, security-auditor, performance-engineer

Production — sre, incident-commander

Firmware — firmware-engineer, board-bringup-engineer

Frontend — frontend-engineer, ux-reviewer

Data — data-engineer, analytics-engineer, data-analyst, ml-engineer

Support — docs-engineer

Skills

Define requirements-interview · spec-writing

Plan work-breakdown · architecture-decision · api-design

Build tdd-loop · incremental-delivery · frontend-build · firmware-build · data-pipeline · data-modeling · ml-lifecycle

Verify systematic-debugging · browser-verification

Review code-review-pass · simplification-pass · security-hardening · performance-pass · data-quality · data-analysis

Ship release-and-rollback · incident-response · documentation

Meta using-agent-dev-team · team-escalation · autonomous-relay

Checklists in references/ load only when a workflow points to one, so they cost nothing until they are needed.

Testing

npm test                                     # static validation + routing evals, free
node scripts/run-evals.js --behavioral       # list behavioral cases
node scripts/run-evals.js --behavioral intern-ceiling

Four tiers, described in docs/test-plan.md: static validation, routing evals, behavioral evals with planted traps, and a 14 scenario manual pass with a per-tool scorecard.

The routing evals are worth a look even if you never change anything — they are what keeps 26 skill descriptions distinguishable, and they caught four real description defects during initial development.

Portability, concretely

The Agent Skills spec permits exactly six frontmatter fields: name, description, license, compatibility, metadata, allowed-tools. Any other key is a hard error on claude.ai upload and the Skills API. So:

• skills/ stays spec-pure. Tier and ownership data lives in metadata, which the spec allows, and hosts ignore. scripts/validate.js enforces this.
• agents/ carries Claude Code fields (model, effort, tools, color), because it is a Claude Code file format, not a spec file. The body of each agent file is plain markdown that any tool can use.
• AGENTS.md carries everything a tool needs with no file format at all.

The one thing Claude Code does that others cannot is spawn subagents automatically. Everywhere else, a tier is a persona the model adopts and a protocol it follows — which is text, and text travels.

Contributing

See CONTRIBUTING.md

Prior art

The lifecycle structure, the anti-rationalization tables, and the tiered eval approach follow addyosmani/agent-skills. The tier ladder, the handoff and brief contracts, and the firmware and hardware tracks are this project's additions.