.claude/agents/ — Agent Definitions

Every file in this directory defines a research agent. The filename (minus .md) becomes the subagent_type used to spawn it.

File Format — Canonical 7-Section Structure

Every agent definition follows this exact structure:

---
name: agent-name-here          # Lowercase, hyphenated. MUST match filename.
description: "When to use..."  # 3-5 example prompts. Claude reads this to dispatch.
model: opus | sonnet | haiku   # LLM tier (see below)
color: cyan                    # Terminal display color
memory: project                # Always "project" for research agents
---

Body Sections (in order)

1. Identity (no header) — 1-2 paragraphs. HOW they think, not WHAT they know. Methodology over knowledge domain.
2. ## Research Corpus — Points to researchers/{{DOMAIN}}/. Includes read-at-start instruction.
3. ## Core Methodology — 3-5 numbered principles that define the agent's analytical approach.
4. ## Primary Directives — 3-5 numbered operational rules specific to the archetype.
5. ## Interaction Patterns — Exactly 4 bullets: Solo, Team, Adversarial, Cross-domain.
6. ## Output Standards — Bullet list of formatting, quality, and epistemic requirements.
7. ## Persistent Memory — Boilerplate pointing to .claude/agent-memory/{name}/.

Model Tier Assignment

Agent Archetypes

Every research agent maps to one cognitive archetype:

Required Agents

These three must exist in every project:

1. coordinator.md — Orchestration, meeting minutes, context keeping
2. knowledge-weaver.md — Knowledge index curation (sole writer of knowledge-index.json)
3. web-researcher.md — Paper fetching and corpus population

Rules

• One agent per file — no multi-agent definitions
• Filename = identity — foo-bar.md means the agent's name is foo-bar
• No project-wide rules in agent files — those belong in the root CLAUDE.md
• Infrastructure agents don't do research — coordinator orchestrates, indexer indexes, scout fetches. Hard boundary.
• Every agent needs a memory stub — create .claude/agent-memory/{name}/MEMORY.md when creating the agent

Anti-Patterns

• The "Yes Man" — agrees with everything, has no methodology. Fix: add adversarial directives.
• The "Kitchen Sink" — knows everything, thinks about nothing distinctly. Fix: narrow the methodology.
• The "Personality Without Methodology" — has a persona but no analytical framework. Fix: define HOW it evaluates claims.
• The "Stateless" — never references or updates its memory. Fix: add memory read/write instructions.
• The "Novelist" — produces prose instead of structured output. Fix: mandate output format.

Quality Checklist

Before considering an agent definition complete:

• YAML frontmatter has all 5 fields
• Identity section describes methodology, not just knowledge
• Research corpus points to an actual researchers/ subdirectory
• Primary directives are specific and actionable (not "be thorough")
• Interaction patterns cover all 4 contexts
• Output standards include epistemic requirements
• Persistent memory section exists with directory path
• Debate test: Spawn alongside another agent on contested topic — does it hold a DISTINCT position?
• Execution test: Give it a concrete problem — does it produce ACTIONABLE output?