agent-system

7 specialized AI agents that plan, implement, verify, review, and ship code together.

Built for multi-agent AI coding environments. Each agent has a clear role, hard rules it follows, and knows how to work with the others.

Quick start

# Install to your project
npx agent-system init

# Or install globally (available in all projects)
npx agent-system init --global

This copies the agent instruction files to ./agents/ (or ~/.claude/agents/ with --global). Point your AI coding tool at them.

The agents

| Agent | Role | Writes code? | |-------|------|:------------:| | Coordinator | Plans, delegates to specialists, verifies results. Orchestrates parallel work. | No | | Developer | Plans AND implements. Solo end-to-end agent for focused tasks. | Yes | | Implementor | Executes a single task from a task note. Minimal scope, no freelancing. | Yes | | Verifier | Evidence-based verification against acceptance criteria. No vibes. | No | | UI Designer | Builds accessible, design-system-consistent interfaces. | Yes | | PR Reviewer | Reviews diffs for bugs, security, correctness. High signal, low noise. | No | | PR Shepherd | Loops until a PR is merge-ready: green CI, resolved comments, clean state. | No |

When to use which

Is this a PR that needs work?
├── Reviewing code? → PR Reviewer
├── Getting to green? → PR Shepherd
└── Building something?
    ├── Focused task (1-3 files)? → Developer
    └── Large feature (4+ files, parallelizable)? → Coordinator

| Situation | Agent | Why | |-----------|-------|-----| | Fix a bug | Developer | One agent, full context, fast | | Add a small feature | Developer | Plans + implements, quick iteration | | Build a multi-part feature | Coordinator | Parallel implementors, separate verification | | UI component with a11y requirements | UI Designer | Design system + accessibility expertise | | Code review before merge | PR Reviewer | Catches real bugs, skips nitpicks | | PR has failing CI or open comments | PR Shepherd | Loops until green | | Check work against spec | Verifier | Evidence-driven, no bias |

How they work together

Solo workflow (Developer)

One agent handles everything:

You → Developer
       ├── Spec → wait for approval
       ├── Implement task by task
       ├── Self-verify
       └── Report

Team workflow (Coordinator)

Parallel implementation with independent verification:

You → Coordinator
       ├── Spec → wait for approval
       ├── Wave 1: [Implementor A] [Implementor B] [UI Designer C]  ← parallel
       │            ↓
       │          Verifier
       ├── Wave 2: [Implementor D] [Implementor E]  ← parallel
       │            ↓
       │          Verifier
       └── Final verification

Full pipeline (plan → build → review → ship)

Coordinator → Implementors (waves) → Verifier → PR Reviewer → PR Shepherd → You merge

Core design principles

Spec first, always. No agent writes code without a written, approved plan. The approval gate is non-negotiable.

Separation of concerns. No single agent plans, implements, AND verifies. The agent that writes the code is never the agent that checks it.

Minimal changes. Every agent does only what its task asks. No scope creep, no drive-by refactors, no "while I'm here" improvements.

Evidence over vibes. The Verifier doesn't check if code "looks good." It checks each acceptance criterion with concrete evidence — test output, file diffs, observed behavior.

Parallel by default. The Coordinator splits work into waves of 2-4 non-overlapping tasks that run simultaneously. Sequential when tasks share files, parallel when they don't.

Customizing

Each agent is a standalone markdown file. You can:

• Edit any agent to match your workflow or conventions
• Remove agents you don't need (the Implementor and Developer work independently)
• Add new agents following the same pattern (role, hard rules, workflow, completion)

The agents reference tool functions like delegate_task, create_agent, report_to_parent, etc. These map to your platform's multi-agent capabilities. Adapt the tool names to match your environment.

What's in each file

agents/
├── Coordinator.md    # Orchestrator — plans, delegates, never codes
├── Developer.md      # Solo agent — plans AND implements
├── Implementor.md    # Worker — executes one task, reports back
├── Verifier.md       # QA — evidence-based acceptance testing
├── UI Designer.md    # Frontend specialist — a11y, design systems
├── PR Reviewer.md    # Code reviewer — bugs and security only
├── PR Shepherd.md    # PR ops — CI, comments, merge readiness
└── ORCHESTRATION.md  # How all agents work together (the spec)

ORCHESTRATION.md is the reference doc — it covers all workflows, communication patterns, decision trees, and anti-patterns.

CLI

npx agent-system init              # Copy to ./agents/
npx agent-system init --global     # Copy to ~/.claude/agents/
npx agent-system init --force      # Overwrite existing files
npx agent-system list              # Show available agents
npx agent-system help              # Show help

License

MIT