ai-agents

# AI Agent System

> A coordinated multi-agent framework for AI-powered software development workflows.

[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/rjmurillo/ai-agents)

![GitHub commits since latest release](https://img.shields.io/github/commits-since/rjmurillo/ai-agents/latest)
![GitHub commit activity](https://img.shields.io/github/commit-activity/w/rjmurillo/ai-agents)
![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/rjmurillo/ai-agents)

![AI Issue Triage](https://github.com/rjmurillo/ai-agents/actions/workflows/ai-issue-triage.yml/badge.svg)
![AI PR Quality Gate](https://github.com/rjmurillo/ai-agents/actions/workflows/ai-pr-quality-gate.yml/badge.svg)
![Spec-to-Implementation Validation](https://github.com/rjmurillo/ai-agents/actions/workflows/ai-spec-validation.yml/badge.svg)
![Pester Tests](https://github.com/rjmurillo/ai-agents/actions/workflows/pester-tests.yml/badge.svg)
![CodeQL Analysis](https://github.com/rjmurillo/ai-agents/actions/workflows/codeql-analysis.yml/badge.svg)

---

## TL;DR

1. **Install:** `/install-plugin rjmurillo/ai-agents` (Claude Code or GitHub Copilot CLI)
2. **Use:** Ask the orchestrator to coordinate tasks, or call agents directly by name
3. **Result:** 21 specialized agents handle research → planning → implementation → QA → deployment

```text
# Example: End-to-end feature development
> orchestrator: implement user authentication with OAuth2, including tests and security review
```

---

## Where to Start

| I want to... | Go to |
|--------------|-------|
| **Use the agents right now** | [Quick Install](#quick-install-recommended) → [Quick Start](#quick-start) |
| **Understand how it works** | [Key Concepts](#key-concepts) → [How Agents Work Together](#how-agents-work-together) |
| **Contribute or modify agents** | [Developer Setup](#developer-setup) → [CONTRIBUTING.md](CONTRIBUTING.md) |
| **See all available agents** | [Agent Catalog](#agent-catalog) |
| **Troubleshoot issues** | [Troubleshooting](#troubleshooting) |

---

## Is This For You?

✅ **Good fit if:**

- You use Claude Code, GitHub Copilot CLI, or VS Code with Copilot
- You want structured, multi-step AI workflows with clear accountability
- You need audit trails and consistent output formats
- You prefer specialized agents over generic prompting

❌ **Not ideal if:**

- You prefer single-prompt interactions without agent orchestration
- You're not using one of the supported platforms (Claude Code, Copilot CLI, VS Code)
- You need real-time streaming responses for all interactions

---

## Table of Contents

- [AI Agent System](#ai-agent-system)
  - [TL;DR](#tldr)
  - [Where to Start](#where-to-start)
  - [Is This For You?](#is-this-for-you)
  - [Table of Contents](#table-of-contents)
  - [Purpose and Scope](#purpose-and-scope)
    - [What is AI Agents?](#what-is-ai-agents)
    - [Core Capabilities](#core-capabilities)
    - [Key Concepts](#key-concepts)
  - [Installation](#installation)
    - [Quick Install (Recommended)](#quick-install-recommended)
    - [Verify Installation](#verify-installation)
    - [Supported Platforms](#supported-platforms)
    - [Alternative: Install via skill-installer](#alternative-install-via-skill-installer)
  - [Quick Start](#quick-start)
    - [Examples](#examples)
      - [Simple Scenarios](#simple-scenarios)
      - [Advanced Scenarios](#advanced-scenarios)
  - [System Architecture](#system-architecture)
    - [How Agents Work Together](#how-agents-work-together)
    - [Agent Catalog](#agent-catalog)
    - [Directory Structure](#directory-structure)
  - [Troubleshooting](#troubleshooting)
  - [Contributing](#contributing)
    - [Developer Setup](#developer-setup)
    - [Agent Development](#agent-development)
  - [Documentation](#documentation)
  - [License](#license)

---

## Purpose and Scope

### What is AI Agents?

AI Agents is a coordinated multi-agent system for software development. It provides specialized AI agents that handle different phases of the development lifecycle, from research and planning through implementation and quality assurance.

The orchestrator is the hub of operations. Within it has logic from taking everything from a "vibe" or a "shower thought" and building out a fully functional spec with acceptance criteria and user stories, to taking a well defined idea as input and executing on it. There are 21 agents that cover the roles of software development, from vision and strategy, to architecture, implementation, and verification. Each role looks at something specific, like the critic that just looks to poke holes in other agents' (or your own) work, or DevOps that's concerned about how you deploy and operate the thing you just built.

The agents themselves use the platform specific handoffs to invoke subagents, keeping the orchestrator context clean. A great example of this is orchestrator facilitating creating and debating an [Architectural Decision Record](https://adr.github.io/) from research and drafting, to discussion, iterating on the issues, tie breaking when agents don't agree. And then  extracting persistent knowledge to steer future agents to adhere. Artifacts are stored in your memory system if you have one enabled, and Markdown files for easy reference to both agents and humans.

### Core Capabilities

- **21 specialized agents** for different development phases (analysis, architecture, implementation, QA, etc.)
- **Explicit handoff protocols** between agents with clear accountability
- **Multi-Agent Impact Analysis Framework** for comprehensive planning
- **Cross-session memory** with citation verification, graph traversal, and health reporting via Serena + Forgetful
- **Self-improvement system** with skill tracking and retrospectives
- **Quality gates** with pre-PR validation, session protocol enforcement, and automated CI checks
- **50+ reusable skills** for common development workflows (git, PR management, testing, linting)
- **TUI-based installation** via [skill-installer](https://github.com/rjmurillo/skill-installer)
- **AI-powered CI/CD** with issue triage, PR quality gates, and spec validation

### Key Concepts

| Term | Definition |
|------|------------|
| **Agent** | A specialized AI persona with a defined role (analyst, implementer, security, etc.) |
| **Orchestrator** | The coordinating agent that routes tasks to specialists and synthesizes results |
| **Handoff** | Explicit transfer of context and control between agents with clear accountability |
| **Skill** | A reusable workflow component for common tasks (50+ included: git, PR, testing, linting) |
| **Memory** | Cross-session context persistence via Serena + Forgetful for knowledge retention |
| **ADR** | Architectural Decision Record—structured documents capturing design decisions |
| **Quality Gate** | Validation checkpoint (critic review, QA pass, security scan) before proceeding |

---

## Installation

> **Requirements:** Python 3.10+ and [UV](https://docs.astral.sh/uv/) package manager (for skill-installer method only). The `/install-plugin` method has no prerequisites.
>
> See [CONTRIBUTING.md](CONTRIBUTING.md#prerequisites) for full development setup including Python 3.14.x, pre-commit hooks, and test dependencies.

### Quick Install (Recommended)

The fastest way to get started is the CLI marketplace. Run the install command from within your AI coding tool.

**Claude Code** (in Claude Code CLI):

```text
/install-plugin rjmurillo/ai-agents
```

**GitHub Copilot CLI** (in Copilot CLI):

```text
/install-plugin rjmurillo/ai-agents
```

This installs the full agent set for your platform. You can also install individual components:

| Component | Install Command | What You Get |
|-----------|----------------|--------------|
| Claude agents only | `/plugin install claude-agents@ai-agents` | 26 specialized agents for Claude Code |
| Copilot CLI agents only | `/plugin install copilot-cli-agents@ai-agents` | Agent definitions for Copilot CLI |
| Full proj

[truncated…]