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

$3

``bash
npm install -g aidev
`

$3

`bash
git clone
cd aidev-npm
npm install
npm run build
npm link # Makes 'aidev' available globally
`

$3

- Node.js >= 20.0.0
- Anthropic API key

---

Quick Start

`bash


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

$3

`bash


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
`

$3

`bash
aidev config --show
`

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

$3

`bash
aidev config --clear
`

$3

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

---

Commands

$3

`bash
aidev [options] ""
`

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

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

Examples:
`bash


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
`

---

$3

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

`bash
aidev analyze [path]
`

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

Example:
`bash
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
`

---

$3

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

`bash
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
`

---

$3

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

`bash
aidev create-agent [options]
`

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

Interactive Mode (Default):
`bash
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:
`bash
aidev create-agent --quick
`

Uses guided prompts for rapid agent creation without AI conversation.

Output:
Creates a .agent.yaml file in the specified directory.

---

$3

Configure aidev settings.

`bash
aidev config [options]
`

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

Examples:
`bash


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.

$3

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

$3

| 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 |

$3

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

$3

`
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:

$3

| 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 |

$3

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

$3

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 |
|------|---------|
| -brownfield-architecture.md | Current architecture documentation |
| -integration-map.md | External integrations and APIs |
| -system-analysis.md | System analysis and constraints |

$3

`markdown


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

$3

`bash
aidev "Add a password reset feature with email verification"
`

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

$3

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

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

$3

`bash
aidev "Refactor the authentication module to use dependency injection"
`

Plan: Architect (design) → Developer (implement)

$3

`bash
aidev "Add comprehensive unit tests for the user service"
`

Plan: QA (tests)

$3

`bash
aidev "Document all REST API endpoints with examples"
`

Plan: Developer (documentation)

$3

`bash
aidev "Design a caching strategy for the product catalog"
`

Plan: Analyst (analysis) → Architect (design)

$3

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

Shows detailed output from each agent.

$3

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

$3

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

---

Troubleshooting

$3

`bash


Set your API key

aidev config --api-key sk-ant-your-key

Or via environment variable

export ANTHROPIC_API_KEY=sk-ant-your-key
`

$3

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

`bash


Reinstall dependencies

cd /path/to/aidev-npm
npm install

Or use a custom BMAD-METHOD location

export BMAD_PATH=/path/to/custom/BMAD-METHOD
`

$3

Some agents require BMAD-METHOD. Check available agents:

`bash
aidev agents
`

$3

`bash


Rebuild the project


cd /path/to/aidev-npm
npm run build
`

$3

`bash


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
`

$3

`bash
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