Scaffold Your First Project

Purpose #

End-to-end walkthrough: clone the repo, build it, run the CLI against an empty directory, inspect the emitted tree. Goal: build confidence with the toolchain before touching any code.

Big Picture #

You will run aidokit init from your local checkout against a scratch directory and read the emitted .claude/ tree against .docs/context/claude-workflow-kit-v4-base-part-3.md.

How It Works #

1. Prerequisites #

See getting-started/quick-start.md §Prerequisites. Node 20+, pnpm 9 via Corepack, Git, optionally Claude Code if you want to dogfood the emitted tree.

2. Clone + build #

git clone <repo-url> aidokit && cd aidokit
corepack enable
pnpm install
pnpm build
pnpm test    # optional but recommended — confirms a clean baseline

Expected: install < 60 s; cold build < 90 s; warm build < 30 s.

3. Create a scratch project #

mkdir /tmp/scratch && cd /tmp/scratch
git init

4. Run aidokit init #

From the scratch dir (using the locally built CLI):

node /path/to/aidokit/packages/cli/dist/bin/aidokit.js init \
  --adapter claude-code \
  --conformance standard \
  --stack node-ts \
  --yes

Notes:

--yes accepts non-sensitive prompts only — it does not bypass any securitySensitive confirmation or prereq install.
--stack node-ts skips detection.
If you omit any flag, you'll get interactive prompts via @clack/prompts.

5. Inspect the emitted tree #

/tmp/scratch/
├── CLAUDE.md
├── .claude/
│   ├── agents/          # 7 role files
│   ├── commands/        # intake.md, implement-task.md, orchestrator-next.md
│   ├── skills/          # 18+ skills (base + node-ts contributions)
│   ├── output-styles/   # 5 styles
│   ├── schemas/         # 8 JSON schemas
│   ├── scripts/         # 19 hook scripts (mode 0o755)
│   └── settings.json
├── docs/                # docs/ skeleton from @aidokit/shared-docs
├── agent-artifacts/     # 7 directory READMEs
└── .aido/
    └── adapter.md       # YAML manifest reflecting your selection

Compare counts against .docs/context/claude-workflow-kit-v4-base-part-3.md §§42–54.

6. Try `--dry-run` #

node /path/to/aidokit/packages/cli/dist/bin/aidokit.js init \
  --adapter claude-code --stack node-ts --yes --dry-run

The plan prints; nothing is written. Use this whenever you want to preview emissions without touching disk.

7. (Optional) Open in Claude Code #

cd /tmp/scratch
claude
# inside the session:
/intake "test prompt"

If Claude Code is installed at v2.1.32+, it auto-loads the emitted CLAUDE.md and surfaces the verbs as slash commands.

Example: what should match #

Spot-check a few invariants:

.claude/agents/ has exactly 7 files (Strict conformance) — Researcher, Architect, Planner, Builder, Tester-Reviewer, Maintainer, Frontend-Browser-Tester. See .docs/docs/specs/adapter-contract.md §7.4.
.claude/commands/ has exactly 3 files. The intake verb's content references the "hard stop before code" rule (conformance check adapter.emit-verbs.intake-stops-before-code).
.claude/scripts/*.mjs are mode 0o755. Run ls -l .claude/scripts/ to confirm.
CLAUDE.md references the source-of-truth chain and validation commands (adapter.emit-rules.references-source-of-truth-chain, adapter.emit-rules.includes-validation-commands).
.aido/adapter.md declares conformance: strict and lists the capability declarations.

Common Mistakes #

Running from the repo root instead of a scratch dir. aidokit init would mutate this repo's .claude/, breaking the dogfood gate.
Forgetting pnpm build. Without dist/, the bin/aidokit.js shim cannot resolve its sources.
Using npm instead of pnpm. The repo is pnpm-only — packageManager field enforces it via Corepack.
Expecting the latest dist-tag to exist on npm. Pre-v1.0 it is unset; only alpha works (ADR-0004 §3). For local work the dist-tag is irrelevant.

Checklist #

[ ] pnpm install && pnpm build && pnpm test all green.
[ ] Scratch dir created, git init run.
[ ] aidokit init succeeded, exit code 0.
[ ] Counted files in .claude/agents/, .claude/commands/, .claude/scripts/, .claude/skills/.
[ ] Read CLAUDE.md and .aido/adapter.md end-to-end.
[ ] Ran --dry-run and observed no writes.