Agent Personas
Specialist personas that play a single role with a single perspective. Each persona is a Markdown file consumed as a system prompt by your harness (Claude Code, Cursor, Copilot, etc.).
| Persona | Role | Best for |
|---|
| code-reviewer | Senior Staff Engineer | Five-axis review before merge |
| security-auditor | Security Engineer | Vulnerability detection, OWASP-style audit |
| test-engineer | QA Engineer | Test strategy, coverage analysis, Prove-It pattern |
How personas relate to skills and commands
Three layers, each with a distinct job:
| Layer | What it is | Example | Composition role |
|---|
| Skill | A workflow with steps and exit criteria | code-review-and-quality | The how — invoked from inside a persona or command |
| Persona | A role with a perspective and an output format | code-reviewer | The who — adopts a viewpoint, produces a report |
| Command | A user-facing entry point | /review, /ship | The when — composes personas and skills |
The user (or a slash command) is the orchestrator. Personas do not call other personas. Skills are mandatory hops inside a persona's workflow.
When to use each
Direct persona invocation
Pick this when you want one perspective on the current change and the user is in the loop.
- "Review this PR" → invoke
code-reviewer directly
- "Are there security issues in
auth.ts?" → invoke security-auditor directly
- "What tests are missing for the checkout flow?" → invoke
test-engineer directly
Slash command (single persona behind it)
Pick this when there's a repeatable workflow you'd otherwise re-explain every time.
/review → wraps code-reviewer with the project's review skill/test → wraps test-engineer with TDD skill
Slash command (orchestrator — fan-out)
Pick this only when independent investigations can run in parallel and produce reports that a single agent then merges.
/ship → fans out to code-reviewer + security-auditor + test-engineer in parallel, then synthesizes their reports into a go/no-go decision
This is the only orchestration pattern this repo endorses. See references/orchestration-patterns.md for the full pattern catalog and anti-patterns.
Decision matrix
Is the work a single perspective on a single artifact?
├── Yes → Direct persona invocation
└── No → Are the sub-tasks independent (no shared mutable state, no ordering)?
├── Yes → Slash command with parallel fan-out (e.g. /ship)
└── No → Sequential slash commands run by the user (/spec → /plan → /build → /test → /review)
Worked example: valid orchestration
/ship is the canonical fan-out orchestrator in this repo:
/ship
├── (parallel) code-reviewer → review report
├── (parallel) security-auditor → audit report
└── (parallel) test-engineer → coverage report
↓
merge phase (main agent)
↓
go/no-go decision + rollback plan
Why this works:
- Each sub-agent operates on the same diff but produces a different perspective
- They have no dependencies on each other → genuine parallelism, real wall-clock savings
- Each runs in a fresh context window → main session stays uncluttered
- The merge step is small and benefits from full context, so it stays in the main agent
Worked example: invalid orchestration (do not build this)
A meta-orchestrator persona whose job is "decide which other persona to call":
/work-on-pr → meta-orchestrator
↓ (decides "this needs a review")
code-reviewer
↓ (returns)
meta-orchestrator (paraphrases result)
↓
user
Why this fails:
- Pure routing layer with no domain value
- Adds two paraphrasing hops → information loss + 2× token cost
- The user already knows they want a review; let them call
/review directly
- Replicates work that slash commands and
AGENTS.md intent-mapping already do
Rules for personas
- A persona is a single role with a single output format. If you find yourself adding a second role, create a second persona.
- Personas do not invoke other personas. Composition is the job of slash commands or the user. On Claude Code this is also a hard platform constraint — "subagents cannot spawn other subagents" — so the rule is enforced for you.
- A persona may invoke skills (the how).
- Every persona file ends with a "Composition" block stating where it fits.
Claude Code interop
The personas in this repo are designed to work as Claude Code subagents and as Agent Teams teammates without modification:
- As subagents: auto-discovered when this plugin is enabled (no path config needed). Use the Agent tool with
subagent_type: code-reviewer (or security-auditor, test-engineer). /ship is the canonical example.
- As Agent Teams teammates (experimental, requires
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1): reference the same persona name when spawning a teammate. The persona's body is appended to the teammate's system prompt as additional instructions (not a replacement), so your persona text sits on top of the team-coordination instructions the lead installs (SendMessage, task-list tools, etc.).
Subagents only report results back to the main agent. Agent Teams let teammates message each other directly. Use subagents when reports are enough; use Agent Teams when sub-agents need to challenge each other's findings (e.g. competing-hypothesis debugging). See references/orchestration-patterns.md for the full mapping.
Plugin agents do not support hooks, mcpServers, or permissionMode frontmatter — those fields are silently ignored. Avoid relying on them when authoring new personas here.
Adding a new persona
- Create
agents/<role>.md with the same frontmatter format used by existing personas.
- Define the role, scope, output format, and rules.
- Add a Composition block at the bottom (Invoke directly when / Invoke via / Do not invoke from another persona).
- Add the persona to the table at the top of this file.
- If the persona enables a new orchestration pattern, document it in
references/orchestration-patterns.md rather than inventing the pattern in the persona file itself.