# Agents

> **Specialized AI agents for software engineering workflows.**

Agents are autonomous specialists that handle specific domains of software development. They can be invoked manually via commands or auto-invoked based on context.

---

## Available Agents

| Agent | Purpose | Command | Auto-Invokes |
|-------|---------|---------|--------------|
| [architect](./architect.md) | System design and ADRs | `/architect` | On new features |
| [build-error-resolver](./build-error-resolver.md) | Fix build/type errors | `/build-fix` | On build failures |
| [code-reviewer](./code-reviewer.md) | Automated code review | `/code-review` | After code changes |
| [doc-updater](./doc-updater.md) | Keep docs in sync | `/update-docs` | On API changes |
| [e2e-runner](./e2e-runner.md) | E2E test generation | `/e2e` | On UI features |
| [planner](./planner.md) | Implementation planning | `/plan` | On feature requests |
| [refactor-cleaner](./refactor-cleaner.md) | Dead code removal | `/refactor-clean` | On cleanup requests |
| [security-reviewer](./security-reviewer.md) | Security analysis | `/security-review` | On auth/input code |
| [tdd-guide](./tdd-guide.md) | Test-driven development | `/tdd` | On all implementations |

---

## How Agents Work

### Manual Invocation
```bash
/plan add user authentication
/code-review
/security-review --secrets
```

### Auto-Invocation
Agents auto-invoke when their triggers are detected:

```
User: "Add a login form to the dashboard"
       ↓
[Planner Agent] Creates implementation plan
       ↓
[TDD Guide] Ensures tests written first
       ↓
[Code Reviewer] Reviews after implementation
       ↓
[Security Reviewer] Checks auth code
```

---

## Agent Orchestration

Agents can invoke other agents as needed:

```
Architect → Planner → TDD Guide → Code Reviewer
                ↓
         Security Reviewer
                ↓
         Doc Updater
```

Use `/orchestrate` to run a full workflow.

---

## Language Support

All agents support both Python and TypeScript/JavaScript:

| Feature | Python | TypeScript |
|---------|--------|------------|
| Testing | pytest | Jest/Vitest |
| Linting | ruff | ESLint |
| Types | mypy | tsc |
| Formatting | ruff format | Prettier |
| E2E | playwright | Playwright |

---

## Configuration

Agent behavior can be configured in `.claude/settings.json`:

```json
{
  "agents": {
    "autoInvoke": true,
    "codeReviewer": {
      "severityThreshold": "MEDIUM"
    },
    "tddGuide": {
      "coverageTarget": 80
    }
  }
}
```

---

## Creating Custom Agents

To create a new agent:

1. Create `agents/<agent-name>.md`
2. Define purpose, triggers, and capabilities
3. Add to this README
4. Create corresponding command in `commands/`

Template:
```markdown
# Agent Name

> **Purpose:** One-line description

## When to Use
[Triggers and invocation]

## Capabilities
[What it does]

## Integration with Other Agents
[How it works with others]
```

---

## Best Practices

1. **Let agents work** - Trust the orchestration
2. **Review outputs** - Agents assist, you decide
3. **Customize thresholds** - Adjust for your project
4. **Combine agents** - Use `/orchestrate` for full workflows
