# Agent Profiles

This directory contains specialized AI agent profiles. Each profile defines a role, principles, constraints, and workflow for a specific domain.

## Available Agents

| Agent                | File                      | Model  | Use When                                                 |
| -------------------- | ------------------------- | ------ | -------------------------------------------------------- |
| Planner              | `planner.md`              | opus   | Breaking down tasks, planning implementations, risk assessment |
| Frontend Architect   | `frontend-architect.md`   | opus   | UI components, performance, accessibility, React/Next.js |
| Backend Architect    | `backend-architect.md`    | opus   | System design, databases, APIs, scalability              |
| Security Auditor     | `security-auditor.md`     | opus   | Security review, vulnerability assessment, auth flows    |
| Code Reviewer        | `code-reviewer.md`        | sonnet | Code quality, PR review, best practices                  |
| Test Engineer        | `test-engineer.md`        | sonnet | Test strategy, automation, CI/CD, coverage               |
| Prompt Engineer      | `prompt-engineer.md`      | sonnet | LLM prompts, agent instructions, prompt optimization     |
| Documentation Expert | `documentation-expert.md` | sonnet | Technical writing, user/admin guides, docs maintenance   |
| Build Error Resolver | `build-error-resolver.md` | sonnet | Fix build/type/lint errors with minimal changes          |
| Loop Operator        | `loop-operator.md`        | sonnet | Monitor autonomous loops, detect stalls, escalate        |

## Model Selection

- **opus** — Deep reasoning tasks: planning, architecture, security review. Slower but more thorough.
- **sonnet** — Implementation tasks: code review, testing, writing, fixing. Faster turnaround.

## Tool Restrictions

Each agent declares a `tools` array in its frontmatter, following the principle of least privilege:
- **Read-only agents** (planner, architects): Read, Glob, Grep — they advise, not implement
- **Implementation agents** (test-engineer, build-error-resolver): Read, Glob, Grep, Edit, Write, Bash
- **Review agents** (code-reviewer): Read, Glob, Grep, Bash (for git commands)

## Agent Selection

See `RULES.md` sections 4-5 for the selection protocol and multi-agent coordination.

## Using context7 (Shared Guidelines)

All agents use context7 to access up-to-date documentation. Training data may be outdated — always verify through context7 before making recommendations.

### When to Use

**Always query context7 before:**

- Recommending specific library/framework versions
- Suggesting API patterns or method signatures
- Advising on security configurations or CVEs
- Checking for deprecated features or breaking changes
- Verifying browser support or compatibility matrices

### How to Use

1. **Resolve library ID**: Use `resolve-library-id` to find the correct context7 library identifier
2. **Query documentation**: Use `query-docs` with the resolved ID and a specific topic

### Example

```
User asks about React Server Components

1. resolve-library-id: "react" → get library ID
2. query-docs: topic="Server Components patterns"
3. Base recommendations on returned documentation, not training data
```

### What to Verify

| Category      | Verify                                                     |
| ------------- | ---------------------------------------------------------- |
| Versions      | LTS versions, deprecation timelines, migration guides      |
| APIs          | Current method signatures, new features, removed APIs      |
| Security      | CVE advisories, security best practices, auth patterns     |
| Performance   | Current optimization techniques, benchmarks, configuration |
| Compatibility | Version compatibility matrices, breaking changes           |

### Critical Rule

When context7 documentation contradicts training knowledge, **trust context7**. Technologies evolve rapidly — training data may reference deprecated patterns or outdated versions.

## Adding a New Agent

1. Create a new `.md` file in this directory
2. Use consistent frontmatter: `name`, `model`, `tools`, and `description`
   - `model`: `opus` for reasoning-heavy tasks, `sonnet` for implementation
   - `tools`: minimal set needed (principle of least privilege)
3. Follow the structure: Role → Core Principles → Constraints → Workflow → Responsibilities → Output Format → Pre-Response Checklist
4. Reference this README for context7 usage instead of duplicating the section
5. Update `DOCS.md` and `README.md` to list the new agent