Quick start
Bootstrap a complete, scope-enforced AI-assisted workflow into a new project in under a minute.
What happens when you run aidokit init
Five deterministic phases. Every write goes to .aido-staging/ first and is atomically promoted only when all phases succeed — if anything fails, your project root is untouched.
aidokit init]) --> B[1. Detect
OS, Node, git, stack] B --> C[2. Prompt
adapter, conformance,
stack, MCPs, Beads] C --> D[3. Confirm
show diff,
prereq notes] D --> E[4. Stage write
.aido-staging/] E --> F[5. Promote
atomic rename] F --> G([Done ~18s
open your AI CLI]) D -. cancel .-> X([staging discarded
project untouched]):::stop classDef stop fill:#fef2f2,stroke:#b91c1c,color:#7f1d1d; style A fill:#eff6ff,stroke:#2563eb style G fill:#f0fdf4,stroke:#15803d
Figure 1. The init pipeline. Read-before-write everywhere.
1. Create a project directory
mkdir my-app && cd my-app git init
2. Run aidokit init
npx aidokit@alpha init
Answer the interactive prompts:
- Adapter — which AI coding CLI you use (
claude-code,codex, orcopilot). - Conformance level —
minimum,standard(default), orstrict. See Conformance levels. - Stack pack(s) — aidokit auto-detects from
package.json,pyproject.toml, etc.; you confirm or override. - Beads — opt-in to the task graph / decision memory backend.
- MCP servers — pick from the catalog (see catalog).
Or skip the prompts entirely:
npx aidokit@alpha init \ --adapter claude-code \ --conformance standard \ --stack node-ts \ --yes
--yes accepts non-sensitive prompts only. Security-sensitive MCPs (Filesystem, graphify) and prerequisite installs still require explicit confirmation.3. Inspect what was emitted
ls -la # CLAUDE.md # .claude/ (or .codex/, .copilot/) # docs/ # agent-artifacts/ # .aido/adapter.md # .gitignore
Tour what each directory holds in The emitted workflow.
4. Open in your AI coding CLI
Claude Code
claude # inside the session: /intake "describe your project in one or two paragraphs"
Codex CLI
codex # The agent auto-loads AGENTS.md and the .codex/ workflow tree.
GitHub Copilot CLI
gh copilot # Copilot auto-loads .github/copilot-instructions.md workspace-wide.
5. Preview without writing (--dry-run)
Want to see what would happen first? Add --dry-run to any command that writes files:
npx aidokit@alpha init --adapter claude-code --stack node-ts --yes --dry-run
The CLI prints the full file plan and exits with code 0. Nothing is written; no shell commands are executed.
6. Health-check your setup
npx aidokit@alpha doctor
Read-only. Verifies prereqs, adapter, MCP scoping, conformance snapshot. Exit code 13 on any conformance failure.
Common starting flows
I have an existing project with a PRD or README
npx aidokit@alpha init --brownfield
See Brownfield.
I want multiple adapters in one project
npx aidokit@alpha init --adapter claude-code,codex,copilot
I'm running in CI
npx aidokit@alpha init --no-prompts --yes --json \ --adapter claude-code --conformance standard --stack node-ts
--json implies --no-prompts and --no-color and emits a single JSON object on stdout.
Next steps
- Concepts — the load-bearing ideas in 5 minutes.
- The emitted workflow — tour every directory the CLI writes.
- Adapters — pick the right one for your team.
- CLI reference — every command and flag.