Concepts

Six ideas that explain how aidokit works. Read these once and the rest of the docs make sense.

1. aidokit is a scaffolder, not a runtime

aidokit writes files into your project and exits. It does not run alongside your AI coding CLI. It does not call any language model. It is closer to cookiecutter or npm init than to "an AI service in the cloud".

Zero LLM calls. Every decision is deterministic; every output is reproducible.
No daemon. Every command is short-lived.
No telemetry. Zero network calls from aidokit itself (excluding npm install).

Once aidokit init finishes, your AI coding CLI (Claude Code, Codex CLI, Copilot CLI) takes over and reads the files aidokit emitted.

2. Adapter + Stack Pack composition

Every project has two orthogonal dimensions:

Which AI coding CLI? — that's the adapter.
Which tech stack? — that's the stack pack.

A Django project on Claude Code is "claude-code adapter + python stack pack". The same Django project could later add the Codex adapter without touching the Python pack. Adapters and stack packs never know about each other — the CLI composes their outputs.

flowchart LR subgraph adapters ["Adapter (which CLI)"] a1[claude-code] a2[codex] a3[copilot] end subgraph packs ["Stack Pack (which tech)"] p1[node-ts] p2[node-js] p3[python] p4[react] p5[go] end cli{{"@aidokit/cli
composes"}} out[".claude/ or .codex/ or .copilot/
+ matching skills, validators,
and MCP suggestions"] adapters --> cli packs --> cli cli --> out style cli fill:#eff6ff,stroke:#2563eb style out fill:#f0fdf4,stroke:#15803d

Figure 1. Orthogonal composition. 3 adapters × 5 stack packs = 15 supported combinations at v1.0, with no n×m code path.

Why it matters Stack packs are portable across adapters by construction. A pack written today for Claude Code works under tomorrow's third-party adapter without modification.

3. Seven roles, three capability profiles

The emitted workflow has seven specialized roles, each running under one of three capability profiles:

Role	Profile	What it does
Researcher	read-only	Investigates code, libraries, prior decisions.
Architect	read-only	Module boundaries, layering, validation rules, error envelopes.
Planner	read-only	Decomposes a change into Beads tasks with dependencies.
Builder	scope-limited-write	Implements one approved task. Edits only in-scope files.
Tester-Reviewer	read-only	Two-stage review: spec compliance, then code quality.
Maintainer	docs-only-write	Cleanup, docs, changelog, version recommendations.
Frontend-Browser-Tester	scope-limited-write	Browser-driven UI testing (Standard+).

Each adapter maps these profiles to its CLI's mechanism. For Claude Code: permissionMode + PreToolUse hooks. For Codex: sandbox + approval policy. For Copilot: prose enforcement, with the gap honestly disclosed in the manifest.

flowchart TB subgraph plan ["/intake (plan mode)"] direction LR R[Researcher
read-only] A[Architect
read-only] P[Planner
read-only] R --> A --> P end subgraph build ["/implement-task (one task)"] direction LR B[Builder
scope-limited write] T[Tester-Reviewer
read-only] M[Maintainer
docs-only write] F[Frontend-Browser-Tester
scope-limited write] B --> T B -.optional UI.-> F F -.-> T T --> M end plan ==approved brief==> build

Figure 2. The role graph. Planning roles never touch source; the Builder edits in-scope files only; the Maintainer can only touch docs/, CHANGELOG.md, and the changeset directory.

4. Deterministic watchdog stops

The emitted .claude/scripts/ (or equivalent) contains hook scripts that stop the agent on specific conditions:

Condition	Default threshold
Same test fails repeatedly	3 consecutive failures
Same shell command fails repeatedly	5 consecutive failures
Same file edited too many times in one task	5 edits
Repair attempts exceed cap	2 attempts
Stage timeout exceeded	Configurable
Out-of-scope file write attempted	Always blocked
Version bump without approval	Always blocked
Tracked-file deletion without approval	Always blocked

Hooks are deterministic — the model cannot bypass them. When a stop fires, a blocker report is written to agent-artifacts/blockers/blocker-<id>.md.

Note Codex and Copilot do not currently expose a hook mechanism equivalent to Claude Code's. Their adapters declare this in manifest.gaps; enforcement falls back to prose for those CLIs.

5. Conformance: declared and verified

Three conformance levels:

Minimum — All MUST requirements from the contract. Suitable for CLIs with basic prompt-driven workflows.
Standard — Minimum + all SHOULD requirements. Subagents, repair caps, monitoring stream.
Strict — Standard + all MAY requirements. Workspace isolation, output styles, seventh role.

Every adapter declares its level in the manifest. A test harness in @aidokit/core verifies the claim against the implementation. Declared greater than verified is a CI failure. Adapters that claim Strict must actually emit the seventh role and the five output styles — the harness checks the emissions, not the marketing.

The user's project also declares a target level in .aido/adapter.md. aidokit doctor re-verifies a subset on your machine and reports drift.

6. Per-role MCP scoping

MCP servers (Model Context Protocol — tool servers that extend agent capabilities) are scoped per role, not blanket-loaded. The MCP catalog declares which roles each MCP suits:

Context7 (docs lookup) → Researcher, Architect.
Playwright (browser automation) → Tester-Reviewer, Frontend-Browser-Tester.
Beads MCP (task graph) → Planner, Maintainer.
GitHub MCP (repo + issue access) → Researcher, Planner.
Filesystem, graphify → security-sensitive; never auto-suggested.

A Builder doesn't get docs lookup. A Researcher doesn't get a browser. This keeps context budgets low and capability surface tight.

What's NOT in scope

LLM API calls from aidokit itself.
Telemetry, analytics, version-check pings.
A daemon or background watcher.
Replacing your AI coding CLI.
Auto-progressing between tasks.
A full project-management suite.
An IDE plugin (speculative, post-v1.0).
An enterprise SaaS product.
Auto-installing prerequisites.