Complete reference for all agents in AgentSys.

TL;DR: 49 agents across 20 plugins (18 have agents). opus for reasoning, sonnet for patterns, haiku for execution. Each agent does one thing well.

Design principle: Each agent has a single responsibility. Complex work is decomposed into specialized agents that do one thing extremely well, then orchestrated together.

Related docs:

• /next-task Workflow - How agents work together

AgentSys uses 49 specialized agents across 20 plugins (18 have agents; gate-and-ship is commands-only; zig-lsp is a config-only LSP plugin with no commands or agents). Each agent is optimized for a specific task and assigned a model based on complexity:

Agent types:

• File-based agents (39) - Defined in plugins/*/agents/*.md with frontmatter
• Role-based agents (10) - Defined inline via Task tool with specialized prompts

Model: sonnet Purpose: Find and prioritize tasks from configured sources.

What it does:

1. Loads claimed tasks from tasks.json (excludes them)
2. Fetches from GitHub Issues, GitHub Projects (v2 boards), GitLab, local files, or custom CLI
3. Excludes issues that already have an open PR (GitHub source only)
4. Applies priority scoring (labels, blockers, age, reactions)
5. Presents top 5 via AskUserQuestion checkboxes
6. Posts "Workflow Started" comment to GitHub issue

Tools available:

• Bash (gh, glab, git)
• Grep, Read
• AskUserQuestion

Model: haiku Purpose: Create git worktrees for isolated development.

What it does:

1. Creates ../worktrees/{task-slug}/ directory
2. Creates feature/{task-slug} branch
3. Claims task in tasks.json
4. Creates flow.json in worktree

Tools available:

• Bash (git only)
• Read, Write

Model: opus Purpose: Deep codebase analysis before planning.

What it does:

1. Extracts keywords from task description
2. Searches for related files
3. Traces dependency graphs
4. Analyzes existing patterns
5. Outputs exploration report

Tools available:

• Read, Glob, Grep
• Bash (git only)
• LSP
• Task (for sub-exploration)

Why opus: Exploration quality directly impacts planning quality. Poor exploration = poor plan = poor implementation. The compound effect justifies the cost.

Model: opus Purpose: Design step-by-step implementation plans.

What it does:

1. Synthesizes exploration findings
2. Creates implementation steps
3. Identifies risks and critical paths
4. Outputs structured JSON
5. Posts summary to GitHub issue

Tools available:

• Read, Glob, Grep
• Bash (git only)
• Task (for research)

Output format:

{
  "steps": [
    { "action": "modify", "file": "src/auth.ts", "description": "..." }
  ],
  "risks": ["..."],
  "complexity": "medium"
}

Why opus: Planning is the leverage point. A good plan makes implementation straightforward. A bad plan causes rework cycles.

Model: opus Purpose: Execute approved plans with production-quality code.

What it does:

1. Executes plan step-by-step
2. Creates atomic commits per step
3. Runs type checks, linting, tests after each step
4. Updates flow.json for resume capability

Tools available:

• Read, Write, Edit
• Glob, Grep
• Bash (git, npm, node)
• Task (for sub-tasks)
• LSP

Restrictions:

• MUST NOT create PR
• MUST NOT push to remote
• MUST NOT invoke review agents

Why opus: Implementation quality matters. Bad code gets caught in review but wastes cycles. Good code flows through.

Note: delivery-validator and test-coverage-checker moved to prepare-delivery plugin.

Model: sonnet Purpose: Update documentation for recent changes.

What it does:

1. Finds docs referencing changed files
2. Updates CHANGELOG entry
3. Fixes outdated imports/versions
4. Delegates simple edits to simple-fixer
5. Invokes /ship when complete

Tools available:

• Bash (git)
• Read, Grep, Glob
• Task (for simple-fixer)

Model: haiku Purpose: Execute mechanical edits without judgment.

What it does:

• Receives structured fix list from parent
• Executes each fix: remove-line, replace, insert
• No decision-making, just execution

Tools available:

• Read, Edit
• Bash (git)

Why haiku: Pure execution. No reasoning needed. Haiku is fast and cheap.

Model: haiku Purpose: Poll CI status with sleep/check loops.

What it does:

1. Polls gh pr checks every 15 seconds
2. Reports status changes
3. On failure: delegates to ci-fixer
4. On success: continues workflow

Tools available:

• Bash (gh, git)
• Read
• Task (for ci-fixer)

Why haiku: Polling is mechanical. No judgment needed.

Model: sonnet Purpose: Fix CI failures and review comments.

What it does:

1. Analyzes CI logs to diagnose failure
2. Applies fixes:
   • Lint auto-fix
   • Type error resolution
   • Test failure fixes
3. Addresses PR review comments
4. Commits and pushes fixes

Tools available:

• Bash (git, npm)
• Read, Edit
• Grep, Glob

Model: sonnet Purpose: Clean AI slop from code with certainty-based findings.

What it does:

1. Parses arguments (mode, scope, thoroughness)
2. Invokes deslop skill to run detection
3. Returns structured findings with certainty levels
4. HIGH certainty items marked for auto-fix by orchestrator

Tools available:

• Bash (git, node)
• Skill (for deslop)
• Read, Glob, Grep

Why sonnet: Slop detection is pattern-based. Sonnet handles patterns well and is faster/cheaper than opus.

Cross-plugin usage: Also used by next-task Phase 8 with scope=diff to clean new code before review.

Model: sonnet Purpose: Analyze plugin structures.

Checks:

• plugin.json manifest validity
• MCP tool definitions (additionalProperties, required array)
• Security patterns (unrestricted Bash, command injection)
• Component organization

Tools available:

• Read, Glob, Grep
• Bash (git)

Model: opus Purpose: Analyze agent prompts.

Checks (14 patterns):

• Frontmatter validity
• Tool restrictions
• XML structure
• Chain-of-thought appropriateness
• Example quality
• Anti-patterns (vague language, prompt bloat)

Tools available:

• Read, Glob, Grep
• Bash (git)

Why opus: Agent quality compounds. Bad agent prompts = bad agent outputs across all uses.

Model: opus Purpose: Analyze CLAUDE.md/AGENTS.md files.

Checks:

• Structure (critical rules, architecture, commands)
• References to actual files
• Token efficiency
• README duplication
• Cross-platform compatibility

Tools available:

• Read, Glob, Grep
• Bash (git)

Model: opus Purpose: Analyze documentation quality.

Modes:

• AI-only: Aggressive token reduction
• Both: Balance readability with AI-friendliness

Checks:

• Link validity
• Structure and chunking
• Semantic boundaries
• Heading hierarchy

Tools available:

• Read, Glob, Grep
• Bash (git)

Model: opus Purpose: Analyze prompt engineering patterns.

Checks (16 patterns):

• Clarity (vague instructions)
• Structure (XML, headings)
• Examples (few-shot patterns)
• Context/WHY presence
• Output format specification
• Anti-patterns (redundant CoT)

Tools available:

• Read, Glob, Grep
• Bash (git)

Model: opus Purpose: Analyze hook definitions.

Checks:

• Frontmatter presence and structure
• Required name/description fields
• Basic formatting expectations

Tools available:

• Read, Glob, Grep

Model: opus Purpose: Analyze SKILL.md quality.

Checks:

• Frontmatter presence and structure
• Required name/description fields
• Trigger phrase clarity ("Use when user asks")

Tools available:

• Read, Glob, Grep

Model: sonnet Purpose: Analyze cross-file semantic consistency.

Checks:

• Tools used vs declared in frontmatter
• Agent references exist
• Duplicate instructions across files
• Contradictory rules (ALWAYS vs NEVER)
• Orphaned agents
• Skill tool mismatches

Tools available:

• Read, Glob, Grep, Bash(git:*)

Model: opus Purpose: Deep semantic analysis for drift detection.

What it does:

1. Receives data from JavaScript collectors
2. Performs semantic matching (not string matching)
3. Identifies:
   • Issues that should be closed (already done)
   • "Done" phases that aren't done
   • Release blockers
4. Outputs prioritized reconstruction plan

Tools available:

• Read, Write

Why opus: Semantic matching requires deep understanding. "user authentication" must match auth/, login.js, session.ts. Opus handles this.

Model: haiku Purpose: Validate repo-intel output for obvious errors.

What it does:

1. Verifies map isn't empty
2. Flags suspiciously small symbol counts
3. Checks for missing language detection
4. Returns single-line status

Tools available:

• Read

Why haiku: Validation is deterministic and lightweight.

Model: opus Purpose: Coordinate /perf investigations across all phases.

What it does:

1. Enforces perf rules and phase order
2. Spawns theory, profiling, and logging helpers
3. Ensures checkpoints + evidence after each phase

Tools available:

• Read, Write, Edit, Task, Bash(git:), Bash(npm:), Bash(cargo:), Bash(go:), Bash(pytest:), Bash(mvn:), Bash(gradle:*)

Model: opus Purpose: Generate hypotheses based on git history and evidence.

Tools available:

• Read, Bash(git:), Bash(npm:), Bash(pnpm:), Bash(yarn:), Bash(cargo:), Bash(go:), Bash(pytest:), Bash(python:), Bash(mvn:), Bash(gradle:)

Model: opus Purpose: Validate hypotheses with controlled experiments.

Tools available:

• Read, Write, Edit, Bash(git:), Bash(npm:), Bash(pnpm:), Bash(yarn:), Bash(cargo:), Bash(go:), Bash(pytest:), Bash(python:), Bash(mvn:), Bash(gradle:)

Model: sonnet Purpose: Map entrypoints and likely hot files before profiling.

Tools available:

• Read, Grep, Glob

Model: sonnet Purpose: Append structured investigation logs with evidence.

Tools available:

• Read, Write

Model: opus Purpose: Synthesize findings into evidence-backed recommendations.

Tools available:

• Read, Write

These are role-based agents invoked via Task tool with specialized prompts. They use the built-in review subagent type with domain-specific instructions.

Activation: Always active Purpose: Review code quality and error handling.

Focuses on:

• Code style and consistency
• Best practices violations
• Error handling and failure paths
• Maintainability issues
• Code duplication

Activation: Always active Purpose: Find security vulnerabilities.

Focuses on:

• SQL injection, XSS, CSRF vulnerabilities
• Authentication and authorization flaws
• Secrets exposure, insecure configurations
• Input validation, output encoding

Activation: Always active Purpose: Find performance bottlenecks.

Focuses on:

• N+1 queries, inefficient algorithms
• Memory leaks, unnecessary allocations
• Blocking operations, missing async
• Bundle size, lazy loading

Activation: Always active (reports missing tests) Purpose: Validate test coverage and quality.

Focuses on:

• Test coverage for new code
• Edge case coverage
• Test design and maintainability
• Mocking appropriateness

Activation: Conditional (if FILE_COUNT > 50) Purpose: Review code organization.

Focuses on:

• Code organization and modularity
• Design pattern violations
• Dependency management
• SOLID principles

Activation: Conditional (if database detected) Purpose: Review database operations.

Focuses on:

• Query optimization, N+1 queries
• Missing indexes
• Transaction handling
• Connection pooling

Activation: Conditional (if API detected) Purpose: Review API design.

Focuses on:

• REST best practices
• Error handling and status codes
• Rate limiting, pagination
• API versioning

Activation: Conditional (if frontend detected) Purpose: Review frontend code.

Focuses on:

• Component design and composition
• State management patterns
• Performance (memoization, virtualization)
• Accessibility

Activation: Conditional (if backend detected) Purpose: Review backend service and domain logic.

Focuses on:

• Service boundaries and layering
• Domain logic correctness
• Concurrency and idempotency
• Background job safety

Activation: Conditional (if CI/CD detected) Purpose: Review infrastructure and CI/CD.

Focuses on:

• Pipeline configuration
• Secret management
• Docker best practices
• Deployment strategies

Model: opus Purpose: Research any topic online and create comprehensive learning guides with RAG-optimized indexes.

What it does:

1. Uses progressive query architecture (funnel approach: broad → specific → deep)
2. Gathers 10-40 online sources based on depth level
3. Scores sources by authority, recency, depth, examples, uniqueness
4. Uses just-in-time retrieval to save tokens (only fetches high-scoring sources)
5. Creates structured learning guides with examples and best practices
6. Updates CLAUDE.md/AGENTS.md master indexes for future RAG lookups
7. Runs enhance:enhance-docs and enhance:enhance-prompts for quality

Tools available:

• WebSearch, WebFetch, Read, Write, Glob, Grep, Skill

Output:

• Topic-specific guide in agent-knowledge/
• Updated master index in agent-knowledge/CLAUDE.md
• Source metadata with quality scores in agent-knowledge/resources/

Model: sonnet Purpose: Lint agent configuration files using agnix CLI.

What it does:

1. Parses arguments (path, --fix, --strict, --target)
2. Invokes the agnix skill with the appropriate flags
3. Returns structured validation results

Tools available:

• Bash(agnix:), Bash(cargo:), Skill, Read, Glob, Grep

Output:

• Structured JSON with error/warning counts
• List of diagnostics with file, line, rule, message
• Fix status if --fix was used

Model: sonnet Purpose: Orchestrate pre-ship quality gate pipeline via skill.

What it does:

1. Runs prepare-delivery:test-coverage-checker and prepare-delivery:delivery-validator in sequence
2. Aggregates pass/fail results into a single quality gate verdict
3. Blocks shipping if any mandatory check fails

Tools available:

• Bash (git, npm)
• Skill, Task, Read, Grep, Glob

Model: sonnet Purpose: Validate test quality for new code.

What it does:

1. Identifies new/modified functions
2. Checks if tests exist
3. Checks if tests are meaningful (not just path matching)
4. Reports coverage status

Tools available:

• Bash (git, npm)
• Read, Grep, Glob

Advisory only: Does not block workflow. Reports findings but continues.

Model: sonnet Purpose: Final validation before shipping.

Checks:

1. Review status - no open issues (or explicit override)
2. Tests pass
3. Build passes
4. Task requirements met (extracts from task, maps to changes)
5. No regressions

Tools available:

• Bash (git, npm)
• Read, Grep, Glob

On failure: Returns to implementation with fix instructions.

Restrictions:

• MUST NOT create PR
• MUST NOT push
• MUST NOT skip sync-docs:sync-docs-agent

No agents - command-only orchestrator that delegates to prepare-delivery and ship plugins.

Model: sonnet Purpose: Cross-tool AI consultation - get a second opinion from another AI tool.

What it does:

1. Formats context and question for the target tool (Gemini, Codex, Claude, OpenCode, Copilot)
2. Invokes the target tool non-interactively
3. Returns the structured response for comparison

Tools available:

• Bash, Read, Glob, Grep, Skill

Model: sonnet Purpose: Structured multi-round debate between AI tools.

What it does:

1. Frames the debate topic and assigns positions to AI tools
2. Manages rounds - each tool argues, then rebuts
3. Synthesizes final summary with key agreements and disagreements

Tools available:

• Bash, Read, Glob, Grep, Skill

Model: sonnet Purpose: Browser automation with persistent state.

What it does:

1. Manages headless browser sessions with auth handoff
2. Navigates pages, extracts content, fills forms
3. Maintains session state across multiple interactions

Tools available:

• Bash, Read, Write, Skill

Model: sonnet Purpose: Versioned release with automatic ecosystem detection.

What it does:

1. Detects ecosystem (npm, cargo, go, etc.) and version strategy
2. Bumps version, creates changelog entry, tags release
3. Delegates publish to CI via tag push or gh release create

Tools available:

• Bash (git, gh, npm, cargo)
• Read, Write, Glob, Grep

Model: opus Purpose: Suggest skills, hooks, and agents from observed workflow patterns.

What it does:

1. Reads compacted knowledge themes from transcript analysis
2. Identifies repetitive manual patterns that could be automated
3. Recommends new skills, hooks, or agents with draft implementations

Tools available:

• Read, Glob, Grep, Write

Why opus: Pattern synthesis across diverse workflows requires deep reasoning to distinguish signal from noise.

Model: sonnet Purpose: Compact transcripts into knowledge files.

What it does:

1. Reads raw transcripts from Claude Code, Codex, or OpenCode
2. Extracts observations and clusters them into knowledge themes
3. Writes compacted knowledge files for skillers-recommender

Tools available:

• Read, Write, Glob, Grep, Bash

Model: sonnet Purpose: Codebase onboarding - project orientation for newcomers.

What it does:

1. Scans project structure, README, and config files
2. Identifies architecture patterns, key entry points, and conventions
3. Generates a concise orientation guide tailored to the contributor's role

Tools available:

• Read, Glob, Grep, Bash (git)

Model: sonnet Purpose: Match contributor skills to project needs.

What it does:

1. Scans open issues, good-first-issue labels, and help-wanted tags
2. Profiles contributor strengths from their history or stated skills
3. Returns ranked list of issues the contributor is best suited to tackle

Tools available:

• Bash (gh, git)
• Read, Glob, Grep

Key insight: For enhancers and analyzers, quality loss is exponential. Each imperfection in analysis creates downstream problems.

Agents have restricted tool access for safety:

← Back to Documentation Index | Main README

Related:

• /next-task Workflow - How agents orchestrate together
• /ship Workflow - Shipping agents in action