Quick Start

Purpose #

Get a fresh checkout of aidokit building and tested on your machine in under 30 minutes.

Big Picture #

The repo is a pnpm + Turborepo monorepo of 15 TypeScript packages targeting Node 20+ and ESM. Conventions are in CLAUDE.md §7 and codified in ADR-0001 and ADR-0002.

How It Works #

Prerequisites #

Tool	Version	Notes
Node.js	≥ 20.0.0	LTS; pinned via `.node-version` and `engines`
pnpm	9.x	Use Corepack: `corepack enable`
Git	any recent
Claude Code	≥ 2.1.32	Required to dogfood the emitted `.claude/`
Beads CLI	optional	Required at Standard from v0.5

aidokit itself never auto-installs any of these (see ADR-0008). Install them with your usual tools first.

Steps #

git clone <repo-url> aidokit && cd aidokit
corepack enable
pnpm install
pnpm build
pnpm test

Expected: install < 60 s on a typical dev machine; cold build < 90 s; warm build (Turborepo cache hit) < 30 s. See ADR-0002 §Validation.

Run the CLI against a scratch project #

Note: npx aidokit init becomes the canonical entry point at v1.0 (published to npm with provenance). Pre-v1.0, run the CLI from your local build as shown below.

mkdir /tmp/aidokit-scratch && cd /tmp/aidokit-scratch
git init
node /path/to/aidokit/packages/cli/dist/bin/aidokit.js init \
  --adapter claude-code --tier standard --stack node-ts --yes

The --tier flag is the v1.0 preferred way to choose workflow intensity — starter (60-second setup, no role vocabulary), standard (full six-role workflow, the default), or strict (audit-ready, capability declarations on). See the tier landing pages for what each emits. --conformance keeps working as a back-compat alias (--tier wins when both are set).

--yes accepts defaults but does not bypass securitySensitive prompts or prereq installs (see .docs/docs/specs/security-model.md §7.7).

Inspect the emitted tree under /tmp/aidokit-scratch/ — .claude/, docs/, agent-artifacts/, .aido/adapter.md.

Example: running just one package's tests #

pnpm --filter @aidokit/adapter-claude-code test
pnpm --filter @aidokit/core test

Turborepo orders the dependency graph automatically.

Diagram #

See diagrams/scaffold-flow.md for the full aidokit init pipeline.

Common Mistakes #

Using npm or yarn. The repo is pnpm-only; the packageManager field in package.json is enforced via Corepack. See ADR-0002.
Importing from another package's src/ directly. Internal imports use workspace:* and resolve through each package's dist/. Phantom dependencies are blocked by pnpm's isolated node_modules.
Forgetting the .js extension on TypeScript imports. NodeNext resolution requires import { x } from './foo.js' even for .ts source. See ADR-0001 §Implementation notes.
Running node against the dev src/ tree. Build first (pnpm build) or use tsx.

Checklist #

[ ] Node 20+ on PATH (node --version)
[ ] pnpm 9.x via Corepack (pnpm --version)
[ ] pnpm install succeeds without phantom-dep warnings
[ ] pnpm build produces dist/ in every package
[ ] pnpm test is green
[ ] aidokit init against a temp dir emits a .claude/ tree

project-overview.md — what each package does
how-to-guides/how-to-run-the-cli-locally.md — deeper run recipes
tutorials/scaffold-your-first-project.md — end-to-end walkthrough
how-to-guides/how-to-run-tests-and-byte-compare.md