Agents Reference
6 core agents and 6 pack agents: roles, models, allowed tools, and when to use each.
Overview
AI Craftsman Superpowers includes 6 core agents plus 6 pack agents, for 12 available with every pack loaded. Pack agents are symlinked into the roster by the pack loader at session start, so they appear only when their pack is enabled. Agents are invoked automatically by /craftsman:team or explicitly using the Agent tool.
Model tiers, as declared in each agent’s own frontmatter:
- Sonnet: every agent except one (quality and speed balance)
- Haiku:
doc-writer, the one repetitive-writing agent - Opus: not assigned to any agent. The Opus tier is used by skills that need judgment spanning files, not by agents
Read the frontmatter, not the role name
Each agent declares its own tool grant in tools:. Most craftsmen hold Write and Edit because their job is to change code. architect and team-lead hold neither. A role name does not imply read-only.
Cost optimization
Agent hooks (PreToolUse/PostToolUse) always use Haiku for cost control (~$0.15-0.30/session). Sonnet agents are only invoked for explicit commands.
Core Agents
team-lead - CTO-Level Orchestrator
| Property | Value |
|---|---|
| Model | Sonnet |
| Memory | User + Project |
| Max turns | 50 |
| Allowed tools | Read, Glob, Grep, Bash, Agent, TeamCreate, TaskCreate, TaskList, TaskUpdate, SendMessage, craftsman:plan, craftsman:challenge, craftsman:verify, craftsman:team. No Write, no Edit |
The team-lead is the top-level orchestrator for complex multi-step tasks. It:
- Manages other agents via delegation
- Maintains project context across sessions
- Makes architectural decisions
- Challenges suboptimal approaches
When to use:
/craftsman:team feature # team-lead orchestrates the full feature
/craftsman:plan execute-with-agentsarchitect - DDD/Clean Architecture Validator
| Property | Value |
|---|---|
| Model | Sonnet |
| Memory | Project |
| Max turns | 20 |
| Allowed tools | Read, Glob, Grep, Bash, Agent, craftsman:design, craftsman:challenge. No Write, no Edit |
The architect validates dependency direction, bounded contexts, aggregate boundaries, and Clean Architecture layer violations. Read-only - never writes or edits code.
Validates:
- Layer imports (Domain → nothing, Application → Domain, Infrastructure → both)
- Aggregate boundaries (no cross-aggregate direct references)
- Domain model purity (no infrastructure in Domain layer)
- DDD tactical patterns (Entity, Value Object, Aggregate, Repository)
When to use:
/craftsman:challenge Review the current architecture
/craftsman:team code-review # architect runs as part of the teamdoc-writer - Technical Documentation Specialist
| Property | Value |
|---|---|
| Model | Haiku |
| Memory | Project |
| Max turns | 20 |
| Allowed tools | Read, Glob, Grep, Write, Edit |
Generates and reviews API docs (OpenAPI), ADRs, READMEs, runbooks, and user guides. Verifies documentation accuracy against actual code.
When to use:
/craftsman:team code-review # doc-writer checks documentation gapssecurity-pentester - OWASP Top 10 Auditor
| Property | Value |
|---|---|
| Model | Sonnet |
| Memory | Project |
| Max turns | 20 |
| Allowed tools | Read, Glob, Grep, Bash, Write. No Edit |
Performs automated + manual security analysis focused on OWASP Top 10, SQL injection, XSS, authentication flaws, and API security.
Checks:
- SQL injection (parameterized queries)
- XSS (output encoding)
- Authentication/authorization flaws
- Insecure direct object references
- Security misconfiguration
- Sensitive data exposure
When to use:
/craftsman:team security-audit # dedicated security pass
/craftsman:team code-review # security included in full reviewui-ux-director - Design System Guardian
| Property | Value |
|---|---|
| Model | Sonnet |
| Memory | Project |
| Max turns | 20 |
| Allowed tools | Read, Glob, Grep, Write. No Bash, no Edit |
Deep expertise in SaaS dashboard UX, data visualization, accessibility (WCAG 2.1 AA), and design token systems.
Validates:
- WCAG 2.1 AA compliance
- Design token usage (no hardcoded colors)
- Component consistency
- Keyboard navigation
- Screen reader compatibility
When to use:
/craftsman:team code-review # ui-ux reviews frontend componentslegacy-surgeon - Inherited Code Rescuer
| Property | Value |
|---|---|
| Model | Sonnet |
| Effort | High |
| Memory | Project |
| Isolation | Worktree |
| Max turns | 25 |
| Allowed tools | Read, Glob, Grep, Bash, Write, Edit |
Brings untested, tangled, inherited code under control without breaking it. Characterizes behavior first, breaks dependencies with seams, refactors under a net, and migrates with strangler fig. Never rewrites from scratch.
When to use:
/craftsman:legacy audit # rank hotspots, produce LEGACY-AUDIT.md
/craftsman:legacy cover # characterization net before touching anything
/craftsman:legacy untangle # break dependencies
/craftsman:legacy migrate # strangler figRuns in its own git worktree, so a rescue in progress never blocks your working tree.
Pack Agents
Pack agents are symlinked into the roster by the pack loader at session start, and appear only when the corresponding pack is enabled.
backend-craftsman (Symfony Pack)
| Property | Value |
|---|---|
| Model | Sonnet |
| Pack | symfony |
| Expertise | Symfony 7/8, API Platform 4, Doctrine ORM, Messenger, PHPUnit |
Deep PHP/Symfony expertise. Validates DDD tactical patterns, Symfony service configuration, Doctrine entity design, and API Platform resources.
When enabled: All PHP file writes trigger backend validation via agent hooks.
frontend-craftsman (React Pack)
| Property | Value |
|---|---|
| Model | Sonnet |
| Pack | react |
| Expertise | React 19, TypeScript, Tailwind, shadcn/ui, TanStack Query |
Deep React/TypeScript expertise. Validates component design, hook patterns, type safety, and accessibility.
When enabled: All .tsx/.ts file writes trigger frontend validation via agent hooks.
ai-engineer (AI/ML Pack)
| Property | Value |
|---|---|
| Model | Sonnet |
| Pack | ai-ml |
| Expertise | RAG pipelines, pgvector, embeddings, LLM integration, MLOps |
AI/ML specialist for RAG pipeline design, embedding strategies, vector database integration, prompt engineering, and MLOps practices.
When enabled: Unlocks /craftsman:rag, /craftsman:mlops, /craftsman:agent-design.
api-craftsman (Symfony Pack)
| Property | Value |
|---|---|
| Model | Sonnet |
| Effort | Medium |
| Pack | symfony |
| Max turns | 30 |
| Allowed tools | Read, Glob, Grep, Bash, Agent, Edit, Write, craftsman:spec, craftsman:test |
| Expertise | API Platform 4, REST and HATEOAS, OpenAPI, JSON-LD and Hydra, OAuth2 and JWT |
Senior API architect. Use for API design reviews, API Platform configuration, and RESTful architecture decisions. Holds Write and Edit: it changes code.
symfony-reviewer (Symfony Pack)
| Property | Value |
|---|---|
| Model | Sonnet |
| Effort | Medium |
| Pack | symfony |
| Max turns | 15 |
| Allowed tools | Read, Glob, Grep, Bash, Edit, craftsman:challenge |
Review specialist for Symfony applications: PHP code, Doctrine entities, Symfony services. Despite the name, it holds Edit and can patch what it finds.
react-reviewer (React Pack)
| Property | Value |
|---|---|
| Model | Sonnet |
| Effort | Medium |
| Pack | react |
| Max turns | 15 |
| Allowed tools | Read, Glob, Grep, Bash, Edit, craftsman:challenge |
Review specialist for React and TypeScript: components, hooks, type safety. Despite the name, it holds Edit and can patch what it finds.
Agent Teams
Use /craftsman:team to orchestrate multiple agents together:
/craftsman:team code-review
# → architect + security-pentester + doc-writer run in parallel
# → team-lead synthesizes findings
/craftsman:team feature
# → team-lead orchestrates: architect (design) → backend/frontend (implement) → verify
/craftsman:team security-audit
# → security-pentester does a comprehensive OWASP deep diveParallel execution
When using /craftsman:team code-review, architect, security-pentester, and doc-writer run in parallel using separate agent contexts. This reduces review time by 60-70% compared to sequential review.