# AI Sub-Agents

Sub-agents are specialized AI instances launched inside pipelines. Each agent has a focused role, its own tool set, and returns a structured report to the orchestrator.

Source files: `.claude/agents/`

---

## Agent Reference

| Agent | Role | Used in |
|-------|------|---------|
| `code-architect` | Designs feature architectures by analyzing existing codebase patterns and conventions. Produces implementation blueprints with specific files to create/modify, component designs, data flows, and build sequences. | `/specification`, `/feature` |
| `code-explorer` | Deeply analyzes existing codebase features by tracing execution paths, mapping architecture layers, understanding patterns and abstractions, and documenting dependencies. | `/specification`, `/feature`, `/improvement` |
| `code-implementer` | Implements a single spec sub-task in isolation, keeping the orchestrator's context lean. Receives a focused brief, edits only the files listed in the code map, checks lints, and returns a structured report. | `/implement`, `/feature`, `/improvement` |
| `code-reviewer` | Reviews code for bugs, logic errors, security vulnerabilities, code quality issues, and adherence to project conventions. Uses confidence-based filtering — reports only high-priority issues. | `/implement`, `/feature`, `/improvement` |
| `docs-author` | Maps, summarizes, or updates `docs/` (design/spec, modules, architecture, infrastructure, testing). Operates in three modes: mapping early, working spec before implementation, final verification after code. | `/implement`, `/feature`, `/improvement`, `/documentation` |
| `test-author` | Plans and authors automated tests (PHPUnit, API/functional) by mirroring the existing project test layout. | `/implement`, `/feature`, `/improvement` |
| `api-docs-author` | Verifies that API implementation matches the documented spec (OpenAPI YAML) — controllers, DTOs, routes, responses. Flags deviations from documented contracts; skips cleanly when the feature is non-API. | `/implement`, `/feature`, `/improvement` |

---

## How agents are invoked

Agents are not called directly — they are launched by slash commands as parallel or sequential sub-tasks.

To understand which agent handles what, see [commands.md](commands.md).