aidokitwiki
User Docs Wiki

Introduction

Audience-Contributor Status-Shipped v0.5

The problem (in 3 lines) #

  1. AI coding CLIs are unsafe by default. They edit files they weren't asked to touch, forget decisions across sessions, and run autonomous loops with no stop conditions.
  2. Existing workflow kits lock you into one CLI. Hand-crafted .claude/ trees don't port to Codex or Copilot; teams maintain dozens of files by hand.
  3. There's no enforced discipline. Scope boundaries, role separation, watchdog stops, and per-role MCP scoping exist as patterns — not as installable artifacts.

What aidokit does #

aidokit is a one-command scaffolder that emits a complete, adapter-agnostic AI-assisted development workflow into any project. It ships the operating discipline around your AI coding CLI — not a replacement for it. Zero LLM calls. No daemon. No telemetry.

How It Works #

Read .docs/ARCHITECTURE.md §8 for the canonical step-by-step. In short:

  1. Parse args; probe host; detect stack.
  2. Resolve missing prereqs (print install commands; never auto-install — ADR-0008).
  3. Interactive selection (adapter, conformance, stack packs, MCPs, Beads).
  4. Build immutable ProjectContext.
  5. Compose file plan from adapter + stack packs + base skills + shared docs.
  6. Stage and atomically commit.
  7. Install MCP servers; run postInstall; write .aido/adapter.md.
%%{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;

  P1[1. parse + probe]:::cli --> P2[2. prereqs]:::cli
  P2 --> P3[3. interactive
selection]:::cli
  P3 --> P4[4. immutable
ProjectContext]:::artifact
  P4 --> P5[5. compose
file plan]:::artifact
  P5 --> P6[6. stage + commit]:::artifact
  P6 --> P7[7. postInstall +
.aido/adapter.md]:::ok

Each step is detailed in diagrams/scaffold-flow.md.

Current phase #

Field Value
Release target v1.0 GA (in flight)
Shipped v0.5 Beta (see CHANGELOG.md [0.5.0])
Adapters claude-code (Strict), codex (Minimum), copilot (Minimum, ADR-0016)
Stack packs node-ts, node-js, python, react, go
Remaining v1.0 multi-adapter polish, --dry-run everywhere, capability declarations, signed packages, aidokit search, docs site

What aidokit is NOT #

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

Example #

A user invokes npx aidokit init in a fresh Node-TS project. After interactive selection, the CLI writes (illustrative — exact tree per .docs/context/claude-workflow-kit-v4-base-part-3.md):

my-app/
├── CLAUDE.md
├── .claude/
│   ├── commands/ (intake, implement-task, orchestrator-next)
│   ├── agents/   (researcher, architect, planner, builder, tester-reviewer, maintainer, frontend-browser-tester)
│   ├── skills/   (18 base + node-ts contributed)
│   ├── output-styles/  (5 styles)
│   ├── schemas/  (8 artifact schemas)
│   └── scripts/  (19 hook scripts, mode 0o755)
├── docs/
├── agent-artifacts/
└── .aido/adapter.md

Common Mistakes #

Checklist #