agents/ — Agent Definitions

agents/ — Agent Definitions

15 agent definitions for the autoimprove improvement loop. Each agent is a Markdown file with YAML frontmatter (name, description, optional model).

Local Role

Owns all agent prompt files for the autoimprove loop. Defines the dispatch contract, tool access, and model selection for each agent. The AR triad sequencing constraint (E→A→J foreground sequential) lives here.

Product Vision Fit

Agents are the execution layer of the autonomous improvement loop. Each agent specializes in a phase (grind / propose / research) or a quality check (AR triad, reviewer, transformer). Skills orchestrate; agents execute. Without this folder, there is no autonomous improvement.

Tech Stack Boundaries

Markdown + YAML frontmatter only. No runtime code in agent files. Model selection via frontmatter model: field. Tool access via frontmatter allowed-tools: (or inherited default from Claude Code).

Owns

• All .md files under agents/
• The AR triad sequencing constraint (foreground sequential, never background or parallel)
• The experimenter's blind-to-scoring invariant (experimenter receives no benchmark or scoring data)
• Dispatch contracts: what each agent receives as input and what it produces as output

Does Not Own

• Skill orchestration logic — owned by skills/
• Benchmark scripts and metric evaluation — owned by benchmark/
• State files (experiments.tsv, context.json, epoch-baseline.json) — owned by root / skills
• Plugin entry points (plugin.json) — owned by root

Routes Elsewhere

• Theme selection and loop orchestration → skills/run/
• Benchmark evaluation of agent output → benchmark/
• Worktree lifecycle management → skills/_shared/
• Skill scoring rubrics used by reviewer/transformer → skills/rubrics/

Local Examples

Belongs here:

• New agent prompt file agents/new-agent.md
• Changing when the proposer is triggered (dispatch contract)
• Adding a tool to the AR triad's allowed-tools

Route elsewhere:

• Logic that decides which agent to dispatch → skills/run/
• Script that evaluates agent output against a benchmark → benchmark/
• User-facing skill that invokes an agent → skills/<name>/SKILL.md

Verification

python3 ~/.claude/skills/applying-agentsmd-rulebook/scripts/check-agentsmd.py --root .

Agent behavior is tested via skills/challenge/ and skills/test/. No dedicated unit tests for prompt files — challenges are the verification gate.

Change Triggers

Update this file when:

• A new agent is added to agents/ or an existing one is removed
• The AR triad sequencing rule changes (e.g., adding a fourth stage)
• The experimenter's blind-to-scoring invariant is modified
• The dispatch contract for any agent changes (inputs, outputs, model, tools)

---

AR Triad (Protected — Co-CEO only per UNBREAKABLE §7)

The adversarial review chain runs foreground: Enthusiast and Adversary dispatch in parallel (PARALLEL RULE — SKILL.md:141), Judge dispatches sequentially after both complete. Never background.

Agent	File	Role
autoimprove:enthusiast	enthusiast.md	Finds genuine improvements — aggressive optimism
autoimprove:adversary	adversary.md	Maps heuristics + safe zones independently — no findings input
autoimprove:judge	judge.md	Arbitrates E findings using A's adversarial context
autoimprove:enthusiast-spec	enthusiast-spec.md	Spec variant — gaps/ambiguities in design docs
autoimprove:adversary-spec	adversary-spec.md	Spec variant — maps prose heuristics + safe zones (planned-work markers, defaults)
autoimprove:judge-spec	judge-spec.md	Spec variant — arbitrates spec findings using A-spec's adversarial context

Improvement Loop Agents

Agent	File	Role
autoimprove:experimenter	experimenter.md	Spawned per-experiment into worktree; blind to scoring
autoimprove:proposer	proposer.md	Phase 2: drafts structured proposals when grind stagnates
autoimprove:researcher	researcher.md	Phase 3: investigation memos, no code changes

Quality Agents

Agent	File	Role
autoimprove:reviewer	reviewer.md	Scores skills against rubrics, identifies gaps
autoimprove:transformer	transformer.md	Rewrites skills applying rubric transforms
autoimprove:convergence-analyst	convergence-analyst.md	Analyzes experiment history for patterns
autoimprove:challenge-runner	challenge-runner.md	Runs challenge suites against agent outputs
autoimprove:idea-explorer	idea-explorer.md	Explores improvement ideas before committing
autoimprove:docs-regenerate	docs-regenerate.md	Regenerates docs from git diff (diff-only, never full source)

Dispatch Contract

• AR triad invoked via autoimprove:adversarial-review command or directly via Agent tool
• Experimenter receives: theme, worktree path, target repo context — never benchmark/scoring data
• Proposer triggered when grind keep-rate <25% for 3 sessions; produces proposals for human approval
• Researcher produces memos to experiments/research-<timestamp>.md
• Docs-regenerate triggered by PostToolUse commit hook; reads only git diff