# Agent Authoring Guide

Guide for creating and customizing project agents.

---

## Overview

Agents are specialized AI assistants with defined roles, responsibilities, and constraints. Each agent has a specific purpose in the development workflow.

---

## Agent Catalog

> Models below reflect the actual agent frontmatter (4 opus / 2 haiku / 24 sonnet). Keep this table in sync when you change an agent's `model:`.

### Cross-cutting quality

| Agent           | Purpose                                  | Model  |
| --------------- | ---------------------------------------- | ------ |
| code-simplifier | Reviews for over-engineering (report-only) | sonnet |

### Backend Track

| Agent                  | Purpose                                         | Model  |
| ---------------------- | ----------------------------------------------- | ------ |
| backend-architect      | Technical architecture (HOW)                    | opus   |
| backend-designer       | API contracts & schemas (WHAT)                  | sonnet |
| backend-developer      | Implementation (default Python/FastAPI persona) | sonnet |
| backend-test-developer | TDD red-phase test author                       | sonnet |
| backend-qa             | Test execution                                  | haiku  |
| backend-reviewer       | Code review (read-only)                         | sonnet |

### Frontend Track

| Agent                   | Purpose                                     | Model  |
| ----------------------- | ------------------------------------------- | ------ |
| frontend-architect      | Component architecture (HOW)                | opus   |
| frontend-designer       | UI/UX design (WHAT)                         | opus   |
| frontend-developer      | Implementation (default React/Next persona) | sonnet |
| frontend-test-developer | TDD red-phase test author                   | sonnet |
| frontend-qa             | E2E test execution                          | haiku  |
| frontend-reviewer       | Code review (read-only)                     | sonnet |

### Language Developers

One agent per language. Remove the ones your project's stack doesn't use (see [Removing Agents](#removing-agents)).

| Agent            | Stack          | Model  |
| ---------------- | -------------- | ------ |
| bash-developer   | Bash / shell   | sonnet |
| cpp-developer    | C / C++        | sonnet |
| csharp-developer | C# / .NET      | sonnet |
| dart-developer   | Dart / Flutter | sonnet |
| go-developer     | Go             | sonnet |
| java-developer   | Java / Spring  | sonnet |
| kotlin-developer | Kotlin         | sonnet |
| php-developer    | PHP / Laravel  | sonnet |
| ruby-developer   | Ruby / Rails   | sonnet |
| rust-developer   | Rust           | sonnet |
| swift-developer  | Swift          | sonnet |

### Cross-Cutting

| Agent               | Purpose                         | Model  |
| ------------------- | ------------------------------- | ------ |
| database-specialist | Schema, migrations              | sonnet |
| devops-engineer     | CI/CD, deployment               | sonnet |
| security-specialist | Security review (has authority) | opus   |
| integration-qa      | Cross-service testing           | sonnet |
| technical-writer    | Documentation                   | sonnet |

### Optional (AI/Bot)

| Agent         | Purpose                 | Model  |
| ------------- | ----------------------- | ------ |
| bot-developer | Bot / AI implementation | sonnet |

---

## Agent Structure

Every agent file follows this structure:

```markdown
---
name: agent-name
description: "Description with examples"
model: opus | sonnet
color: purple | green | etc
---

# Agent content

## Task Tracker Constants

[Pre-computed values]

## Global Exclusions

[Standard exclusion list]

## Your Role

[Agent responsibilities]

## Standards Reference

[Links to relevant standards]

## Completion Requirements

[What must be done before completion]
```

---

## Creating a New Agent

### 1. Choose a Template

Copy an existing agent that's closest to your needs:

- Developer: Start with `backend-developer.md` or `frontend-developer.md`
- Architect: Start with `backend-architect.md` or `frontend-architect.md`
- QA: Start with `backend-qa.md` or `frontend-qa.md`
- Reviewer: Start with `backend-reviewer.md` or `frontend-reviewer.md`

### 2. Update Frontmatter

```yaml
---
name: my-new-agent
description: "Clear description of what this agent does.

Examples:

<example>
Context: When to use this agent.
user: \"User request\"
assistant: \"How Claude responds\"
</example>"
model: opus  # or sonnet for simpler tasks
color: green  # choose a unique color
---
```

### 3. Define the Role

Clearly state:

- What the agent is responsible for
- What it is NOT responsible for
- When it should be invoked
- What it should produce

### 4. Add Standards References

Link to relevant standards documents:

```markdown
## Standards Reference

- Python: `standards/backend/python.md`
- Testing: `standards/backend/testing.md`
```

### 5. Define Completion Requirements

Be explicit about what must be done:

```markdown
## Completion Checklist

Before reporting complete:

- [ ] All acceptance criteria implemented
- [ ] Tests written and passing
- [ ] No linting errors
- [ ] No type errors
- [ ] Spec compliance verified
```

---

## Frontmatter Reference

| Field       | Required | Description                   |
| ----------- | -------- | ----------------------------- |
| name        | Yes      | Agent identifier (kebab-case) |
| description | Yes      | Purpose and examples          |
| model       | Yes      | `opus`, `sonnet`, or `haiku`  |
| color       | No       | UI color for agent            |

### Model Selection

| Model  | Use For                                                       |
| ------ | ------------------------------------------------------------- |
| opus   | Architecture, security review, UX judgment, complex synthesis |
| sonnet | Most implementation, contract/schema design, code review, TDD |
| haiku  | Bounded mechanical work: test execution, format-driven checks |

### Color Options

purple, green, blue, orange, yellow, red, pink, cyan, teal, lime, indigo, gray

---

## Best Practices

### Do

- Keep roles focused and specific
- Include clear examples in description
- Reference standards documents
- Define explicit completion criteria
- Include recovery instructions

### Don't

- Create agents with overlapping responsibilities
- Make agents too general
- Skip the standards references
- Forget completion requirements

---

## Removing Agents

Remove agents your project doesn't need:

```bash
# If no bot/AI services
rm .claude/agents/bot-developer.md

# If no frontend
rm .claude/agents/frontend-*.md

# If no backend
rm .claude/agents/backend-*.md
```

---

## Agent Hierarchy

When agents disagree, this hierarchy applies:

1. **security-specialist** - Wins on security matters
2. **architect** - Wins on architecture over developer
3. **designer** - Wins on UX/ergonomics
4. **reviewer** - Final say on code quality
5. **User** - Decides cross-domain conflicts

---

## Related Documentation

- [Skill Authoring](../skills/README.md)
- [Development Workflow](../../development-workflow.md)
- [CLAUDE.md](../../CLAUDE.md)
