Project Overview

Purpose #

A fast tour of what lives in the repo and which package owns what.

Big Picture #

Source of truth: .docs/ARCHITECTURE.md §3. The repo is a pnpm + Turborepo monorepo whose packages/ directory holds the 15 packages making up aidokit at v1.0.

How It Works #

Repository top level #

aidokit/
├── CLAUDE.md           ← agent rules for AI-assisted dev of aidokit itself
├── CHANGELOG.md        ← Keep-a-changelog format; pre-1.0 narrative, post-0.5 by changesets
├── CONTRIBUTING.md
├── LICENSE             ← Apache-2.0 (drafted, not legally reviewed — ADR-0003)
├── NOTICE              ← Apache 2.0 §4(d) attribution
├── SECURITY.md         ← vulnerability reporting + capability boundaries
├── package.json + pnpm-workspace.yaml + turbo.json + tsconfig.base.json
├── .changeset/         ← per-PR change descriptions
├── .docs/              ← design docs (hidden on disk; planned to flatten — CLAUDE.md §2)
│   ├── README.md, ROADMAP.md, ARCHITECTURE.md
│   ├── docs/specs/         ← adapter-contract, stack-pack-contract, cli-reference, mcp-catalog, conformance-levels, security-model
│   ├── docs/architecture/decisions/   ← 16 ADRs
│   └── context/            ← v4 kit reference (parts 1/2/3 + a-z)
├── packages/           ← the 15 published packages
├── agent-artifacts/    ← hand-built workflow artifacts for dogfooding aidokit on itself
├── docs/               ← hand-built docs/ skeleton dogfooded by aidokit
└── scripts/            ← repo automation

Package map #

Each package is a workspace under packages/. Names follow ADR-0004 §2: scoped @aidokit/* for libraries, unscoped aidokit for the user-facing CLI binary.

The full responsibilities table is in reference/package-index.md.

Where to look first #

Diagram #

%%{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"
  }
}}%%
graph TD
  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;

  cli["@aidokit/cli (Layer 3)"]:::cli
  cli --> adcc["@aidokit/adapter-claude-code"]:::adapter
  cli --> adcx["@aidokit/adapter-codex"]:::adapter
  cli --> adcp["@aidokit/adapter-copilot"]:::adapter
  cli --> sp1["@aidokit/stack-pack-node-ts"]:::pack
  cli --> sp2["@aidokit/stack-pack-node-js"]:::pack
  cli --> sp3["@aidokit/stack-pack-python"]:::pack
  cli --> sp4["@aidokit/stack-pack-react"]:::pack
  cli --> sp5["@aidokit/stack-pack-go"]:::pack
  cli --> sd["@aidokit/shared-docs"]:::core
  cli --> bs["@aidokit/base-skills"]:::core
  cli --> det["@aidokit/stack-detect"]:::core
  cli --> pre["@aidokit/prereq-check"]:::core
  cli --> mcp["@aidokit/mcp-catalog"]:::core

  adcc --> core["@aidokit/core"]:::core
  adcx --> core
  adcp --> core
  sp1 --> core
  sp2 --> core
  sp3 --> core
  sp4 --> core
  sp5 --> core
  sd --> core
  bs --> core
  det --> core
  pre --> core
  mcp --> core

Common Mistakes #

• Adding a runtime dep from @aidokit/core to any other @aidokit/* package. @aidokit/core MUST stay standalone — third-party adapter authors install only @aidokit/core (see CLAUDE.md §4).
• Cross-package refactors in one PR. Each PR touches one package — see contributing/code-standards.md.
• Creating speculative packages. v0.1 baseline + v0.5/v1.0 additions is the full set; no @aidokit/sdk-* packages exist yet (ROADMAP §Beyond v1.0).

Checklist #

• [ ] You can name the 15 packages and which layer each is in.
• [ ] You know the rule: adapters don't import stack packs, stack packs don't import adapters, only @aidokit/cli imports both.
• [ ] You've identified which package owns the work you're about to do.

Related Pages #

• reference/package-index.md — full responsibilities + runtime-dep table
• concepts/three-layer-architecture.md
• how-to-guides/how-to-navigate-the-monorepo.md