architecture/docs/writing-agents.md

# Writing Agents

A guide to creating specialized subagents that combine multiple skills for complex, context-isolated tasks.

## What is an Agent?

Agents are **specialized subprocesses** that combine multiple skills into focused personas. Unlike commands (which define workflows) or skills (which encode knowledge), agents are autonomous workers that can handle complex tasks independently.

Think of agents as specialists you can delegate work to. They have their own context, their own expertise (via skills), and they report back when finished.

## File Structure

Agents live in the `agents/` directory, each in its own folder:

```
agents/
└── product-manager/
    └── AGENT.md
```

### Why AGENT.md?

The uppercase `AGENT.md` filename:
- Makes the agent file immediately visible in directory listings
- Follows a consistent convention across all agents
- Clearly identifies the primary file in an agent folder

### Supporting Files (Optional)

An agent folder can contain additional files if needed:

```
agents/
└── code-reviewer/
    ├── AGENT.md           # Main agent document (required)
    └── checklists/        # Supporting materials
        └── security.md
```

However, prefer keeping everything in `AGENT.md` when possible—agent definitions should be concise.

## Agent Document Structure

A well-structured `AGENT.md` follows this pattern:

```markdown
# Agent Name

Brief description of what this agent does.

## Skills
List of skills this agent has access to.

## Capabilities
What the agent can do—its areas of competence.

## When to Use
Guidance on when to spawn this agent.

## Behavior
How the agent should operate—rules and constraints.
```

All sections are important:
- **Skills**: Defines what knowledge the agent has
- **Capabilities**: Tells spawners what to expect
- **When to Use**: Prevents misuse and guides selection
- **Behavior**: Sets expectations for operation

## How Agents Combine Skills

Agents gain their expertise by combining multiple skills. Each skill contributes domain knowledge to the agent's overall capability.

### Skill Composition

```
┌────────────────────────────────────────────────┐
│           Product Manager Agent                │
│                                                │
│  ┌──────────┐  ┌──────────────┐                │
│  │ gitea  │  │issue-writing │                │
│  │          │  │              │                │
│  │ CLI      │  │ Structure    │                │
│  │ commands │  │ patterns     │                │
│  └──────────┘  └──────────────┘                │
│                                                │
│  ┌──────────────────┐  ┌─────────────────┐     │
│  │backlog-grooming  │  │roadmap-planning │     │
│  │                  │  │                 │     │
│  │ Review           │  │ Feature         │     │
│  │ checklists       │  │ breakdown       │     │
│  └──────────────────┘  └─────────────────┘     │
│                                                │
└────────────────────────────────────────────────┘
```

The agent can:
- Use **gitea** to interact with issues and PRs
- Apply **issue-writing** patterns when creating content
- Follow **backlog-grooming** checklists when reviewing
- Use **roadmap-planning** strategies when breaking down features

### Emergent Capabilities

When skills combine, new capabilities emerge:

| Skills Combined | Emergent Capability |
|-----------------|---------------------|
| gitea + issue-writing | Create well-structured issues programmatically |
| backlog-grooming + issue-writing | Improve existing issues systematically |
| roadmap-planning + gitea | Plan and create linked issue hierarchies |
| All four skills | Full backlog management lifecycle |

## Use Cases for Agents

### 1. Parallel Processing

Agents work independently with their own context. Spawn multiple agents to work on separate tasks simultaneously.

```
Command: /groom (batch mode)
         │
         ├─── Spawn Agent: Review issues #1-5
         │
         ├─── Spawn Agent: Review issues #6-10
         │
         └─── Spawn Agent: Review issues #11-15

         ↓ (agents work in parallel)

Results aggregated by command
```

**Use when:**
- Tasks are independent and don't need to share state
- Workload can be divided into discrete chunks
- Speed matters more than sequential consistency

### 2. Context Isolation

Each agent maintains separate conversation state. This prevents context pollution when handling complex, unrelated subtasks.

```
Main Context                    Agent Context
┌─────────────────┐            ┌─────────────────┐
│ User working on │            │ Isolated work   │
│ feature X       │   spawn    │ on backlog      │
│                 │ ─────────► │ review          │
│ (preserves      │            │                 │
│  feature X      │   return   │ (doesn't know   │
│  context)       │ ◄───────── │  about X)       │
└─────────────────┘            └─────────────────┘
```

**Use when:**
- Subtask requires deep exploration that would pollute main context
- Work involves many files or concepts unrelated to main task
- You want clean separation between different concerns

### 3. Complex Workflows

Some workflows are better handled by a specialized agent than by inline execution. Agents can make decisions, iterate, and adapt.

```
Command: /plan-issues "add user authentication"
         │
         └─── Spawn product-manager agent
                   │
                   ├── Explore codebase to understand structure
                   ├── Research authentication patterns
                   ├── Design issue breakdown
                   ├── Create issues in dependency order
                   └── Return summary to command
```

**Use when:**
- Task requires iterative decision-making
- Workflow has many steps that depend on intermediate results
- Specialist expertise (via combined skills) adds value

### 4. Autonomous Exploration

Agents can explore codebases independently, building understanding without polluting the main conversation.

**Use when:**
- You need to understand a new part of the codebase
- Exploration might involve many file reads and searches
- Results should be summarized, not shown in full

## When to Use an Agent vs Direct Skill Invocation

### Use Direct Skill Invocation When:

- **Simple, single-skill task**: Writing one issue doesn't need an agent
- **Main context is relevant**: The current conversation context helps
- **Quick reference needed**: Just need to check a pattern or command
- **Sequential workflow**: Command can orchestrate step-by-step

Example: Creating a single issue with `/create-issue`
```
Command reads issue-writing skill directly
         │
         └── Creates one issue following patterns
```

### Use an Agent When:

- **Multiple skills needed together**: Complex tasks benefit from composition
- **Context isolation required**: Don't want to pollute main conversation
- **Parallel execution possible**: Can divide and conquer
- **Autonomous exploration needed**: Agent can figure things out independently
- **Specialist persona helps**: "Product manager" framing improves outputs

Example: Grooming entire backlog with `/groom`
```
Command spawns product-manager agent
         │
         └── Agent iterates through all issues
             using multiple skills
```

### Decision Matrix

| Scenario | Agent? | Reason |
|----------|--------|--------|
| Create one issue | No | Single skill, simple task |
| Review 20 issues | Yes | Batch processing, isolation |
| Quick CLI lookup | No | Just need gitea reference |
| Plan new feature | Yes | Multiple skills, exploration |
| Fix issue title | No | Trivial edit |
| Reorganize backlog | Yes | Complex, multi-skill workflow |

## Annotated Example: Product Manager Agent

Let's examine the `product-manager` agent in detail:

```markdown
# Product Manager Agent

Specialized agent for backlog management and roadmap planning.
```

**The opening** identifies the agent's role clearly. "Product Manager" is a recognizable persona that sets expectations.

```markdown
## Skills

- gitea
- issue-writing
- backlog-grooming
- roadmap-planning
```

**Skills section** lists all knowledge the agent has access to. These skills are loaded into the agent's context when spawned. The combination enables:
- Reading/writing issues (gitea)
- Creating quality content (issue-writing)
- Evaluating existing issues (backlog-grooming)
- Planning work strategically (roadmap-planning)

```markdown
## Capabilities

This agent can:
- Review and improve existing issues
- Create new well-structured issues
- Analyze the backlog for gaps and priorities
- Plan feature breakdowns
- Maintain roadmap clarity
```

**Capabilities section** tells spawners what to expect. Each capability maps to skill combinations:
- "Review and improve" = backlog-grooming + issue-writing
- "Create new issues" = gitea + issue-writing
- "Analyze backlog" = backlog-grooming + roadmap-planning
- "Plan breakdowns" = roadmap-planning + issue-writing

```markdown
## When to Use

Spawn this agent for:
- Batch operations on multiple issues
- Comprehensive backlog reviews
- Feature planning that requires codebase exploration
- Complex issue creation with dependencies
```

**When to Use section** guides appropriate usage. Note the criteria:
- "Batch operations" → Parallel/isolation benefit
- "Comprehensive reviews" → Complex workflow benefit
- "Requires exploration" → Context isolation benefit
- "Complex with dependencies" → Multi-skill benefit

```markdown
## Behavior

- Always fetches current issue state before making changes
- Asks for approval before creating or modifying issues
- Provides clear summaries of actions taken
- Uses the tea CLI for all Forgejo operations
```

**Behavior section** sets operational rules. These ensure:
- Accuracy: Fetches current state, doesn't assume
- Safety: Asks before acting
- Transparency: Summarizes what happened
- Consistency: Uses standard tooling

## Naming Conventions

### Agent Folder Names

- Use **kebab-case**: `product-manager`, `code-reviewer`
- Name by **role or persona**: what the agent "is"
- Keep **recognizable**: familiar roles are easier to understand

Good names:
- `product-manager` - Recognizable role
- `code-reviewer` - Clear function
- `security-auditor` - Specific expertise
- `documentation-writer` - Focused purpose

Avoid:
- `helper` - Too vague
- `do-stuff` - Not a role
- `issue-thing` - Not recognizable

### Agent Titles

The H1 title in `AGENT.md` should be the role name in Title Case:

| Folder | Title |
|--------|-------|
| `product-manager` | Product Manager Agent |
| `code-reviewer` | Code Reviewer Agent |
| `security-auditor` | Security Auditor Agent |

## Model Selection

Agents can specify which Claude model to use via the `model` field in YAML frontmatter. Choosing the right model balances capability, speed, and cost.

### Available Models

| Model | Characteristics | Best For |
|-------|-----------------|----------|
| `haiku` | Fastest, most cost-effective | Simple structured tasks, formatting, basic transformations |
| `sonnet` | Balanced speed and capability | Most agent tasks, code review, issue management |
| `opus` | Most capable, best reasoning | Complex analysis, architectural decisions, nuanced judgment |
| `inherit` | Uses parent context's model | When agent should match caller's capability level |

### Decision Matrix

| Agent Task Type | Recommended Model | Reasoning |
|-----------------|-------------------|-----------|
| Structured output formatting | `haiku` | Pattern-following, no complex reasoning |
| Code review (style/conventions) | `sonnet` | Needs code understanding, not deep analysis |
| Security vulnerability analysis | `opus` | Requires nuanced judgment, high stakes |
| Issue triage and labeling | `haiku` or `sonnet` | Mostly classification tasks |
| Feature planning and breakdown | `sonnet` or `opus` | Needs strategic thinking |
| Batch processing (many items) | `haiku` or `sonnet` | Speed and cost matter at scale |
| Architectural exploration | `opus` | Complex reasoning about tradeoffs |

### Examples

These examples show recommended model configurations for different agent types:

**Code Reviewer Agent** - Use `sonnet`:
```yaml
---
name: code-reviewer
model: sonnet
skills: gitea, code-review
---
```
Code review requires understanding code patterns and conventions but rarely needs the deepest reasoning. Sonnet provides good balance.

**Security Auditor Agent** (hypothetical) - Use `opus`:
```yaml
---
name: security-auditor
model: opus
skills: code-review  # would add security-specific skills
---
```
Security analysis requires careful, nuanced judgment where missing issues have real consequences. Worth the extra capability.

**Formatting Agent** (hypothetical) - Use `haiku`:
```yaml
---
name: markdown-formatter
model: haiku
skills: documentation
---
```
Pure formatting tasks follow patterns and don't require complex reasoning. Haiku is fast and sufficient.

### Best Practices for Model Selection

1. **Start with `sonnet`** - It handles most agent tasks well
2. **Use `haiku` for volume** - When processing many items, speed and cost add up
3. **Reserve `opus` for judgment** - Use when errors are costly or reasoning is complex
4. **Avoid `inherit` by default** - Make a deliberate choice; `inherit` obscures the decision
5. **Consider the stakes** - Higher consequence tasks warrant more capable models
6. **Test with real tasks** - Verify the chosen model performs adequately

### When to Use `inherit`

The `inherit` option has legitimate uses:

- **Utility agents**: Small helpers that should match their caller's capability
- **Delegation chains**: When an agent spawns sub-agents that should stay consistent
- **Testing/development**: When you want to control model from the top level

However, most production agents should specify an explicit model.

## Best Practices

### 1. Choose Skills Deliberately

Include only skills the agent needs. More skills = more context = potential confusion.

**Too many skills:**
```markdown
## Skills
- gitea
- issue-writing
- backlog-grooming
- roadmap-planning
- code-review
- testing
- documentation
- deployment
```

**Right-sized:**
```markdown
## Skills
- gitea
- issue-writing
- backlog-grooming
- roadmap-planning
```

### 2. Define Clear Boundaries

Agents should know what they can and cannot do.

**Vague:**
```markdown
## Capabilities
This agent can help with project management.
```

**Clear:**
```markdown
## Capabilities
This agent can:
- Review and improve existing issues
- Create new well-structured issues
- Analyze the backlog for gaps

This agent cannot:
- Merge pull requests
- Deploy code
- Make architectural decisions
```

### 3. Set Behavioral Guardrails

Prevent agents from causing problems by setting explicit rules.

**Important behaviors to specify:**
- When to ask for approval
- What to do before making changes
- How to report results
- Error handling expectations

### 4. Match Persona to Purpose

The agent's name and description should align with its skills and capabilities.

**Mismatched:**
```markdown
# Security Agent

## Skills
- issue-writing
- documentation
```

**Aligned:**
```markdown
# Security Auditor Agent

## Skills
- security-scanning
- vulnerability-assessment
- code-review
```

### 5. Keep Agents Focused

One agent = one role. If an agent does too many unrelated things, split it.

**Too broad:**
```markdown
# Everything Agent
Handles issues, code review, deployment, and customer support.
```

**Focused:**
```markdown
# Product Manager Agent
Specialized for backlog management and roadmap planning.
```

## When to Create a New Agent

Create an agent when you need:

1. **Role-based expertise**: A recognizable persona improves outputs
2. **Skill composition**: Multiple skills work better together
3. **Context isolation**: Work shouldn't pollute main conversation
4. **Parallel capability**: Tasks can run independently
5. **Autonomous operation**: Agent should figure things out on its own

### Signs You Need a New Agent

- Commands repeatedly spawn similar skill combinations
- Tasks require deep exploration that pollutes context
- Work benefits from a specialist "persona"
- Batch processing would help

### Signs You Don't Need a New Agent

- Single skill is sufficient
- Task is simple and sequential
- Main context is helpful, not harmful
- No clear persona or role emerges

## Agent Lifecycle

### 1. Design

Define the agent's role:
- What persona makes sense?
- Which skills does it need?
- What can it do (and not do)?
- When should it be spawned?

### 2. Implement

Create the agent file:
- Clear name and description
- Appropriate skill list
- Specific capabilities
- Usage guidance
- Behavioral rules

### 3. Integrate

Connect the agent to workflows:
- Update commands that should spawn it
- Document in ARCHITECTURE.md
- Test with real tasks

### 4. Refine

Improve based on usage:
- Add/remove skills as needed
- Clarify capabilities
- Strengthen behavioral rules
- Update documentation

## Checklist: Before Submitting a New Agent

- [ ] File is at `agents/<name>/AGENT.md`
- [ ] Name follows kebab-case convention
- [ ] Agent has a clear, recognizable role
- [ ] Skills list is deliberate (not too many, not too few)
- [ ] Model selection is deliberate (not just `inherit` by default)
- [ ] Capabilities are specific and achievable
- [ ] "When to Use" guidance is clear
- [ ] Behavioral rules prevent problems
- [ ] Agent is referenced by at least one command
- [ ] ARCHITECTURE.md is updated

## See Also

- [ARCHITECTURE.md](../ARCHITECTURE.md): How agents fit into the overall system
- [writing-skills.md](writing-skills.md): Creating the skills that agents use
- [VISION.md](../VISION.md): The philosophy behind composable components