Agents
Twenty-five specialists that never edit each other’s work
Four Architectural Rules
The system uses 25 specialized agents, most of them organized into worker-critic pairs. Four rules explain most of the system’s behavior.
Worker-Critic Pairing
Every creator has a paired destroyer. The critic reads the artifact, scores it against a rubric, and lists what must change — but never edits the file itself. The strategist-critic gives a verdict instead of points: SOUND, MINOR ISSUES, MAJOR ISSUES, or CRITICAL ERRORS. If the score falls below 80 (or the verdict is MAJOR ISSUES or worse), the worker revises and the critic re-evaluates. This cycle repeats up to 3 rounds.
| Worker | Critic | What’s Reviewed |
|---|---|---|
| librarian | librarian-critic | Literature coverage, gaps, recency |
| explorer | explorer-critic | Data feasibility, quality, identification fit |
| strategist | strategist-critic | Identification validity, assumptions, robustness |
| theorist | theorist-critic | Proof validity, assumption minimality, notation |
| data-engineer | coder-critic | Data pipeline quality, reproducibility |
| coder | coder-critic | Code quality, strategy alignment, numerical discipline |
| writer | writer-critic | Manuscript polish, claims-evidence, LaTeX format |
| storyteller | storyteller-critic | Talk structure, visual quality, content fidelity |
| coherence-finder | coherence-skeptic | Internal-consistency findings, one check group at a time |
The coherence pair is a chain rather than a loop: /coherence --deep runs coherence-finder once per check group, one coherence-skeptic per group tries to refute its findings, and coherence-consolidator merges the survivors. No scores, no revision rounds (see Coherence Chain).
Nine agents have no paired critic. Two are infrastructure (orchestrator, verifier); three already serve as reviewers (editor, domain-referee, methods-referee); two are later stages of the coherence chain (coherence-skeptic, coherence-consolidator). The explainer’s output is tested on the author by a quiz, not scored by a critic. The guide-writer writes documentation, outside the research pipeline.
Separation of Powers
Critics never create. Creators never self-score. Every critic’s tool list is read-only (Read, Grep, Glob), so a critic cannot write a file in scripts/, paper/, or anywhere else. If a creator reports its own score, the orchestrator discards it and dispatches the critic.
This prevents the system from rubber-stamping its own output. A critic who fixes their own findings has incentive to find only fixable issues. Separation keeps criticism honest.
Cold-Read Protocol
Critics evaluate blind. On every round, the critic receives only the artifact, its scoring rubric, the severity level, and the content invariants. It does not receive: what round this is, what the worker struggled with, prior critic reports, or the research journal. A critic that knows the worker has already tried twice will soften its evaluation. The cold-read protocol prevents this drift.
Three-Round Limit and Escalation
Three strikes, then escalation. If a worker-critic pair cannot converge after 3 rounds, the orchestrator routes the problem elsewhere — either to a different agent or to the user. Escalation targets are declared per agent in permissions.md. When the coder and coder-critic deadlock, the issue escalates to the strategist-critic (is the memo implementable?). When the strategist and strategist-critic deadlock, it escalates to the user (fundamental design question). This prevents infinite loops while ensuring hard problems get human judgment.
The Skill-Centric Model
Agents used to be monolithic. Each agent file contained identity, checklists, templates, rubrics, and scoring tables — 200 to 474 lines of coupled operational knowledge. Updating a checklist meant editing an agent. Adding a paper type meant editing every agent that touches paper types.
The problem: operational knowledge evolved faster than identity. A new estimator package required updating checklists, not changing who the coder is. Coupling them meant agent files churned constantly.
Now agents are lean identity files. Each one is roughly 35–210 lines declaring: role, voice, constraints, tool access, paper-type awareness, and pointers to where the operational knowledge lives. The coder file says “read analyze/templates/pre-code-report.md before writing code” — it does not contain the pre-code report template itself.
The operational knowledge — checklists, rubrics, scoring tables, templates, gotchas — lives in skill folders. When the orchestrator dispatches an agent, it tells the agent which skill invoked it and the agent reads the relevant templates from that skill’s directory. This means:
- Agent files change rarely (identity is stable)
- Skill folders evolve freely (knowledge improves every project)
- The same agent can serve multiple skills with different templates
- Adding a new paper type means adding templates, not rewriting agents
A concrete example: the coder agent file (136 lines) declares its role, tool access, workflow stages, engineering standards, and output expectations. But when /analyze dispatches it, the coder reads analyze/templates/pre-code-report.md for the pre-code report format, analyze/templates/r-script-structure.R for the scaffold, and analyze/gotchas.md for known pitfalls. None of that lives in the agent file. If we learn a new gotcha tomorrow, we add one line to analyze/gotchas.md — the agent file never changes.
The strategist-critic works the same way. Its identity file (62 lines) says: “You are a top-5 journal referee. Run 4 sequential phases. Read the causal audit template.” The 4-phase audit protocol, the design-specific checklists, and the scoring rubric all live in review/templates/ and review/config/. Updating how we evaluate RDD papers means editing a template, not touching the critic’s identity.
Model and effort live in the frontmatter. Every agent sets model: inherit, so it runs on whatever model your session uses. Some also set effort:. High: strategist, strategist-critic, theorist, theorist-critic, methods-referee, editor. Low: coherence-finder, coherence-skeptic, librarian-critic, explorer-critic. Everything else runs at the default (medium on Opus 5.5).
For full agent specifications, see the .claude/agents/ directory — each file is self-contained and authoritative.
Agent Groups
Rather than profiling each agent individually (those profiles live in .claude/agents/), we organize by function. Each group activates at a specific pipeline phase, produces specific artifacts, and has specific quality gates.
Discovery Pair
The librarian searches top-5 general-interest journals, field journals, NBER working papers, and citation chains to produce an annotated bibliography, a BibTeX file, a frontier map (what has been done), and a positioning statement (where the new paper fits). The explorer searches for datasets — public, administrative, survey — and grades each by feasibility: variable coverage, access requirements, panel structure, and known data issues.
Both run in parallel from the start of a project. Neither depends on the other. The librarian-critic checks for coverage gaps (missing seminal papers, missing methods literature, over-reliance on working papers). The explorer-critic checks measurement validity (does the proposed variable actually capture the concept?) and identification compatibility (does this data support the likely design?).
Together they answer a single question: what has been done, and what data could let us do something new?
Activates: From a research idea or spec. No prerequisites. Produces: quality_reports/literature/ and quality_reports/data-assessment/ Quality gate: No score gate. Strategy needs only one of the two outputs to exist (literature OR data assessment); both critics’ scores feed the weighted aggregate, 10% each.
Strategy Pair
The strategist is paper-type aware. Given the literature and data assessment, it classifies the paper type (reduced-form, structural, theory+empirics, descriptive) and applies the corresponding strategy template. For reduced-form papers, it assesses the identification landscape, proposes designs ranked by credibility, and specifies design-specific estimation guidance (modern DiD estimators for staggered treatment, effective F for IV, MSE-optimal bandwidth for RDD). For structural papers, it specifies the model environment, decision problem, equilibrium concept, identification of each parameter, and counterfactual design. It always anticipates the top 5 referee objections.
The theorist activates conditionally — only for papers that need formal proofs. It drafts assumptions, definitions, propositions, and proofs at journal-publication rigor, with every theorem linked to the empirical strategy. Its critic runs a 4-phase proof review with early stopping on logical gaps.
The strategist-critic is the system’s most important gatekeeper. It runs a 4-phase sequential audit: identify the design, check whether the core assumptions hold (design-specific checklists), evaluate inference and code-theory alignment, then check robustness. Critical finding in Phase 2 stops the review — no point checking robustness if parallel trends are violated.
Activates: After at least one Discovery output (literature OR data assessment). Produces: quality_reports/strategy/ and (when activated) quality_reports/theory/ Quality gate: Strategist-critic verdict of SOUND or MINOR ISSUES before Execution activates; theorist-critic >= 80 when the theorist ran.
Execution Trio
The data-engineer takes raw data and produces clean, analysis-ready datasets. It documents every sample restriction with counts, constructs variables per strategy memo definitions, merges datasets with documented merge rates, and produces publication-quality figures (custom themes, colorblind-safe palettes, no titles inside plots).
The coder translates the strategy memo into numbered analysis scripts (00_master.R through 07_tables.R) with engineering discipline: numerical guards, pre-allocation, a single seed, here() for all paths, and a paper-to-code naming map linking every \(\beta\) and \(Y_{it}\) to its code variable. It implements the main specification, all robustness checks from the memo, and exports bare tabular environments for tables.
The writer drafts the manuscript after code is approved. It refuses to write Results without actual output files in paper/tables/ — this gate exists because the distinction between “the strategy predicts X” and “the data shows X” is the difference between a proposal and a paper. It maintains a claim-source map tracing every numerical claim to a specific script line and output file.
The coder-critic reviews both the data-engineer and coder across 16 categories: strategic alignment (does the code match the memo?), code quality (reproducibility, numerics, function design), and infrastructure (checkpointing, error handling, prohibited patterns). The writer-critic runs 8 checks: structure, claims-evidence, identification fidelity, AI-pattern detection, LaTeX format, compilation, voice fidelity, and notation consistency.
Alongside the trio, the explainer runs once code review passes, in parallel with the writer. For each analysis script it writes a delta-explainer (only what departs from the strategy memo, plus a sample-construction ledger with drop counts), a 5-question quiz, and a separate answer key. It tests the author, not the code: /submit blocks until every script behind a paper exhibit has a passing quiz at the script’s current fingerprint (INV-26).
Activates: Data-engineer and coder after a strategist-critic verdict of SOUND or MINOR ISSUES. Writer and explainer after coder-critic score >= 80. Produces: data/cleaned/, scripts/R/, paper/tables/, paper/figures/, paper/sections/ Quality gate: Coder-critic and writer-critic both >= 80 before Peer Review.
Review Team
The editor performs desk review: reads the abstract and introduction, skims the contribution, verifies novelty, and decides whether to send to referees or desk reject. When it sends, it assigns each referee a contrasting intellectual disposition — STRUCTURAL (“where’s the mechanism?”), CREDIBILITY (“show me the pre-trends”), MEASUREMENT (“how is this measured?”), POLICY (“does this generalize?”), THEORY (“what does the model predict?”), or SKEPTIC (“what would make this go away?”). Each referee also receives randomized pet peeves drawn from pools of critical and constructive tendencies.
The domain-referee evaluates substance: contribution and novelty (30%), literature positioning (25%), substantive arguments (20%), external validity (15%), and journal fit (10%). The methods-referee evaluates methods with paper-type-specific weights: identification strategy, estimation, inference, robustness, and replication readiness. Neither sees the other’s report. In round 1 neither sees earlier verdicts either: both read a fenced copy of the manuscript outside the repository, away from quality_reports/reviews/. --peer --r2 deliberately reuses round 1.
After both reports arrive, the editor classifies each concern as FATAL (cannot be fixed), ADDRESSABLE (fixable with revision), or TASTE (referee preference), resolves disagreements with explicit reasoning, and issues a decision.
Activates: After writer-critic and coder-critic both >= 80. Invoked via /review --peer. Produces: quality_reports/reviews/ Quality gate: Editorial decision of Accept or Minor Revisions to proceed to Submission.
Presentation Pair
The storyteller creates talks from the paper in four formats (job market 40–50 slides, seminar 25–35, short 10–15, lightning 3–5) and two output types (Beamer PDF, Quarto RevealJS HTML). Paper-type aware: reduced-form talks lead with the policy question and show variation; structural talks build the model step by step with progressive reveal and pay off with the counterfactual; theory+empirics talks present competing explanations and a distinguishing prediction; descriptive talks lead with what is missing in current measures.
The storyteller-critic checks narrative flow (does the hook work?), visual quality (text overflow, font sizes, one idea per slide), content fidelity (numbers match the paper), and compilation. Presentation scores are advisory — they do not block commits or PRs.
Activates: After writer-critic score >= 80. Can run parallel with Peer Review. Produces: paper/talks/ or paper/quarto/ Quality gate: Advisory only.
Coherence Chain
/coherence --deep adds a reasoning pass on top of the deterministic parser, run as a three-stage chain. The coherence-finder is one definition dispatched once per non-empty check group (specification, claims, continuity, notation, theory), each in its own context, so the groups do not anchor on each other. A coherence-skeptic per group with findings tries to refute each one, defaulting to refuted when uncertain. The coherence-consolidator merges the same defect seen from different checks and ranks what survives.
Activates: On /coherence --deep, after paper_coherence.py --slices writes one slice per group. Produces: A ## Reasoning layer section appended to quality_reports/coherence/YYYY-MM-DD_report.md Quality gate: None. Reasoning findings are advisory and never block; coherence carries no weight in the score.
Infrastructure
The orchestrator is the project manager. It reads permissions.md to determine which agents can activate and runs scripts/pipeline.py check-pre / check-post around every dispatch (do REQUIRES artifacts exist? do PRODUCES artifacts exist with required sections?). It launches worker-critic pairs in parallel when independent and tracks strike counts. It does not do the arithmetic: scripts/score.py computes the weighted score, and pipeline.py status derives pipeline_state.json from the research journal. Its tool list names its dispatch roster as Agent(...), so it can only spawn registry agents. It makes no research decisions — when judgment is needed, it escalates to the user with a clear question.
The verifier checks mechanical correctness in two modes. It starts from scripts/verify.py, which runs the mechanical checks (including the INV-26 understanding gate), and keeps the judgment calls for itself. Standard mode (between phases): LaTeX compilation, script execution, file integrity, output freshness. Submission mode (before journal deposit): package inventory, dependency verification, data provenance, end-to-end execution, output cross-reference, and AEA-format README completeness. It scores binary — 0 or 100, contributing 5% weight to the overall project score.
Activates: Orchestrator runs throughout. Verifier runs between phases and at submission. Produces: quality_reports/pipeline_state.json, quality_reports/verification_report.md Quality gate: Verifier must PASS (100) for submission.
Phase Flow
Research is not a waterfall, but it has a direction. Agents activate by dependency, not by sequence number. If you already have data and a draft, you can enter at Peer Review. If a referee says “control for X,” the orchestrator routes back to the coder alone — not through the entire pipeline.
The dependency chain:
Discovery ──→ Strategy ──→ Execution ──→ Peer Review ──→ Submission
(librarian, (strategist, (data-engineer, (editor, (verifier)
explorer) theorist) coder, writer) referees)
↕
Presentation
(storyteller)Every arrow but the first is gated by a critic: a strategist-critic verdict of SOUND or MINOR ISSUES out of Strategy, scores >= 80 out of Execution, an editorial decision out of Peer Review. Before every dispatch the orchestrator runs scripts/pipeline.py check-pre, which reads permissions.md: are the REQUIRES artifacts present? Has the prerequisite critic passed? If not, the agent does not activate.
Re-entry is allowed at any phase except Submission (terminal). A Major Revisions decision from Peer Review triggers re-entry at whatever phase the referee comments require — sometimes just the writer (clarification), sometimes back to the coder (new analysis), sometimes back to the strategist (fundamental design challenge).
The system distinguishes between phases (sequential gates) and parallel groups (concurrent work within a phase). The librarian and explorer run concurrently. The data-engineer and coder run concurrently. But the writer waits for the coder to finish, and runs alongside the explainer. These relationships are all declared in one file — permissions.md — not hardcoded in agent logic.
Quick Reference
All 25 agents at a glance.
| Agent | Phase | Creates / Checks | Paired With |
|---|---|---|---|
| librarian | Discovery | Annotated bibliography, BibTeX, frontier map | librarian-critic |
| librarian-critic | Discovery | Checks coverage, gaps, journal quality, recency | librarian |
| explorer | Discovery | Ranked data sources, feasibility grades | explorer-critic |
| explorer-critic | Discovery | Checks measurement validity, sample selection, ID fit | explorer |
| strategist | Strategy | Strategy memo, pseudo-code, robustness plan | strategist-critic |
| strategist-critic | Strategy | Checks assumptions, inference, robustness (4 paper types) | strategist |
| theorist | Strategy | Assumptions, theorems, proofs, notation glossary | theorist-critic |
| theorist-critic | Strategy | 4-phase proof review with early-stop on critical gaps | theorist |
| data-engineer | Execution | Clean datasets, codebooks, publication figures | coder-critic |
| coder | Execution | Analysis scripts, tables, figures, results summary | coder-critic |
| coder-critic | Execution | 16 checks: strategy alignment, code quality, numerics | coder, data-engineer |
| writer | Execution | Paper manuscript, claim-source map | writer-critic |
| writer-critic | Execution | 8 checks: structure, claims, format, voice, notation | writer |
| explainer | Execution | Delta-explainer, sample ledger, 5-question quiz + separate key (INV-26) | None |
| editor | Peer Review | Desk review, referee dispatch, editorial decision | None |
| domain-referee | Peer Review | Blind review (substance: contribution, literature, scope) | None |
| methods-referee | Peer Review | Blind review (methods: ID, estimation, inference, robustness) | None |
| storyteller | Presentation | Beamer / Quarto talks in 4 formats | storyteller-critic |
| storyteller-critic | Presentation | Checks narrative, visuals, content fidelity, scope | storyteller |
| coherence-finder | /coherence --deep |
Internal-consistency findings for one check group | coherence-skeptic |
| coherence-skeptic | /coherence --deep |
Tries to refute one group’s findings, in one batch | coherence-finder |
| coherence-consolidator | /coherence --deep |
Merges duplicates across groups, ranks survivors | None |
| orchestrator | All | Agent dispatch, quality gates (via pipeline.py, score.py) |
None |
| verifier | Submission | Compilation, execution, file integrity, AEA audit (verify.py + judgment) |
None |
| guide-writer | Documentation | Guide pages and docs in a tutorial style | None |
Where the Details Live
This page teaches the architecture — the four rules, the skill-centric model, the group relationships, and the phase flow. The operational specifics (rubrics, scoring tables, checklists, deduction schedules) live elsewhere:
- Agent identity files:
.claude/agents/*.md— role, voice, constraints, paper-type awareness - Skill templates:
{skill}/templates/— checklists, protocols, report formats - Skill config:
{skill}/config/— scoring rubrics, tolerance thresholds - Permission registry:
.claude/rules/permissions.md— REQUIRES, PRODUCES, escalation targets, quality weights - Lifecycle validation:
.claude/rules/lifecycle.md— pre-dispatch and post-completion checks, run byscripts/pipeline.py check-pre/check-post - Weights and thresholds:
.claude/skills/new-project/config/quality-gates.json, read byscripts/score.py
The permission registry is the single source of truth for agent dispatch. Adding a new agent means a file in .claude/agents/ (frontmatter model: inherit, optional effort:) and an entry in permissions.md. If the orchestrator dispatches it, add it to the orchestrator’s Agent(...) roster; if it is weighted, add it to quality-gates.json too — check_scaffold.py fails when the weights in the two files disagree.