Each persona now ends with a three-bullet block stating when to invoke it directly, which slash commands wrap it, and the rule that personas do not invoke other personas. Keeps the persona honest about its place in the workflow without re-stating the broader orchestration model.
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-reviewerdirectly - "Are there security issues in
auth.ts?" → invokesecurity-auditordirectly - "What tests are missing for the checkout flow?" → invoke
test-engineerdirectly
Slash command (single persona behind it)
Pick this when there's a repeatable workflow you'd otherwise re-explain every time.
/review→ wrapscode-reviewerwith the project's review skill/test→ wrapstest-engineerwith 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 tocode-reviewer+security-auditor+test-engineerin 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
/reviewdirectly - Replicates work that slash commands and
AGENTS.mdintent-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.
- A persona may invoke skills (the how).
- Every persona file ends with a "Composition" block stating where it fits.
Adding a new persona
- Create
agents/<role>.mdwith 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.mdrather than inventing the pattern in the persona file itself.