AIDA Plugin for Claude Code

AIDA (Agent Integration & Development Architecture) - Multi-agent orchestration framework for Claude Code.

English | 日本語 | 简体中文 | 繁體中文 | Русский | فارسی | العربية

Table of Contents

• Overview
• Requirements
• Installation
• Update
• Uninstall
• Usage Guide
• Command Reference
• Quality Gates
• Configuration
• Troubleshooting
• Contributing
• License

Overview

AIDA enables multi-agent orchestration for software development projects using Claude Code's Task tool to spawn subagents. It automates the entire development lifecycle from requirements to implementation with TDD (Test-Driven Development) enforcement.

Key Features

• Multi-Agent Orchestration: Automatically spawns and coordinates multiple Claude agents
• 5-Phase Workflow: Structured development from requirements to implementation
• 19 Quality Gates: Automated validation of code quality, tests, and coverage
• TDD Enforcement: Red-Green-Refactor cycle with evidence tracking
• Stack Support: Go + React + Docker (default), with extensibility for other stacks

Requirements

Required

Recommended

Install Dependencies

# Ubuntu/Debian
sudo apt install jq fzf git

# macOS
brew install jq fzf git

# Install grepai (recommended for semantic search)
go install github.com/yoanbernabeu/grepai@latest

# Install jj (optional - for environment isolation)
cargo install jj-cli

Installation

Method 1: One-Line Install (Recommended)

curl -sSL https://raw.githubusercontent.com/clearclown/claude-code-aida/main/scripts/install.sh | bash

Method 2: Manual Clone

# Clone repository
git clone https://github.com/clearclown/claude-code-aida.git ~/.claude-code-aida

# Run install script
cd ~/.claude-code-aida
./scripts/install.sh

Method 3: Install to Custom Location

# Clone to custom location
git clone https://github.com/clearclown/claude-code-aida.git /path/to/aida

# Install from that location
cd /path/to/aida
./scripts/install.sh

Verify Installation

# Check installation
./scripts/verify-installation.sh

# Restart Claude Code
claude

# Test command availability
/aida:status

If /aida shows "Unknown skill", restart Claude Code and try again.

What Gets Installed

~/.claude-code-aida/         # AIDA source files
~/.claude/commands/
  aida.md                    # Main /aida command
  aida/
    init.md                  # /aida:init
    start.md                 # /aida:start
    status.md                # /aida:status
    work.md                  # /aida:work
    pipeline.md              # /aida:pipeline
    enhance.md               # /aida:enhance
    analyze.md               # /aida:analyze
    maintain.md              # /aida:maintain
    import.md                # /aida:import
    resume.md                # /aida:resume
    fix.md                   # /aida:fix

Update

Automatic Update

# Navigate to AIDA directory
cd ~/.claude-code-aida

# Pull latest changes and reinstall
git pull origin main
./scripts/install.sh

Update Script

# One-line update
cd ~/.claude-code-aida && git pull origin main && ./scripts/install.sh

Update to Specific Version

cd ~/.claude-code-aida
git fetch --tags
git checkout v1.2.0  # Replace with desired version
./scripts/install.sh

Update from Specific Branch

cd ~/.claude-code-aida
git fetch origin
git checkout develop  # or feature/new-feature
git pull
./scripts/install.sh

Verify Update

# Check version/status
./scripts/verify-installation.sh

# Restart Claude Code after update
# Then test:
/aida:status

Uninstall

Complete Uninstall

# Remove command files
rm -f ~/.claude/commands/aida.md
rm -rf ~/.claude/commands/aida/

# Remove AIDA source directory
rm -rf ~/.claude-code-aida

# Optional: Remove project data (only do this if you don't need the data)
# rm -rf ~/.aida  # Global AIDA data

Partial Uninstall (Keep Source)

# Only remove command files (keeps source for reinstall)
rm -f ~/.claude/commands/aida.md
rm -rf ~/.claude/commands/aida/

Clean Project Data

# Remove AIDA data from a specific project
cd /path/to/project
rm -rf .aida/

Verify Uninstall

# Check commands are removed
ls ~/.claude/commands/aida* 2>/dev/null || echo "Commands removed"

# Check source directory
ls ~/.claude-code-aida 2>/dev/null || echo "Source removed"

Usage Guide

Basic Workflow

1. Create a New Project

# Create project directory
mkdir my-project && cd my-project

# Start Claude Code
claude

# Generate project with full pipeline
/aida "Create a blog platform with user authentication"

2. Step-by-Step Execution

# Initialize workspace
/aida:init

# Start specification phase
/aida:start "Create a Twitter clone"

# Check current status
/aida:status

# Continue work
/aida:work

3. Enhance Existing Project

# Navigate to existing project
cd /path/to/existing-project
claude

# Analyze and enhance
/aida:enhance . "Add user profile feature"

4. Import External Project

# Import from GitHub
/aida:import https://github.com/user/repo

# Import from local path
/aida:import /path/to/project

Advanced Usage

Resume Interrupted Session

/aida:resume

Fix Failing Quality Gates

/aida:fix

Run Quality Gates Manually

# Run all gates
./scripts/quality-gates.sh my-project

# Skip Docker gates
./scripts/quality-gates.sh my-project --skip-docker

# Skip frontend gates
./scripts/quality-gates.sh my-project --skip-frontend

# Verbose output
./scripts/quality-gates.sh my-project --verbose

Analyze Project Structure

/aida:analyze /path/to/project

Maintenance Tasks

# Update dependencies
/aida:maintain /path/to/project --update-deps

# Security audit
/aida:maintain /path/to/project --security-audit

Command Reference

Core Commands

Extended Commands

Utility Scripts

# Verify installation
./scripts/verify-installation.sh

# Run quality gates
./scripts/quality-gates.sh <project>

# Analyze project
./scripts/analyze-project.sh /path/to/project

# Parse requirements document
./scripts/parse-requirements.sh docs/requirements.md

# Setup jj for environment isolation
./scripts/setup-jj.sh

# Semantic search (requires grepai)
./scripts/semantic-search.sh "authentication logic"

# Interactive file picker (requires fzf)
./scripts/file-picker.sh code ./src

Quality Gates

AIDA enforces quality through 19 automated gates:

Basic Gates (1-7)

Extended Gates (8-19)

TDD Gate (20)

Configuration

Project Structure

.aida/                    # AIDA management directory
  state/
    session.json          # Session state
    coordinator.json      # Agent coordination
  specs/                  # Generated specifications
  artifacts/              # Intermediate work
  tdd-evidence/           # TDD cycle records
  fix-plans/              # Generated fix plans
  search-cache/           # Semantic search cache
  results/                # Completion reports

./                        # Generated project
  backend/                # Go backend
  frontend/               # React frontend
  docker-compose.yml      # Container config

Environment Variables

# Project directory override
export CLAUDE_PROJECT_DIR=/path/to/project

# Agent scaling configuration
export MAX_AGENTS=4
export MIN_AGENTS=1

# Token limit configuration
export AIDA_TOKEN_LIMIT=100000

Customization

Modify Quality Thresholds

Edit scripts/quality-gates.sh:

# Change test count requirements
MIN_BACKEND_TESTS=50   # Default: 80
MIN_FRONTEND_TESTS=70  # Default: 100

# Change coverage requirements
MIN_BACKEND_COVERAGE=60  # Default: 75
MIN_FRONTEND_COVERAGE=60 # Default: 70

Skip Specific Gates

# Skip Docker gates (no Docker installed)
./scripts/quality-gates.sh project --skip-docker

# Skip frontend gates (backend-only project)
./scripts/quality-gates.sh project --skip-frontend

Troubleshooting

Common Issues

"Unknown skill: aida"

Commands not installed:

cd ~/.claude-code-aida
./scripts/install.sh
# Restart Claude Code

Quality Gates Fail

# Check which gate failed
./scripts/quality-gates.sh project --verbose

# Skip Docker if unavailable
./scripts/quality-gates.sh project --skip-docker

# Generate fix plan
./scripts/generate-fix-plan.sh project

Session Stuck

# Check session state
cat .aida/state/session.json | jq .

# Reset session
rm .aida/state/session.json
/aida:init

grepai Not Found

# Install grepai
go install github.com/yoanbernabeu/grepai@latest

# Add to PATH
export PATH=$PATH:$(go env GOPATH)/bin

fzf Not Working

# Install fzf
sudo apt install fzf  # Ubuntu/Debian
brew install fzf      # macOS

Debug Information

# Full installation verification
./scripts/verify-installation.sh

# Check AIDA logs
ls -la .aida/logs/

# Check agent status
./scripts/agent-coordinator.sh status

# Check resource usage
./scripts/resource-monitor.sh status

Contributing

Contributions welcome! Areas of focus:

• Python/FastAPI stack support
• Node.js/Express stack support
• Rust/Axum stack support
• Configurable quality thresholds
• Better session recovery
• Improved project analysis
• More test coverage

Development Setup

# Clone for development
git clone https://github.com/clearclown/claude-code-aida.git
cd claude-code-aida

# Run tests
./tests/run-all-tests.sh

# Lint prompts
./scripts/prompt-lint.sh agents/

# Check installation
./scripts/verify-installation.sh

Test Coverage

Currently tested scripts (20 test suites):

• test-agent-coordinator.sh
• test-agent-scaler.sh
• test-analyze-project.sh
• test-common.sh
• test-enhancement-queue.sh
• test-file-picker.sh
• test-generate-fix-plan.sh
• test-install.sh
• test-jj-worktree.sh
• test-parse-requirements.sh
• test-prompt-lint.sh
• test-quality-gates.sh
• test-ralph-gate.sh
• test-resource-monitor.sh
• test-semantic-search.sh
• test-setup-jj.sh
• test-task-seeker.sh
• test-tdd-logger.sh
• test-validate-completion.sh
• test-verify-installation.sh

License

MIT

Credits & Acknowledgments

Core Technologies

Infrastructure

Links

• GitHub Repository
• Issues
• Discussions