aidokit wiki

You probably want one of two things.

Use aidokit to scaffold a project → .docs/README.md

Contribute to aidokit itself → keep reading.

aidokit is a command-line tool that scaffolds a structured, adapter-agnostic, AI-assisted development workflow into any software project in one command. The CLI makes zero LLM calls, runs no daemon, and emits a complete .claude/ (and/or .codex/, .copilot/) workflow tree composed from one Adapter + N Stack Packs + shared catalogs + shared docs.

Source of truth lives under .docs/. This wiki is the contributor onboarding layer; it cites the design docs rather than restating them.

Tip

Not sure where to start? Pick your scenario → — answer a few questions, get a copy-paste playbook. (The HTML mirror version is fully interactive.)

Tip

New here? Start with Introduction → Onboarding guide → Scaffold your first project. Budget ~3 days to be productive, ~1 week to land a small change end-to-end.

Picking how structured a project should be? The user-facing tier vocabulary — Starter · Standard · Strict — is the v1.0 preferred way to describe the workflow intensity. Internally the same axis is called ConformanceLevel (minimum / standard / strict) — see concepts/conformance-levels.md for the technical view.

Why aidokit exists #

AI coding tools are powerful but unsafe by default — they edit files they were not asked to touch, forget decisions across sessions, run on autonomous loops with no stop conditions, and give every agent every tool. Teams building structured workflows around them either lock into one CLI (hand-crafted Claude Code kits), maintain dozens of files by hand, or skip enforcement entirely.

aidokit ships the operating discipline around AI coding CLIs: enforced scope boundaries, role separation, deterministic watchdog stops, structured task memory, and a strict source-of-truth chain — packaged into a one-command install that is portable across Claude Code, Codex CLI, and GitHub Copilot CLI.

See .docs/README.md for the full pitch.

Who this wiki is for #

New contributors (engineers, QA, docs writers, maintainers) onboarding to aidokit itself.
Adapter authors building a @scope/aidokit-adapter-* package post-v1.0.
Stack-pack authors building a @scope/aidokit-stack-pack-* package.
Maintainers running releases, reviewing PRs, or evolving specs and ADRs.

If you want to use aidokit to scaffold a project, read .docs/README.md — this wiki documents the project that builds aidokit, not the CLI's end-user surface.

What you can do with aidokit (v1.0 scope) #

Drawn from .docs/ROADMAP.md §v1.0.

Scaffold a project with three first-party adapters: claude-code (Strict), codex (Minimum), copilot (Minimum). See ADR-0016.
Use five first-party stack packs: node-ts, node-js, python, react, go.
Run aidokit init greenfield or with --brownfield ingestion.
Run aidokit doctor, aidokit sync, aidokit validate, aidokit migrate, aidokit mcp …, aidokit skills …, aidokit new …, aidokit manifest.
Coexist multiple adapters in one project (.claude/ + .codex/ + .copilot/ sharing docs/, agent-artifacts/, Beads).
Verify adapter and stack-pack conformance at Minimum / Standard / Strict via the harness exported from @aidokit/core.
Install MCP servers from the catalog (Context7, Beads MCP, Playwright, GitHub MCP, Chrome DevTools, Postgres MCP, Filesystem MCP, graphify — see reference/mcp-catalog-reference.md).
Use --dry-run on init and sync; verify signed packages via npm provenance.
Run aidokit search adapter|stack-pack for npm-native discovery.

What is out of scope at v1.0 and stays out: third-party SDK as standalone packages, marketplace site, additional first-party adapters/packs, IDE plugins, any LLM-assisted feature, auto-install of prereqs.

At a glance #

%%{init: {
  "theme": "base",
  "themeVariables": {
    "fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif",
    "fontSize": "14px",
    "primaryColor": "#eff6ff",
    "primaryTextColor": "#0f172a",
    "primaryBorderColor": "#2563eb",
    "lineColor": "#475569",
    "secondaryColor": "#f1f5f9",
    "tertiaryColor": "#ffffff",
    "clusterBkg": "#f8fafc",
    "clusterBorder": "#cbd5e1"
  }
}}%%
flowchart TB
  classDef actor    fill:#ede9fe,stroke:#6d28d9,color:#1e1b4b,stroke-width:1.2px;
  classDef cli      fill:#dbeafe,stroke:#1d4ed8,color:#0c1f4a,stroke-width:1.4px;
  classDef adapter  fill:#cffafe,stroke:#0e7490,color:#083344;
  classDef pack     fill:#dcfce7,stroke:#15803d,color:#052e16;
  classDef core     fill:#fef9c3,stroke:#a16207,color:#422006;
  classDef artifact fill:#f1f5f9,stroke:#475569,color:#0f172a;
  classDef stop     fill:#fee2e2,stroke:#b91c1c,color:#7f1d1d,stroke-dasharray:4 3;
  classDef ok       fill:#ecfdf5,stroke:#047857,color:#064e3b;
  classDef external fill:#fff7ed,stroke:#c2410c,color:#431407;

  user(["Developer / QA / Maintainer"]):::actor
  cli["@aidokit/cli (aidokit binary)"]:::cli

  subgraph L2 [Layer 2 — Extensions]
    adapters["@aidokit/adapter-*
claude-code, codex, copilot"]:::adapter
    packs["@aidokit/stack-pack-*
node-ts, node-js, python, react, go"]:::pack
  end

  subgraph L1 [Layer 1 — Core + Utilities]
    core["@aidokit/core"]:::core
    sd["@aidokit/shared-docs"]:::core
    stackdet["@aidokit/stack-detect"]:::core
    prereq["@aidokit/prereq-check"]:::core
    mcp["@aidokit/mcp-catalog"]:::core
    base["@aidokit/base-skills"]:::core
  end

  emitted[".claude/ + .codex/ + .copilot/
+ docs/ + agent-artifacts/
(emitted into the user's project)"]:::artifact
  aicli["User's AI coding CLI
(Claude Code / Codex / Copilot)"]:::external

  user --> cli
  cli --> adapters
  cli --> packs
  adapters --> core
  packs --> core
  sd --> core
  stackdet --> core
  prereq --> core
  mcp --> core
  base --> core
  cli --> emitted
  emitted --> aicli

The full architecture is in concepts/three-layer-architecture.md. Detailed diagrams live in diagrams/.

How the emitted workflow runs #

The CLI scaffolds it; your AI coding CLI runs it. The seven roles, three verbs, and hard-stop gates are spec-defined.

%%{init: {
  "theme": "base",
  "themeVariables": {
    "fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif",
    "fontSize": "14px",
    "primaryColor": "#eff6ff",
    "primaryTextColor": "#0f172a",
    "primaryBorderColor": "#2563eb",
    "lineColor": "#475569",
    "secondaryColor": "#f1f5f9",
    "tertiaryColor": "#ffffff",
    "clusterBkg": "#f8fafc",
    "clusterBorder": "#cbd5e1"
  }
}}%%
flowchart LR
  classDef actor    fill:#ede9fe,stroke:#6d28d9,color:#1e1b4b,stroke-width:1.2px;
  classDef cli      fill:#dbeafe,stroke:#1d4ed8,color:#0c1f4a,stroke-width:1.4px;
  classDef adapter  fill:#cffafe,stroke:#0e7490,color:#083344;
  classDef pack     fill:#dcfce7,stroke:#15803d,color:#052e16;
  classDef core     fill:#fef9c3,stroke:#a16207,color:#422006;
  classDef artifact fill:#f1f5f9,stroke:#475569,color:#0f172a;
  classDef stop     fill:#fee2e2,stroke:#b91c1c,color:#7f1d1d,stroke-dasharray:4 3;
  classDef ok       fill:#ecfdf5,stroke:#047857,color:#064e3b;
  classDef external fill:#fff7ed,stroke:#c2410c,color:#431407;

  intake(["/intake"]):::actor
  R[Researcher]:::actor
  A[Architect]:::actor
  P[Planner]:::actor
  S1{{"stops before
any code"}}:::stop

  impl(["/implement-task"]):::actor
  B[Builder]:::actor
  T[Tester-Reviewer]:::actor
  M[Maintainer]:::actor
  S2{{"stops after
one task"}}:::stop

  brief["task brief"]:::artifact
  diff["change summary
+ test report"]:::artifact

  intake --> R --> A --> P --> brief --> S1
  S1 -. user approves .-> impl
  impl --> B --> T --> M --> diff --> S2
  S2 -. /orchestrator-next .-> impl

For deeper traces see diagrams/scaffold-flow.md, diagrams/data-flow.md, and diagrams/dogfood-loop.md.

Contributor onboarding journey #

A four-step ramp for new contributors. Each step expands what the previous one set up.

%%{init: {
  "theme": "base",
  "themeVariables": {
    "fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif",
    "fontSize": "14px",
    "primaryColor": "#eff6ff",
    "primaryTextColor": "#0f172a",
    "primaryBorderColor": "#2563eb",
    "lineColor": "#475569",
    "secondaryColor": "#f1f5f9",
    "tertiaryColor": "#ffffff",
    "clusterBkg": "#f8fafc",
    "clusterBorder": "#cbd5e1"
  }
}}%%
flowchart LR
  classDef actor    fill:#ede9fe,stroke:#6d28d9,color:#1e1b4b,stroke-width:1.2px;
  classDef cli      fill:#dbeafe,stroke:#1d4ed8,color:#0c1f4a,stroke-width:1.4px;
  classDef adapter  fill:#cffafe,stroke:#0e7490,color:#083344;
  classDef pack     fill:#dcfce7,stroke:#15803d,color:#052e16;
  classDef core     fill:#fef9c3,stroke:#a16207,color:#422006;
  classDef artifact fill:#f1f5f9,stroke:#475569,color:#0f172a;
  classDef stop     fill:#fee2e2,stroke:#b91c1c,color:#7f1d1d,stroke-dasharray:4 3;
  classDef ok       fill:#ecfdf5,stroke:#047857,color:#064e3b;
  classDef external fill:#fff7ed,stroke:#c2410c,color:#431407;

  S1["Day 0 — Read
Introduction, ROADMAP, CLAUDE.md"]:::actor
  S2["Day 1 — Run
pnpm install, build, scaffold a demo"]:::actor
  S3["Day 3 — Understand
three-layer arch, dogfood gate, contracts"]:::actor
  S4["Week 1 — Ship
land a small change with changeset"]:::ok
  S1 --> S2 --> S3 --> S4

The detailed checklist is in getting-started/onboarding-guide.md.

Documentation map #

Section	Purpose
Getting started	Orientation, install, project overview, glossary
Tutorials	End-to-end walkthroughs for common contributor tasks
How-to guides	Targeted recipes for specific operational tasks
Concepts	Explanations of the load-bearing ideas — architecture, conformance, dogfood gate
Reference	Tables: CLI surface, contracts, package index, ADRs, error codes
Diagrams	Mermaid renderings of the system, flows, and release pipeline
Contributing	Contribution conventions, doc standards, review and release checklists

Onboarding path #

A realistic ramp for a new contributor:

Time	Goal	Anchor
30 min	Read getting-started/introduction.md, skim .docs/README.md and CLAUDE.md	What `aidokit` is and is not
1 day	`pnpm install && pnpm build`; run the Scaffold your first project tutorial; trace one adapter package	Make the CLI work locally
3 days	Read concepts/three-layer-architecture.md, concepts/adapters-and-stack-packs.md, concepts/dogfood-gate.md; pick an open task	Understand the load-bearing rules
1 week	Propose an ADR or land a small change end-to-end via tutorials/prepare-a-change-for-review.md	Ship a change with conformance + dogfood + changeset

Need help? #

Project rules and source-of-truth ordering: CLAUDE.md
Design docs: .docs/ (README.md, ROADMAP.md, ARCHITECTURE.md, docs/specs/, docs/architecture/decisions/)
ADR index: reference/adr-index.md
Release history: CHANGELOG.md
Security: SECURITY.md
GitHub issues: [!TODO] Confirm with maintainer — repo URL not yet finalised in published docs.

A few load-bearing rules #

These are repeated across the wiki because they are non-negotiable. See CLAUDE.md §§4, 8 for the full set.

aidokit makes zero LLM calls. No telemetry. No phone-home. No auto-install of prereqs.
Adapters and stack packs are siblings — they never import each other; only @aidokit/cli consumes both.
No template engines (no Handlebars/EJS/Nunjucks/Mustache). Templates are real files with {{varName}} interpolation; complex emission is programmatic.
No YAML-as-code, no runtime plugin discovery. Contracts are TypeScript interfaces; catalogs are TypeScript const arrays.
The dogfood gate is permanent: from Phase 8, the @aidokit/adapter-claude-code adapter must emit a .claude/ tree byte-identical to this repo's hand-built .claude/. See concepts/dogfood-gate.md.