Product Overview

Purpose #

Explain what aidokit is at the product level — the problem it solves, the shape of the solution, and the explicit non-goals.

v1.0 surface (2026-05-25): the user-facing surface is now organised around three tiers (Starter · Standard · Strict) and five stack packs (Node-TS · Node-JS · Python · React · Go). The comparison page is the most honest entry point for prospective users; the privacy policy and supply-chain page document what aidokit does and does not transmit / sign.

Big Picture #

Drawn from .docs/README.md, .docs/ROADMAP.md, and CLAUDE.md §1.

AI coding tools (Claude Code, Codex, Copilot CLI, …) 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 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 (npx aidokit init).

How It Works #

aidokit is a productisation of the AI Dev Orchestrator Spec v2.0. The CLI itself:

Makes zero LLM calls — every decision is deterministic.
Runs no daemon — every command is short-lived.
Reads project manifests, runs shell commands declared in adapter capabilities, and emits files atomically through a staging directory.
Hands off to the user's existing AI coding CLI for actual development work.

The output is a complete workflow tree composed from:

1 Adapter (claude-code | codex | copilot)
  +
N Stack Packs (node-ts, node-js, python, react, go)
  +
Shared catalogs (@aidokit/mcp-catalog, @aidokit/base-skills)
  +
Shared docs (@aidokit/shared-docs)

The user sees .claude/ (or .codex/, .copilot/) + CLAUDE.md/AGENTS.md/copilot-instructions.md + docs/ + agent-artifacts/ + .aido/adapter.md.

Example #

npx aidokit init against a fresh Node-TS repo produces an interactive flow:

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

? Adapter:                     Claude Code
? Conformance level:           Standard
? Detected stack:              Node.js + TypeScript — use this?  Yes
? Install Beads task graph:    Yes
? MCP servers to install:      Context7, Beads MCP

⠋ Emitting CLAUDE.md and .claude/ engine directory...
✔ Setup complete in 18s

The emitted project is then opened in claude (or codex, copilot), and the team runs /intake to begin work. aidokit itself never re-runs unless the user invokes another command (aidokit doctor, aidokit sync, aidokit mcp add …).

Diagram #

See diagrams/product-map.md.

What's in scope at v1.0 #

From .docs/ROADMAP.md §v1.0:

Three first-party adapters: claude-code (Strict), codex (Minimum), copilot (Minimum)
Five first-party stack packs: node-ts, node-js, python, react, go
Multi-adapter projects (multiple engine dirs sharing docs/ + agent-artifacts/ + Beads)
All three conformance levels (Minimum / Standard / Strict)
--brownfield, --dry-run, --json, --yes, --no-prompts
doctor, sync, validate, migrate, mcp …, skills …, new …, manifest, search
Signed npm packages (provenance attestations)
Eight-entry MCP catalog (context7, beads-mcp, playwright, github, chrome-devtools, postgres, filesystem, graphify)

What is NOT in scope #

From .docs/ROADMAP.md §Non-goals:

LLM API calls from aidokit itself
Telemetry, analytics, version-check pings
A daemon mode, long-running watcher, or background service
Replacing the user's AI coding CLI
Auto-progression between tasks
A full project-management suite
An IDE plugin
An enterprise SaaS product
Auto-install of prereqs (ADR-0008)

Common Mistakes #

Building "helpful" model-calling features inside aidokit. The zero-LLM-calls rule is absolute (see CLAUDE.md §8).
Documenting post-v1.0 surface (third-party SDK, marketplace) as if it ships today. Mark it as > [!TODO] or scope it explicitly to post-v1.0.
Conflating aidokit with the kit content. aidokit is the CLI. The kit content (skills, agents, hooks) is emitted by an adapter — specifically @aidokit/adapter-claude-code.

Checklist #

[ ] You can articulate why aidokit exists in one sentence.
[ ] You know the difference between aidokit and the AI coding CLI it scaffolds for.
[ ] You can name what is in v1.0 vs. post-v1.0.