aidev

AI Development Team Orchestrator - An intelligent CLI tool that coordinates AI agents to complete software development tasks using the BMAD-METHOD.

Table of Contents

• Overview
• Installation
• Quick Start
• Configuration
• Commands
  • Main Command
  • analyze
  • agents
  • create-agent
  • config
• Smart Orchestration
• AI Agents
• Source of Truth Documents
• Examples
• Troubleshooting
• License

Overview

aidev is an AI-powered development orchestrator that intelligently coordinates multiple specialized AI agents to complete software development tasks. Instead of using a fixed workflow, aidev analyzes your task and dynamically selects which agents to use and in what order.

Key Features:

• Smart task analysis and planning
• Dynamic agent selection based on task type
• Automatic project context discovery
• Support for brownfield (existing) and greenfield (new) projects
• Integration with BMAD-METHOD agent framework
• Custom agent creation

Installation

Global Installation (Recommended)

npm install -g aidev

Local Development

git clone <repository>
cd aidev-npm
npm install
npm run build
npm link  # Makes 'aidev' available globally

Requirements

• Node.js >= 20.0.0
• Anthropic API key

Quick Start

# 1. Install aidev
npm install -g aidev

# 2. Configure your API key (prompted on first run, or set manually)
aidev config --api-key sk-ant-your-key-here

# 3. Navigate to your project
cd /path/to/your/project

# 4. Run a task
aidev "Add user authentication with JWT"

Configuration

Setting API Key

# Interactive configuration
aidev config

# Set API key directly
aidev config --api-key sk-ant-xxx

# Via environment variable
export ANTHROPIC_API_KEY=sk-ant-xxx

View Configuration

aidev config --show

Output:

Configuration:
  Path: /Users/you/.config/aidev-nodejs/config.json
  API Key: configured

Clear Configuration

aidev config --clear

Configuration File Location

• macOS: ~/Library/Preferences/aidev-nodejs/config.json
• Linux: ~/.config/aidev-nodejs/config.json
• Windows: %APPDATA%\aidev-nodejs\config.json

Commands

Main Command (Run Orchestration)

aidev [options] "<task description>"

Arguments: | Argument | Description | |----------|-------------| | prompt | The development task to execute |

Options: | Option | Description | Default | |--------|-------------|---------| | -m, --model <model> | Claude model to use | claude-sonnet-4-20250514 | | -v, --verbose | Show detailed output including agent responses | false | | -d, --dir <path> | Project directory to work in | Current directory | | -V, --version | Output version number | | | -h, --help | Display help | |

Examples:

# Basic usage
aidev "Add a REST API endpoint for user profiles"

# With verbose output
aidev "Fix the authentication bug" --verbose

# Specify project directory
aidev "Add caching layer" --dir ./my-project

# Use a different model
aidev "Refactor the database layer" --model claude-opus-4-20250514

analyze

Analyze a repository and display detected context including technology stack and source-of-truth documents.

aidev analyze [path]

Arguments: | Argument | Description | Default | |----------|-------------|---------| | path | Repository path to analyze | Current directory |

Example:

aidev analyze ./my-project

Output:

Analyzing repository: ./my-project

Technology Stack:
  Language: TypeScript
  Framework: Express
  Test Framework: Jest
  Package Manager: npm

Source of Truth Documents:
  Project: my-project
  ✓ my-project-brownfield-architecture.md
  ✓ my-project-integration-map.md
  ✓ my-project-system-analysis.md

agents

Display information about available AI agents loaded from BMAD-METHOD.

aidev agents

Output:

AI Development Team (BMAD Agents)
Loaded from: /path/to/BMAD-METHOD

📊 Mary - Business Analyst
   Role: Strategic Business Analyst + Requirements Expert

🏗️ Winston - System Architect
   Role: System Architect + Technical Design Leader

👩‍💻 Amelia - Senior Developer
   Role: Senior Software Engineer + Implementation Expert

🧪 Murat - Test Architect
   Role: Master Test Architect + Quality Assurance Expert

Other available agents: pm, sm, tech-writer, ux-designer

create-agent

Create a new BMAD-compliant agent using the agent-builder (Bond).

aidev create-agent [options]

Options: | Option | Description | Default | |--------|-------------|---------| | -q, --quick | Quick mode - guided prompts without AI conversation | false | | -o, --output <path> | Output directory for the agent file | Current directory | | -m, --model <model> | Claude model to use | claude-sonnet-4-20250514 | | -v, --verbose | Show detailed output | false |

Interactive Mode (Default):

aidev create-agent

Starts a conversation with Bond (the agent-building expert) who guides you through:

1. Brainstorming the agent's purpose
2. Defining metadata (name, title, icon)
3. Crafting the persona (role, identity, communication style)
4. Setting principles and guidelines
5. Adding optional menu commands

Quick Mode:

aidev create-agent --quick

Uses guided prompts for rapid agent creation without AI conversation.

Output: Creates a <agent-name>.agent.yaml file in the specified directory.

config

Configure aidev settings.

aidev config [options]

Options: | Option | Description | |--------|-------------| | --api-key <key> | Set Anthropic API key | | --show | Show current configuration | | --clear | Clear all configuration |

Examples:

# Interactive configuration
aidev config

# Set API key
aidev config --api-key sk-ant-xxx

# Show current config
aidev config --show

# Clear all settings
aidev config --clear

Smart Orchestration

aidev uses intelligent task analysis to determine which agents to call and in what order. Instead of a fixed workflow, it dynamically creates execution plans based on your task.

How It Works

1. Discovery - Analyzes your repository to detect:

   • Programming language and framework
   • Test framework
   • Package manager
   • Source-of-truth documents

2. Planning - AI analyzes your task to determine:

   • Task type (bug fix, new feature, refactor, etc.)
   • Required agents
   • Execution order and dependencies
   • Complexity estimate

3. Execution - Runs only the necessary agents in the optimal order

Task Types

| Task Type | Description | Typical Agents | |-----------|-------------|----------------| | new_feature | Building new functionality | Analyst → Architect → Dev → QA | | bug_fix | Fixing issues | Dev → QA | | refactor | Improving existing code | Architect → Dev | | testing | Creating tests | QA | | documentation | Writing docs | Dev / Tech Writer | | code_review | Reviewing code | Dev | | architecture | System design | Analyst → Architect | | analysis | Research/investigation | Analyst | | general | Other tasks | Context-dependent |

Step Priorities

| Priority | Symbol | Description | |----------|--------|-------------| | Required | ● | Must complete for task success | | Recommended | ◐ | Improves quality but not essential | | Optional | ○ | Nice to have |

Example Output

 AI Dev Team - Smart Orchestration
Task: Fix the login timeout bug

  BMAD-METHOD: /path/to/BMAD-METHOD
  Loaded 8 agents

✓ Discovery complete
  Language: TypeScript
  Framework: Express
  Found 2 source-of-truth document(s)

✓ Execution plan created

Task Type: bug_fix
Complexity: simple
Reasoning: Bug fix task - only developer needed to fix, QA for regression tests

Execution Plan:
  1. ● 👩‍💻 Amelia: Analyze and fix bug
  2. ◐ 🧪 Murat: Add regression tests

👩‍💻 Analyze and fix bug complete
🧪 Add regression tests complete

✓ Workflow complete!

Outputs generated:
  - Fix
  - Tests

Task type: bug_fix
Complexity: simple

AI Agents

aidev coordinates specialized AI agents, each with unique expertise:

Core Agents

| Agent | Name | Role | Best For | |-------|------|------|----------| | 📊 | Mary (Analyst) | Strategic Business Analyst + Requirements Expert | PRDs, requirements, analysis | | 🏗️ | Winston (Architect) | System Architect + Technical Design Leader | Architecture, API design, tech decisions | | 👩‍💻 | Amelia (Developer) | Senior Software Engineer | Implementation, bug fixes, refactoring | | 🧪 | Murat (Test Architect) | Master Test Architect | Test strategy, unit/integration tests |

Additional Agents

| Agent | Role | |-------|------| | PM | Product Manager - roadmap, prioritization | | SM | Scrum Master - process, workflow | | Tech Writer | Technical documentation | | UX Designer | User interface and experience |

BMAD-METHOD Integration

aidev comes bundled with bmad-method as a dependency - no separate installation required!

The loader automatically discovers agents from:

1. Bundled npm package: node_modules/bmad-method (default)
2. Sibling directory: ../BMAD-METHOD (for development)
3. Environment variable: $BMAD_PATH (custom location)

The bundled bmad-method includes:

• Core agents: analyst, architect, dev, qa, pm, po, sm, ux-expert
• Expansion packs: game development, creative writing, infrastructure agents

Source of Truth Documents

For best results, create these files in your repository root:

| File | Purpose | |------|---------| | <project>-brownfield-architecture.md | Current architecture documentation | | <project>-integration-map.md | External integrations and APIs | | <project>-system-analysis.md | System analysis and constraints |

Example: myapp-brownfield-architecture.md

# MyApp Architecture

## Overview
MyApp is a Node.js/Express REST API with PostgreSQL database.

## Technology Stack
- Runtime: Node.js 20
- Framework: Express 4.x
- Database: PostgreSQL 15
- ORM: Prisma
- Authentication: JWT

## Directory Structure
├── src/
│   ├── routes/
│   ├── controllers/
│   ├── services/
│   ├── models/
│   └── middleware/
├── tests/
└── prisma/

## Key Patterns
- Repository pattern for data access
- Service layer for business logic
- Controller layer for HTTP handling

aidev will automatically discover and use these files to provide better context to agents.

Examples

New Feature Development

aidev "Add a password reset feature with email verification"

Plan: Analyst (PRD) → Architect (design) → Developer (code) → QA (tests)

Bug Fix

aidev "Fix: Users can't login after password change"

Plan: Developer (fix) → QA (regression tests)

Refactoring

aidev "Refactor the authentication module to use dependency injection"

Plan: Architect (design) → Developer (implement)

Testing

aidev "Add comprehensive unit tests for the user service"

Plan: QA (tests)

Documentation

aidev "Document all REST API endpoints with examples"

Plan: Developer (documentation)

Architecture Design

aidev "Design a caching strategy for the product catalog"

Plan: Analyst (analysis) → Architect (design)

With Verbose Output

aidev "Add rate limiting to the API" --verbose

Shows detailed output from each agent.

Different Project Directory

aidev "Update the build configuration" --dir ~/projects/my-app

Using Different Model

aidev "Complex system redesign" --model claude-opus-4-20250514

Troubleshooting

"API key not configured"

# Set your API key
aidev config --api-key sk-ant-your-key

# Or via environment variable
export ANTHROPIC_API_KEY=sk-ant-your-key

"BMAD-METHOD not found"

bmad-method is bundled with aidev, so this shouldn't happen. If it does:

# Reinstall dependencies
cd /path/to/aidev-npm
npm install

# Or use a custom BMAD-METHOD location
export BMAD_PATH=/path/to/custom/BMAD-METHOD

"Agent not available"

Some agents require BMAD-METHOD. Check available agents:

aidev agents

Build Errors

# Rebuild the project
cd /path/to/aidev-npm
npm run build

Permission Denied (Global Install)

# Use sudo (not recommended) or fix npm permissions
sudo npm install -g aidev

# Better: Configure npm to use a different directory
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

Verbose Debugging

aidev "your task" --verbose

Shows detailed output including:

• Agent responses
• Planning reasoning
• Step-by-step execution

Environment Variables

| Variable | Description | |----------|-------------| | ANTHROPIC_API_KEY | Anthropic API key (alternative to config) | | BMAD_PATH | Custom path to BMAD-METHOD |

License

MIT