aidokit

AI Dev Orchestrator CLI — bootstrap a structured, adapter-agnostic, AI-assisted development workflow into any project with one command.

Status: v0.5 Beta shipped (2026-05-25). v1.0 GA in flight — see ROADMAP.md. Public CLI surface is stabilising; breaking changes follow Changesets discipline.

What is aidokit?

aidokit is a command-line tool that scaffolds a complete, controlled, AI-assisted development workflow into any software project — greenfield or brownfield — and lets you pick which AI coding CLI (Claude Code, Codex, future tools) drives it.

In one command, it gives your project:

• A scope-enforced workflow with hard stops between stages
• A persistent task graph and decision memory
• Per-role capability sandboxing (Researcher, Architect, Planner, Builder, Tester-Reviewer, Maintainer)
• Stack-aware skill packs that match your tech
• MCP servers configured per role, not blanket-loaded onto every agent
• Migration paths between major versions of the underlying spec

Built on the AI Dev Orchestrator Spec v2.0 — a tool-agnostic specification for structured AI-assisted development.

Why aidokit?

AI coding tools are powerful but unsafe by default:

• They edit files they were not asked to touch
• They forget what they decided across sessions
• They run on autonomous loops with no stop conditions
• They lose project context when chats compact
• They give every agent every tool, blowing up token budgets and capability surface

aidokit does not try to fix the underlying models. It ships the operating discipline around them: enforced scope boundaries, role separation, deterministic watchdog stops, structured task memory, and a strict source-of-truth chain — all packaged into a one-command install.

Existing solutions either lock you into one CLI (hand-crafted kits for Claude Code only), require manual setup of dozens of files, or skip enforcement entirely. aidokit makes the workflow portable, scaffolds it for you, and lets the ecosystem grow with community-contributed adapters and stack packs.

Top-5 pain points aidokit addresses

The 25-pain-point analysis of AI-first development workflows highlighted what actually goes wrong in practice. aidokit is shaped against the five with the highest combined severity-and-tractability:

All 25 pain points in the broader analysis are addressed by v1.x — see CHANGELOG.md [Unreleased] and docs/specs/cli-reference.md for the complete surface.

aidokit makes zero LLM calls itself — it scaffolds discipline around whichever AI coding CLI you already use.

Quick start

🧭 Not sure which path fits you? Try the interactive scenario picker → — answer a few questions (CLI, tier, stack) and get a copy-paste playbook for your situation. Static fallback: Scenarios →.

Prerequisites

• Node.js 20 or later
• Git
• An AI coding CLI — Claude Code (Strict), Codex CLI (Minimum), or GitHub Copilot CLI (Minimum). All three first-party adapters shipped in v0.5.
• Beads CLI — recommended for task graph and decision memory (optional; a flat-file fallback is supported)

Install and bootstrap

# In your project directory
npx aidokit init

That is it. Follow the interactive prompts to pick your adapter, conformance level, stack pack, and MCP servers.

Example: greenfield Node.js project

$ mkdir my-app && cd my-app
$ git init
$ npx aidokit init

🔍 Detecting environment...
   ✔ macOS · Node.js 20.11 · Git initialized · Greenfield project

? Adapter (no default — pick one):
    claude-code
  > codex
    copilot
? Conformance level:           Standard
? Detected stack:              Node.js + TypeScript — use this?  Yes
? Install Beads task graph:    Yes
? MCP servers to install:      Context7, Beads MCP

⠋ Emitting AGENTS.md and .codex/ engine directory...
⠹ Writing docs/ skeleton and agent-artifacts/...
⠼ Initializing Beads...
✔ Setup complete in 18s

📋 Next steps
   1. Review AGENTS.md and customize project rules
   2. Run:  codex
   3. Run:  /intake "describe your project"

After bootstrapping, your project has the full workflow installed:

my-app/
├── AGENTS.md                   ← agent rules (project-level; `CLAUDE.md` under the claude-code adapter)
├── .codex/                     ← engine directory (`.claude/` under the claude-code adapter, `.copilot/` under copilot)
│   ├── commands/               ← /intake, /implement-task, /orchestrator-next
│   ├── agents/                 ← role definitions (Researcher, Builder, etc.)
│   ├── skills/                 ← procedural skills auto-loaded by triggers
│   └── scripts/                ← watchdog hooks (scope, version, deletion guards)
├── docs/                       ← project documentation skeleton
├── agent-artifacts/            ← task briefs, change summaries, reports, blockers
└── .beads/                     ← task graph database

Features

• One-command setup — npx aidokit init scaffolds the entire workflow
• Adapter-agnostic — Claude Code, Codex CLI, and Copilot CLI all shipped in v0.5; third-party adapters via SDK (post-v1.0)
• Stack-aware — detects your stack and suggests matching skills and MCPs
• Per-role MCP scoping — Researcher gets documentation lookup, Builder does not; no blanket loading
• Brownfield support — ingest existing PRD, BRD, or codebase into the workflow
• Migration tools — upgrade between major versions without manual editing
• Health checks — aidokit doctor verifies your setup stays consistent
• Conformance levels — Minimum, Standard, Strict — pick what your team needs
• Zero LLM calls of its own — uses your existing CLI's authentication; no API keys required by aidokit

Supported adapters

See ROADMAP.md for the release timeline and conformance targets per release.

How it works

aidokit is a thin scaffolding layer over the AI Dev Orchestrator Spec v2.0. It:

1. Detects your stack, OS, and installed tools
2. Asks which adapter and conformance level you want
3. Emits the right files into your project — agent rules, slash commands, role definitions, skills, watchdog hooks, documentation skeleton
4. Wires per-role MCP servers based on your stack and selections
5. Initializes the task graph backend (Beads)
6. Hands off to your AI coding CLI for actual development work

aidokit itself makes zero LLM calls. Your existing CLI handles all model communication using whatever authentication you already have configured.

See ARCHITECTURE.md for the system design.

Commands at a glance

Full reference: docs/specs/cli-reference.md.

Documentation

• ROADMAP.md — release plan, what is in v0.1 / v0.5 / v1.0
• ARCHITECTURE.md — system overview, package map, key flows
• docs/specs/adapter-contract.md — interface for adapter authors
• docs/specs/cli-reference.md — every command, flag, exit code
• CONTRIBUTING.md — local setup, testing, PR workflow
• CHANGELOG.md — what changed per release

Status

v0.5 Beta shipped (2026-05-25). v1.0 GA in flight — remaining scope: multi-adapter polish, --dry-run, capability declarations, aidokit search, npm provenance / Sigstore signing, docs site. See ROADMAP.md §v1.0.

Follow the repository for the v1.0 GA announcement.

Contributing

Contributions are welcome. Start with CONTRIBUTING.md for local setup and the PR workflow, then check open issues tagged good first issue.

For larger work — new adapters, new stack packs, or spec changes — please open a discussion before submitting a PR.

License

Apache 2.0. See LICENSE.

Acknowledgements

aidokit consolidates ideas from the broader AI-assisted development community:

• AI Dev Orchestrator Spec v2.0 — the underlying tool-agnostic specification
• Beads — task graph and agent memory layer
• Claude Code — first-party adapter target
• Patterns drawn from GitHub SpecKit, OpenSpec, BMAD, and Superpowers
• Earlier internal iterations: claude-workflow-kit v2.1, v3, and v4

If you maintain or contributed to any of the above and would like to be more specifically credited, please open an issue.