AI Dev Pipeline (aidp) - Ruby Gem

A portable CLI that automates AI development workflows from idea to implementation using your existing IDE assistants. Features autonomous work loops, background execution, and comprehensive progress tracking.

Quick Start

# Install the gem
gem install aidp

# Navigate to your project
cd /your/project

# Launch the interactive configuration wizard
aidp config --interactive

# Analyze and bootstrap project docs
aidp init
# Creates LLM_STYLE_GUIDE.md, PROJECT_ANALYSIS.md, CODE_QUALITY_PLAN.md

# Start Copilot interactive mode (default)
aidp

First-Time Setup

On the first run in a project without an aidp.yml, AIDP launches a First-Time Setup Wizard. You'll be prompted to choose one of:

1. Minimal (single provider: cursor)
2. Development template (multiple providers, safe defaults)
3. Production template (full-feature example – review before committing)
4. Full example (verbose documented config)
5. Custom (interactive prompts for providers and defaults)

Non-interactive environments (CI, scripts, pipes) automatically receive a minimal aidp.yml so workflows can proceed without manual intervention.

You can re-run the wizard manually:

aidp --setup-config

Devcontainer Support

AIDP provides first-class devcontainer support for sandboxed, secure AI agent execution. Devcontainers offer:

• Network Security: Strict firewall with allowlisted domains only
• Sandboxed Environment: Isolated from your host system
• Elevated Permissions: AI agents can run with full permissions inside the container
• Consistent Setup: Same environment across all developers

For AIDP Development

This repository includes a .devcontainer/ setup for developing AIDP itself:

# Open in VS Code
code .

# Press F1 → "Dev Containers: Reopen in Container"
# Container builds automatically with Ruby 3.4.5, all tools, and firewall

# Run tests inside container
bundle exec rspec

# Run AIDP inside container
bundle exec aidp

See .devcontainer/README.md for complete documentation.

Generating Devcontainers for Your Projects

Use aidp init to generate a devcontainer for any project:

# Initialize project with devcontainer
aidp init

# When prompted:
# "Generate devcontainer configuration for sandboxed development?" → Yes

# Or use the flag directly
aidp init --with-devcontainer

This creates:

• .devcontainer/Dockerfile - Customized for your project's language/framework
• .devcontainer/devcontainer.json - VS Code configuration and extensions
• .devcontainer/init-firewall.sh - Network security rules
• .devcontainer/README.md - Setup and usage documentation

Elevated Permissions in Devcontainers

When running inside a devcontainer, you can enable elevated permissions for AI agents:

# aidp.yml
devcontainer:
  enabled: true
  full_permissions_when_in_devcontainer: true  # Run all providers with full permissions

  # Or enable per-provider
  permissions:
    skip_permission_checks:
      - claude  # Adds --dangerously-skip-permissions for Claude Code

AIDP automatically detects when it's running in a devcontainer and adjusts agent permissions accordingly. This is safe because the container is sandboxed from your host system.

Core Features

Work Loops

AIDP implements work loops - an iterative execution pattern where AI agents autonomously work on tasks until completion, with automatic testing and linting feedback.

• Iterative refinement: Agent works in loops until task is 100% complete
• Self-management: Agent edits PROMPT.md to track its own progress
• Automatic validation: Tests and linters run after each iteration
• Self-correction: Only failures are fed back for the next iteration

See Work Loops Guide for details.

Job Management

Monitor and control background jobs:

# List and manage jobs
aidp jobs list                        # List all jobs
aidp jobs status <job_id>             # Show job status
aidp jobs logs <job_id> --tail        # View recent logs
aidp checkpoint summary --watch       # Watch metrics in real-time

# Control jobs
aidp jobs stop <job_id>               # Stop a running job

Progress Checkpoints

Track code quality metrics and task progress throughout execution:

# View current progress
aidp checkpoint summary

# Watch with auto-refresh
aidp checkpoint summary --watch

# View historical data
aidp checkpoint history 20

Tracked Metrics:

• Lines of code
• Test coverage
• Code quality scores
• PRD task completion percentage
• File count and growth trends

Parallel Workstreams

Work on multiple tasks simultaneously using isolated git worktrees:

# Create a workstream for each task
aidp ws new issue-123-fix-auth
aidp ws new feature-dashboard

# List all workstreams
aidp ws list

# Check status
aidp ws status issue-123-fix-auth

# Remove when complete
aidp ws rm issue-123-fix-auth --delete-branch

Benefits:

• Complete isolation between tasks
• Separate git branches for each workstream
• Independent state and history
• Work on multiple features in parallel

See Workstreams Guide for detailed usage.

Command Reference

Copilot Mode

# Start interactive Copilot mode (default)
aidp                            # AI-guided workflow selection

# Copilot can perform both analysis and development based on your needs
# It will interactively help you choose the right approach

Job Management

# List all background jobs
aidp jobs list

# Show job status
aidp jobs status <job_id>
aidp jobs status <job_id> --follow  # Follow with auto-refresh

# View job logs
aidp jobs logs <job_id>
aidp jobs logs <job_id> --tail      # Last 50 lines
aidp jobs logs <job_id> --follow    # Stream in real-time

# Stop a running job
aidp jobs stop <job_id>

Checkpoint Monitoring

# View latest checkpoint
aidp checkpoint show

# Progress summary with trends
aidp checkpoint summary
aidp checkpoint summary --watch             # Auto-refresh every 5s
aidp checkpoint summary --watch --interval 10  # Custom interval

# View checkpoint history
aidp checkpoint history           # Last 10 checkpoints
aidp checkpoint history 50        # Last 50 checkpoints

# Detailed metrics
aidp checkpoint metrics

# Clear checkpoint data
aidp checkpoint clear
aidp checkpoint clear --force     # Skip confirmation

Workstream Commands

# Create a new workstream
aidp ws new <slug>
aidp ws new <slug> --base-branch <branch>

# List all workstreams
aidp ws list

# Check workstream status
aidp ws status <slug>

# Remove a workstream
aidp ws rm <slug>
aidp ws rm <slug> --delete-branch  # Also delete git branch
aidp ws rm <slug> --force          # Skip confirmation

System Commands

# Show system status
aidp status

# Provider health dashboard
aidp providers

# Harness state management
aidp harness status
aidp harness reset

# Configuration
aidp --setup-config             # Re-run setup wizard
aidp --help                     # Show all commands
aidp --version                  # Show version

AI Providers

AIDP intelligently manages multiple providers with automatic switching:

• Anthropic Claude CLI - Primary provider for complex analysis and code generation
• Codex CLI - OpenAI's Codex command-line interface for code generation
• Cursor CLI - IDE-integrated provider for code-specific tasks
• Gemini CLI - Google's Gemini command-line interface for general tasks
• GitHub Copilot CLI - GitHub's AI pair programmer command-line interface
• macOS UI - macOS-specific UI automation provider
• OpenCode - Alternative open-source code generation provider

The system automatically switches providers when:

• Rate limits are hit
• Providers fail or timeout
• Cost limits are reached
• Performance optimization is needed

Provider Configuration

# aidp.yml
harness:
  work_loop:
    enabled: true
    max_iterations: 50
    test_commands:
      - "bundle exec rspec"
    lint_commands:
      - "bundle exec standardrb"
    units:
      deterministic:
        - name: run_full_tests
          command: "bundle exec rake spec"
          enabled: false
          next:
            success: agentic
            failure: decide_whats_next
        - name: wait_for_github
          type: "wait"
          metadata:
            interval_seconds: 60
      defaults:
        on_no_next_step: wait_for_github
        fallback_agentic: decide_whats_next

providers:
  claude:
    type: "usage_based"
    api_key: "${AIDP_CLAUDE_API_KEY}"
    max_tokens: 100000
  gemini:
    type: "usage_based"
    api_key: "${AIDP_GEMINI_API_KEY}"
    max_tokens: 50000
  cursor:
    type: "subscription"

Environment Variables

# Set API keys
export AIDP_CLAUDE_API_KEY="your-claude-api-key"
export AIDP_GEMINI_API_KEY="your-gemini-api-key"

Tree-sitter Static Analysis

AIDP includes powerful Tree-sitter-based static analysis capabilities for code.

Tree-sitter Dependencies

The Tree-sitter analysis requires the Tree-sitter system library and pre-compiled language parsers:

# Install Tree-sitter system library
# macOS
brew install tree-sitter

# Ubuntu/Debian
sudo apt-get install tree-sitter

# Or follow the ruby_tree_sitter README for other platforms
# https://github.com/Faveod/ruby-tree-sitter#installation

# Install Tree-sitter parsers
./install_tree_sitter_parsers.sh

Parser Installation Script

The install_tree_sitter_parsers.sh script automatically downloads and installs pre-built Tree-sitter parsers:

# Make the script executable
chmod +x install_tree_sitter_parsers.sh

# Run the installation script
./install_tree_sitter_parsers.sh

The script will:

• Detect your OS and architecture (macOS ARM64, Linux x64, etc.)
• Download the appropriate parser bundle from Faveod/tree-sitter-parsers
• Extract parsers to .aidp/parsers/ directory
• Set up the TREE_SITTER_PARSERS environment variable

Environment Setup

After running the installation script, make the environment variable permanent:

# Add to your shell profile (e.g., ~/.zshrc, ~/.bashrc)
echo 'export TREE_SITTER_PARSERS="$(pwd)/.aidp/parsers"' >> ~/.zshrc

# Reload your shell
source ~/.zshrc

Knowledge Base Structure

The Tree-sitter analysis generates structured JSON files in .aidp/kb/:

• symbols.json - Classes, modules, methods, and their metadata
• imports.json - Require statements and dependencies
• calls.json - Method calls and invocation patterns
• metrics.json - Code complexity and size metrics
• seams.json - Integration points and dependency injection opportunities
• hotspots.json - Frequently changed code areas (based on git history)
• tests.json - Test coverage analysis
• cycles.json - Circular dependency detection

Legacy Code Analysis Features

The Tree-sitter analysis specifically supports:

• Seam Detection: Identifies I/O operations, global state access, and constructor dependencies
• Change Hotspots: Uses git history to identify frequently modified code
• Dependency Analysis: Maps import relationships and call graphs
• Test Coverage: Identifies untested public APIs
• Refactoring Opportunities: Suggests dependency injection points and seam locations

File-Based Interaction

At gate steps, the AI creates files for interaction instead of requiring real-time chat:

• Questions files: PRD_QUESTIONS.md, ARCH_QUESTIONS.md, TASKS_QUESTIONS.md, IMPL_QUESTIONS.md - Contains questions if AI needs more information
• Output files: docs/PRD.md, docs/Architecture.md - Review and edit as needed
• Progress tracking: .aidp-progress.yml - Tracks completion status

Answering Questions

When the AI creates a questions file, follow these steps:

1. Edit the file directly: Add your answers below each question in the file
2. Re-run the step: The AI will read your answers and complete the step
3. Approve when satisfied: Mark the step complete and continue

The questions file is only created when the AI needs additional information beyond what it can infer from your project structure and existing files. Your answers are preserved for future reference.

Workflow Examples

Standard Interactive Workflow

# Start Copilot mode (default)
aidp

# Copilot will guide you through:
# - Understanding your project goals
# - Selecting the right workflow (analysis, development, or both)
# - Answering questions about your requirements
# - Reviewing generated files (PRD, architecture, etc.)
# - Automatic execution with harness managing retries

Project Analysis

# High-level project analysis and documentation
aidp init

# Creates:
# - LLM_STYLE_GUIDE.md
# - PROJECT_ANALYSIS.md
# - CODE_QUALITY_PLAN.md

Progress Monitoring

# Watch progress in real-time
aidp checkpoint summary --watch

# Check job status
aidp jobs list
aidp checkpoint summary

Debug and Logging

# Enable debug output to see AI provider communication
AIDP_DEBUG=1 aidp

# Log to a file for debugging
AIDP_LOG_FILE=aidp.log aidp

# Combine both for full debugging
AIDP_DEBUG=1 AIDP_LOG_FILE=aidp.log aidp

Development

# Install dependencies
bundle install

# Install Tree-sitter parsers for development
./install_tree_sitter_parsers.sh

# Set up environment variables
export TREE_SITTER_PARSERS="$(pwd)/.aidp/parsers"

# Run tests
bundle exec rspec

# Run Tree-sitter analysis tests specifically
bundle exec rspec spec/aidp/analysis/
bundle exec rspec spec/integration/tree_sitter_analysis_workflow_spec.rb

# Run linter
bundle exec standardrb

# Auto-fix linting issues
bundle exec standardrb --fix

# Build gem
bundle exec rake build

Development Dependencies

The following system dependencies are required for development:

• Tree-sitter - System library for parsing (install via brew install tree-sitter or package manager)
• Ruby gems - All required gems are specified in aidp.gemspec and installed via bundle install

Contributing

See CONTRIBUTING.md for development setup and conventional commit guidelines.

Documentation

For detailed information:

• CLI User Guide - Complete guide to using AIDP commands
• Work Loops Guide - Iterative workflows with automatic validation
• Configuration Guide - Detailed configuration options and examples
• Troubleshooting Guide - Common issues and solutions

Manual Workflow (Alternative)

The gem packages markdown prompts that can also be used directly with Cursor or any LLM. See the templates/ directory for the individual prompt files that can be run manually.