aicats

AI Coordinated Agent Team System — Multi-agent workflow for GitHub Copilot with complexity-based routing, a skills library, structured session memory, and 13 specialist agents.

npx aicats init

Overview

aicats scaffolds 13 GitHub Copilot custom agents, a skills library, agent workflows, prompt templates, instruction files, and a structured .aicats/ project directory into your project. The Team Lead scores task complexity, selects the right execution path, and routes to the appropriate specialists — from a single-agent Compact path to a Full Convoy for large features.

User Request → [Team Lead scores complexity]
                    │
              ┌─────┴──────────────┐
         Score 1-2             Score 3-5            Score 6+
         Compact               Standard             Full Convoy
              │                    │                    │
       1 Specialist         2-3 Specialists       Full Pipeline
                                                  (all agents)

Installation

One-time global install (recommended):

npm install -g aicats

Or use directly with npx:

npx aicats init

Quick Start

# 1. Go to your project
cd my-project

# 2. Initialize AICATS (agents + skills + .aicats/ directory)
npx aicats init

# 3. Fill in your project context
code .aicats/project.instructions.md

# 4. Open Copilot Chat in VS Code, use @aicats-team-lead
# 5. Describe your task — the agents handle the rest

CLI Commands

| Command | Description | |---------|-------------| | aicats init | Initialize AICATS (agents, skills, .aicats/) | | aicats init --force | Re-initialize, overwriting existing files | | aicats init --no-skills | Skip skills, workflows, prompts, instructions | | aicats manifest | Show installation manifest | | aicats log | List all session log dates | | aicats log --latest | Show the most recent session logs | | aicats log --date YYYY-MM-DD | Show logs for a specific date | | aicats log --type session --agent "..." --outcome success | Append a session event | | aicats lesson | View all lessons learned | | aicats lesson --add "text" | Add a new lesson learned | | aicats lesson --add "text" --category patterns | Add with category |

aicats log --type Events

# Session event
aicats log --type session --agent "AICATS Developer" --model "claude-sonnet-4-5" \
  --task "Add auth endpoint" --outcome success --duration_min 12 --files_changed 3

# Delegation event
aicats log --type delegation --agent "AICATS QA" --outcome success --phase qa --session_id TASK-42

# Review event
aicats log --type review --agent "AICATS Reviewer" --verdict pass --issues_minor 2

# Panel event
aicats log --type panel --verdict pass --pass_count 2 --block_count 0

# Dispute event
aicats log --type dispute --dispute_id DSP-001 --status open --priority high

Agent Roster

| Agent | Invoke as | Role | Tier | |-------|-----------|------|------| | Team Lead | @aicats-team-lead | Orchestrator (start here) | Quality | | Developer | @aicats-developer | Full-stack implementation | Quality | | UI/UX Expert | @aicats-uiux | Design & accessibility (WCAG) | Quality | | QA Expert | @aicats-qa | Testing, validation, coverage | Quality | | Security Expert | @aicats-security | OWASP, RLS, schema validation | Quality | | Architect | @aicats-architect | Architecture decisions, ADRs | Quality | | Researcher | @aicats-researcher | Codebase exploration | Standard | | Performance | @aicats-performance | Profiling, optimization | Standard | | Data | @aicats-data | Data pipelines, schemas | Fast | | DevOps | @aicats-devops | CI/CD, infrastructure | Fast | | Docs Writer | @aicats-docs-writer | Documentation | Economy | | Release Manager | @aicats-release-manager | Versioning, changelogs | Fast | | Reviewer | (Team Lead only) | Fast code review | Economy |

Skills Library

13 domain skills installed to .github/skills/. Agents load them on-demand.

| Skill | Purpose | |-------|---------| | team-lead-reference | Full Team Lead protocol | | decomposition | Task breakdown strategy | | orchestration-protocols | Delegation and retry rules | | session-checkpoints | Milestone handling | | observability-logging | NDJSON session log protocol | | validation-gates | Pre-merge verification gates | | fast-review | Quick code review protocol | | self-improvement | LESSONS-LEARNED write-back | | agent-memory | Cross-session memory access | | context-map | Codebase orientation | | agent-hooks | Pre/post hooks for agent actions | | panel-majority-vote | Multi-reviewer consensus | | memory-merger | Merge agent memory across sessions |

Agent Workflows

Pre-built workflow templates in .github/agent-workflows/:

| Workflow | Use For | |----------|---------| | feature-implementation.md | Full feature from PRD to delivery | | bug-fix.md | Diagnosis, fix, regression test | | security-audit.md | Standalone OWASP audit | | refactoring.md | Safe incremental refactor | | performance-optimization.md | Profile, optimize, verify | | shared-delivery-phase.md | Shared final delivery gates |

Prompt Templates

Ready-to-use prompts in .github/prompts/:

| Prompt | Use For | |--------|---------| | implement-feature.prompt.md | Start a feature from a description | | bug-fix.prompt.md | Structured bug diagnosis and fix | | brainstorm.prompt.md | Ideation and approach exploration | | quick-refinement.prompt.md | Small improvements to existing code | | generate-prd.prompt.md | Generate a PRD from an idea | | validate-prd.prompt.md | Validate a PRD before implementation |

.aicats/ Directory

.aicats/
├── manifest.json           — AICATS version and managed paths
├── project.instructions.md — ← Fill this in: your stack, ports, conventions
├── LESSONS-LEARNED.md      — Collective agent memory (read by all agents)
├── KNOWN-ISSUES.md         — Accepted limitations and workarounds
├── AGENT-FAILURES.md       — Dead Letter Queue
├── AGENT-PERFORMANCE.md    — Success metrics and query recipes
├── AGENT-EXPERTISE.md      — Per-agent file familiarity
├── KNOWLEDGE-GRAPH.md      — Append-only codebase relationship log
├── DISPUTES.md             — Panel blocks requiring human input
├── agents/
│   ├── agent-registry.md   — All agents with model assignments
│   ├── skill-matrix.json   — Skill slot assignments (machine-readable)
│   └── skill-matrix.md     — Skill documentation
├── logs/
│   ├── README.md           — NDJSON event schema
│   └── events.ndjson       — Session event log
└── project/
    ├── roadmap.md
    └── decisions.md        — Architecture Decision Records (ADR)

What Gets Created by init

.github/
├── agents/              13 Copilot custom agents
├── skills/              13 domain skill files
├── agent-workflows/     6 workflow templates
├── prompts/             6 prompt templates
├── instructions/        2 workspace instruction files
└── copilot-instructions.md

.aicats/
├── manifest.json
├── project.instructions.md
├── LESSONS-LEARNED.md
├── KNOWN-ISSUES.md
├── AGENT-FAILURES.md
├── AGENT-PERFORMANCE.md
├── AGENT-EXPERTISE.md
├── KNOWLEDGE-GRAPH.md
├── DISPUTES.md
├── agents/
├── logs/
└── project/

Feature Comparison

| Feature | v1.x | v2.x | |---------|------|------| | Agents | 5 | 13 | | Skills library | ❌ | ✅ 13 skills | | Agent workflows | ❌ | ✅ 6 workflows | | Prompt templates | ❌ | ✅ 6 prompts | | Instruction files | ❌ | ✅ 2 instructions | | Complexity scoring | ❌ | ✅ Fibonacci 1–13 | | NDJSON event log | ❌ | ✅ aicats log --type | | Manifest command | ❌ | ✅ aicats manifest | | Session memory | Basic | ✅ Full .aicats/ | | RLS checks | ❌ | ✅ Security agent | | Schema validation | ❌ | ✅ Zod checks | | Panel voting | ❌ | ✅ panel-majority-vote | | Dead Letter Queue | ❌ | ✅ AGENT-FAILURES.md |

Requirements

• Node.js 18+
• VS Code with GitHub Copilot extension
• Copilot Chat with agent mode enabled

License

MIT

Overview

aicats scaffolds five GitHub Copilot custom agents into your project, each with a focused role, strict constraints, and structured report output. The Team Lead orchestrates the other four agents in a fixed sequential pipeline, saves logs after each phase, and builds a cumulative resume of every session.

User Request
    │
    ▼
[Team Lead]       Analysis & planning
    ▼
[Developer]       Code implementation
    ▼
[UI/UX Expert]    Design & accessibility review
    ▼
[QA Expert]       Testing & validation
    ▼
[Security Expert] OWASP Top 10 audit
    ▼
[Team Lead]       Final summary, logs, lesson-learned

Installation

One-time global install (recommended):

npm install -g aicats

Or use directly with npx (no install needed):

npx aicats init

Quick Start

# 1. Go to your project
cd my-project

# 2. Initialize AICATS
npx aicats init

# 3. Open Copilot Chat in VS Code and select @aicats-team-lead
# 4. Describe your task — the agents handle the rest

CLI Commands

| Command | Description | |---------|-------------| | aicats init | Initialize AICATS in the current project | | aicats init --force | Re-initialize, overwriting existing agent files | | aicats resume | Show the latest session summary | | aicats log | List all session log dates | | aicats log --latest | Show the most recent session logs | | aicats log --date YYYY-MM-DD | Show logs for a specific date | | aicats lesson | View all lessons learned | | aicats lesson --add "text" | Add a new lesson learned | | aicats lesson --add "text" --category patterns | Add with category |

Lesson categories: architecture · patterns · tools · process · security · ux · general

Agents

@aicats-team-lead

The Orchestrator. Start every complex task here.

• Analyzes the request and creates a task plan
• Delegates to each specialist in sequence
• Aggregates all reports into a final session summary
• Updates .aicats/resume.md and .aicats/sessions-YYYY.md
• Records lessons learned from user feedback

@aicats-team-lead  Add a paginated data table with server-side sorting

@aicats-developer

Senior full-stack developer.

• Implements features, fixes bugs, refactors code
• Follows existing project conventions
• Produces a structured Developer Report including what changed, key decisions, and handoff notes for QA and Security

@aicats-developer  Refactor the auth service to use dependency injection

@aicats-uiux

UI/UX designer & accessibility specialist.

• Reviews UI components against WCAG 2.1 AA
• Checks design consistency (spacing, typography, colors, patterns)
• Evaluates user flows for clarity and intuitiveness
• Produces a UI/UX Report with severity-tagged issues

@aicats-uiux  Review the new onboarding modal for accessibility issues

@aicats-qa

QA engineer.

• Validates the implementation against requirements
• Identifies edge cases, missing error handling, and coverage gaps
• Writes or suggests test cases in Given/When/Then format
• Assesses regression risk

@aicats-qa  Write test cases for the new checkout flow

@aicats-security

Application security engineer.

• Performs an OWASP Top 10 audit on all changed code
• Reviews auth, authorization, input validation, and data protection
• Scans the dependency manifest for known vulnerabilities
• Produces a Security Report — never approves Critical findings

@aicats-security  Audit the new file upload endpoint

Logs & Resume

After aicats init, these are created in your project:

.aicats/
├── resume.md                    ← Latest session summary (always overwritten, stays small)
├── sessions-YYYY.md             ← Sessions history per year (e.g. sessions-2026.md)
├── lesson-learned/
│   └── YYYY-MM-DD.md            ← Lessons from user feedback
└── YYYY-MM-DD/
    ├── HH-MM-SS-plan.md         ← Team Lead's task plan
    ├── developer-HH-MM-SS.md    ← Developer report
    ├── uiux-HH-MM-SS.md         ← UI/UX report
    ├── qa-HH-MM-SS.md           ← QA report
    └── security-HH-MM-SS.md     ← Security report

View the latest session:

aicats resume
aicats log --latest

Lesson Learned System

Agents automatically extract and save lessons when you provide feedback or corrections.

You can also add lessons manually:

aicats lesson --add "always use React Query for server state" --category patterns
aicats lesson --add "validate file MIME type server-side, not just extension" --category security
aicats lesson  # view all lessons

Lessons are stored in .aicats/lesson-learned/YYYY-MM-DD.md and read back by the Team Lead at the start of each new session.

Configuration

.aicats/config.json is created inside the .aicats/ folder:

{
  "version": "1.0.0",
  "project": "my-project",
  "initialized": "2026-04-30T00:00:00.000Z",
  "workflow": [
    "aicats-team-lead",
    "aicats-developer",
    "aicats-uiux",
    "aicats-qa",
    "aicats-security"
  ],
  "logs": {
    "directory": ".aicats",
    "lessonLearned": ".aicats/lesson-learned"
  }
}

What Gets Created by init

After aicats init, these are created in your project:

.github/
├── agents/
│   ├── aicats-team-lead.agent.md
│   ├── aicats-developer.agent.md
│   ├── aicats-uiux.agent.md
│   ├── aicats-qa.agent.md
│   └── aicats-security.agent.md
└── copilot-instructions.md      ← AICATS section appended (or created)
.aicats/
├── config.json
├── resume.md
├── sessions-YYYY.md
└── lesson-learned/

Requirements

• Node.js 18+
• VS Code with GitHub Copilot extension
• Copilot Chat with agent mode enabled

License

MIT