Twelve Claude Code agents defined in .claude/agents/.

Roles

Role	Model	Tools	Purpose
Pai	Sonnet	Read, Glob, Grep, WebSearch, WebFetch, pai-discord, pai-memory, playwright, linear	Executive assistant, Discord comms, persistent memory
Pai Self-Improver	Sonnet	Read, Glob, Grep, Bash, openobserve, pai-discord, linear	Daily diagnostic cron — mines O2, proposes memory updates
Publisher	Opus	Read, Write, Edit, Bash, Glob, Grep, Agent	Orchestrate content pipeline, write blog posts
Analyst	Opus	Read, Glob, Grep, WebSearch, WebFetch	Ingest research, validate claims, propose system improvements
Synthesizer	Opus	Read, Edit, Glob, Grep, Agent	Compare and contrast Deep Research reports
PRD Writer	Opus	Read, Write, Edit, Glob, Grep, WebSearch, WebFetch, Agent	Interview, research, write PRDs
Design Doc Writer	Opus	Read, Write, Edit, Glob, Grep, WebSearch, WebFetch, Agent	Interview, architect, write design docs from PRDs
Journalist	Haiku	Read, Write, Bash, Glob, Grep, WebFetch, WebSearch	Daily AI news digests to wiki journal
Researcher	Sonnet	Read, Glob, Grep, WebFetch, WebSearch	Gather sourced facts, return research brief
Reviewer	Opus	Read, Glob, Grep	Check style, substance, frontmatter, sourcing
QA	Sonnet	Bash, Read, Glob, Grep, Playwright MCP	Build, render, and link verification
Security Auditor	Opus	Read, Glob, Grep	Confidential data, prompt injection, OWASP LLM checks

Top-level vs subagent

Pai, Publisher, Analyst, Synthesizer, Journalist, PRD Writer, and Design Doc Writer are invoked directly. Researcher, Reviewer, QA, and Security Auditor are subagents called by Publisher during its pipeline.

Invocation

claude --agent pai
claude --agent publisher
claude --agent analyst
claude --agent synthesizer
claude --agent journalist
claude --agent prd-writer
claude --agent design-doc-writer

Coordination

• Git — shared state. Subagents write reports to files; the publisher reads those files. All artifacts live in the repo.
• Claude Code memory — cross-session context. Persistent notes about user preferences, project state, and feedback.

Design principles

• Deny-by-default: agents are read-only unless they need to write.
• Route by risk: Opus for judgment, Sonnet for mechanical work, Haiku for high-frequency low-complexity tasks.
• Artifacts not pass-through: files as intermediate state between agents, not large context passed through prompts.

Adding a new agent

1. Define the agent in .claude/agents/<name>.md
2. Create a wiki page at wiki/agent-team/<name>.md (copy prd-writer.md as a template)
3. Add a row to the Roles table above and update the count in the summary
4. Generate the avatar image:

   cd apps/blog/blog
   OPENAI_API_KEY=<key> node scripts/generate-agent-image.mjs agent-<name>.png "<subject description>"
   

   The script saves to public/images/ and matches the existing avatar style (geometric flat design, dark navy background, bold colors).
5. Reference the image in the wiki page: ![<Name> avatar](/images/agent-<name>.png)
6. Add the agent to the invocation block if it's a top-level agent

History

See History for the changelog of architectural transitions.