Quickstart

Install Anatomia, run init in your repo, and ship a verified change. Two minutes to scaffold. Twenty minutes to your first proof.

Reading time · 8 minLast reviewed · 2026-05-25

Prerequisites

  • Node.js 22 or later
  • Git with user.name and user.email configured
  • A Git repository with at least one commit
  • Claude Code with an active subscription — needed for pipeline agents (Steps 3–4)
  • GitHub CLI (gh) — used by Verify to create PRs after a passing run

Step 1: Install

bash
npm install -g anatomia-cli      # first install (or: npm update -g anatomia-cli)

Also available via pnpm add -g anatomia-cli or bun add -g anatomia-cli. This installs the ana command.

Step 2: Initialize

From inside your cloned repo:

bash
ana init

Init scans your project, detects your stack, and scaffolds the pipeline into your repo — agents, skills matched to your stack, and project context. Runs entirely on your machine. Your output will reflect your project:

terminal
✓ Scanned my-saas-app (3.2s)

  Stack:    TypeScript · Next.js · Prisma → PostgreSQL · Vitest
  Deploy:   Vercel

✓ Context → .ana/context/ (2 files)
✓ Skills → .claude/skills/ (7 skills)
    Core:      coding-standards, testing-standards, git-workflow,
               deployment, troubleshooting
    Detected:  api-patterns, data-access
  ✓ 4 gotchas pre-populated
  ✓ Cross-tool: CLAUDE.md + AGENTS.md

  Branch:   main
  Test:     pnpm run test -- --run
  Build:    pnpm run build

  Next:
    claude --agent ana          Start working
    claude --agent ana-setup    Enrich with team knowledge (optional, ~10 min)
Note

Verify detected commands. Init infers Test, Build, and Lint from your package.json. Override any command: ana config set commands.test "your-command". Monorepos with multiple surfaces: see Configurability for per-surface overrides.

Note

Optional but recommended: Run claude --agent ana-setup to calibrate project knowledge (~10 min). Setup investigates your codebase, asks 2–3 questions, and writes rich context.

Persist to git

Init created files locally. Commit them to your artifact branch so every collaborator and agent session has the same context:

bash
ana init commit

This stages only infrastructure files (.ana/, .claude/, CLAUDE.md, AGENTS.md), commits with --no-verify, and pushes. Pipeline data and per-developer state are automatically excluded.

Run ana doctor to verify the installation is healthy — it checks CLI version, scan freshness, context quality, skill enrichment, and proof chain status in one dashboard.

Step 3: First pipeline run

Note

External services. If your project uses a database, Redis, or Docker containers, start them before running the pipeline — agents execute your test command as-is.

Describe a small change — a single-file fix or a feature you'd normally spend 30 minutes on.

bash
claude --agent ana

Start with a greeting — "hey Ana" — so the agent loads your project context before you describe the work.

Ana investigates the codebase, surfaces tradeoffs, and writes a scope. You can scope several work items before building any of them — each runs through the pipeline independently. When you're ready to build, open a new terminal for each pipeline agent — agents must start fresh without state from previous runs:

  1. Plan: claude --agent ana-plan — reads the scope, writes spec.md, and seals contract.yaml
  2. Build: claude --agent ana-build — implements the spec, writes tests tagged to contract assertions
  3. Verify: claude --agent ana-verify — independently verifies against the contract, writes findings, creates PR on pass
Note

Each agent runs CLI commands like ana work start and ana artifact save under the hood — managing worktrees, validating artifact structure, and computing integrity hashes. You don't run these manually.

If Verify finds issues, it produces a FAIL report. Run claude --agent ana-build to fix, then claude --agent ana-verify again. This is normal — 22 of Anatomia's own 163 proofs had rejection cycles.

Step 4: Review, merge, and complete

After Verify passes, it creates a PR. Review the PR — compare Build's report with Verify's findings. This is the moment the two independent accounts meet. When you're satisfied, merge the PR, then complete the work item:

bash
ana work complete <slug>

This archives the plan and writes a proof chain entry — assertions, findings, timing, and SHA-256 hashes of every artifact. The proof is a JSON record committed to your repo. It travels with the code.

View it:

bash
ana proof <slug>

You'll see the contract score, findings by severity, and timing per stage. Every assertion the contract defined, independently verified. The proof chain grows with every pipeline run — a permanent record of what was built, how it was verified, and what was found.

Updating

bash
npm update -g anatomia-cli    # update the CLI
ana init                      # refresh scan data + skill detection
ana init commit               # persist the refresh

Updating the CLI changes the binary only. Your agents, skills, context, and proof chain don't change until you run ana init. When you do, your rules, context files, and proof history are preserved — only machine-detected data refreshes. Run ana doctor after updating to confirm everything is healthy — it checks all five dimensions in one command. ana work status will tell you when your project was initialized with an older version.

Next conceptThe pipelineFive stages, independence guarantees, and what each artifact proves.GuideReading a proofWhat each section of a proof page means.