viper-dev-kit 1.1.0
AI Dev Kit - Universal AI development environment
Requires Python: >=3.10

# AI Dev Kit

**Architecture-first development workflow plugin for Claude Code.**

`ai-dev-kit` is a Claude Code plugin that provides a complete development workflow: architecture exploration, phased planning, swim-lane execution, and documentation management. It supports multi-agent orchestration across Claude, Cursor, Gemini, OpenAI, and more.

## Features

- **Planning System**: `/ai-dev-kit:plan`, `/ai-dev-kit:plan-phase`, `/ai-dev-kit:plan-roadmap`, `/ai-dev-kit:explore-architecture`
- **Execution System**: `/ai-dev-kit:execute-lane`, `/ai-dev-kit:execute-phase` with worktree isolation
- **Documentation System**: TOON format, hierarchical indexes, `/ai-dev-kit:docs-find`, `/ai-dev-kit:docs-update`
- **Multi-Agent Orchestration**: `/ai-dev-kit:delegate`, `/ai-dev-kit:route` across 6 providers
- **Specialized Agents**: 15+ agents for planning, execution, and documentation
- **Skills Library**: C4 modeling, codebase analysis, library detection, standards extraction

## Prerequisites

- **Claude Code** v1.0.0 or later
- **Python 3.10+** (for scripts)
- **UV** (Python package manager) - `curl -LsSf https://astral.sh/uv/install.sh | sh`
- **Node.js 18+** (for CLI tools and npm packages)
- **jq** (required for orchestration scripts) - `apt install jq` or `brew install jq`
- **Chrome** (optional, for browser automation)

## Installation

### From Marketplace (Recommended)

```bash
# Add the marketplace (one-time)
claude plugin marketplace add ViperJuice/ai-dev-kit

# Install the plugin
claude plugin install ai-dev-kit@ai-dev-kit

# Or install with project scope
claude plugin install ai-dev-kit@ai-dev-kit --scope project

# OPTIONAL: Install helper CLI for asset sync
# Note: The PyPI package name is 'viper-dev-kit' but the command is 'ai-dev-kit'
# This CLI is optional and only needed for syncing plugin assets locally
uv tool install viper-dev-kit

# Sync plugin assets locally (optional; /ai-dev-kit:setup also does this)
ai-dev-kit sync --target .claude/ai-dev-kit
```

### From Source (Development)

```bash
# Clone the repository
git clone https://github.com/ViperJuice/ai-dev-kit
cd ai-dev-kit

# Install globally
./dev-tools/scripts/install-plugin.sh

# Or for development (symlink mode)
./dev-tools/scripts/install-plugin.sh --dev

# Install the helper CLI from this repo (optional)
uv tool install --editable .
```

Restart Claude Code after installing (plugins do not auto-reload).

## Quick Start

### Brownfield (Existing Project)

```bash
# 1. Assess the current project
/ai-dev-kit:assess

# 2. Configure the project
/ai-dev-kit:setup

# 3. Validate the setup
/ai-dev-kit:validate
```

### Greenfield (New Project)

```bash
# 1. Initialize a new project
/ai-dev-kit:init

# 2. Explore and plan
/ai-dev-kit:explore-architecture
/ai-dev-kit:plan-roadmap
```

## Commands

### Planning

| Command | Description |
|---------|-------------|
| `/ai-dev-kit:plan` | Architecture-first implementation planning |
| `/ai-dev-kit:plan-phase` | Plan a specific development phase |
| `/ai-dev-kit:plan-roadmap` | Create phased implementation roadmap |
| `/ai-dev-kit:explore-architecture` | Analyze codebase, build C4 diagrams |
| `/ai-dev-kit:visualize-roadmap` | Visualize roadmap with Mermaid/ASCII diagrams |

### Execution

| Command | Description |
|---------|-------------|
| `/ai-dev-kit:execute-lane` | Execute a swim lane in worktree |
| `/ai-dev-kit:execute-phase` | Execute all lanes in a phase |
| `/ai-dev-kit:parallel` | Set up parallel development |

### Documentation

| Command | Description |
|---------|-------------|
| `/ai-dev-kit:docs-find` | Search documentation indexes |
| `/ai-dev-kit:docs-update` | Refresh documentation |
| `/ai-dev-kit:docs-add` | Add new documentation source |
| `/ai-dev-kit:docs-audit` | Audit docs vs project dependencies |
| `/ai-dev-kit:docs-prune` | Remove irrelevant documentation |
| `/ai-dev-kit:docs-add-stack` | Add docs for detected stack |
| `/ai-dev-kit:docs-check` | Check for documentation updates (dry-run) |
| `/ai-dev-kit:toon-validate` | Validate TOON files with official CLI |

### Research

| Command | Description |
|---------|-------------|
| `/ai-dev-kit:research` | Conduct parallel research across topics |

### Orchestration

| Command | Description |
|---------|-------------|
| `/ai-dev-kit:delegate` | Delegate task to specific provider |
| `/ai-dev-kit:route` | Intelligent task routing |
| `/ai-dev-kit:cost-status` | Show usage across providers |
| `/ai-dev-kit:provider-check` | Check provider CLI availability |
| `/ai-dev-kit:mcp-setup` | Configure MCP server integration |

### Kit Management

| Command | Description |
|---------|-------------|
| `/ai-dev-kit:assess` | Analyze project for conflicts |
| `/ai-dev-kit:setup` | Configure brownfield project |
| `/ai-dev-kit:init` | Scaffold greenfield project |
| `/ai-dev-kit:validate` | Verify plugin installation |
| `/ai-dev-kit:kit-pull` | Pull template updates |
| `/ai-dev-kit:kit-push` | Push template improvements |
| `/ai-dev-kit:kit-diff` | Show template divergence |
| `/ai-dev-kit:kit-update` | Update plugin from source |
| `/ai-dev-kit:kit-doctor` | Validate kit installation |

### Onboarding

| Command | Description |
|---------|-------------|
| `/ai-dev-kit:quickstart-codebase` | Unified brownfield onboarding |
| `/ai-dev-kit:prime` | Prime context with essential docs |

### Utility

| Command | Description |
|---------|-------------|
| `/ai-dev-kit:list-skills` | List available skills |
| `/ai-dev-kit:list-tools` | List available tools |

## Documentation

After installation, documentation is available at `ai-docs/`:

- `ai-docs/libraries/` - Library documentation (20+ sources)
- `ai-docs/libraries/_index.toon` - Master index
- `ai-docs/libraries/_registry.json` - Source configuration

Use `/ai-dev-kit:docs-find [query]` to search, or navigate indexes directly.

## Multi-Agent Environment

The plugin supports delegating tasks to the most appropriate AI provider:

| Platform | Role | Usage |
|----------|------|-------|
| **Claude Code** | Control plane, orchestrator | Primary interface |
| **Cursor** | Quick IDE edits | `/ai-dev-kit:delegate cursor "task"` |
| **Gemini** | Large context, web search | `/ai-dev-kit:delegate gemini "task"` |
| **OpenAI/Codex** | Sandboxed execution | `/ai-dev-kit:delegate codex "task"` |
| **Ollama** | Local/private tasks | `/ai-dev-kit:delegate ollama "task"` |

## Project Structure After Setup

```
my-project/
├── .claude/
│   ├── settings.json         # Claude Code settings
│   └── run-logs/             # Execution logs
├── ai-docs/                  # AI-consumable documentation
│   └── libraries/            # Library docs
├── specs/                    # Project specifications
├── architecture/             # C4 diagrams
├── AGENTS.md                 # Universal agent instructions
├── CLAUDE.md -> AGENTS.md    # Claude Code symlink
└── GEMINI.md -> AGENTS.md    # Gemini CLI symlink
```

## Contributing

See [docs/MAINTAINER.md](docs/MAINTAINER.md) for development guidelines.

This repository uses its own ai-dev-kit plugin for development. The plugin is at `plugins/ai-dev-kit/` and commands are available via the `/ai-dev-kit:*` namespace.

## License

MIT License - see LICENSE file for details.