Setup · Greenfield · Brownfield

Setup Guide

Two paths depending on whether you are starting fresh or already have an existing ~/.ai/ constitution.

Path A

Greenfield — starting from scratch

No existing constitution. You want the wizard to generate one personalized to you, wire all hooks, and be ready inside thirty minutes.

1. Install ai

brew install convergent-systems-co/tap/ai

On macOS, Gatekeeper may block the first run. Clear the quarantine flag: 

xattr -d com.apple.quarantine "$(which ai)"

2. Run the setup wizard

ai setup

The Bubble Tea wizard guides you through a set of questions across multiple phases:

On completion, setup writes and wires everything automatically:

Cursor and Codex/AGENTS.md are per-repo — setup prints a reminder to run ai init-integrate --cursor or --codex in each project.

3. Verify

ai doctor

All checks should show [✓]. Start a new Claude Code session — the compact constitution loads at session start.

Check coverage: every operative rule ID present in the compact form:

ai compress --check-coverage

4. Run your first review

ai review --check

Produces a governance report in ~/.ai/governance/reports/ covering violations, overrides, drift, and dead rules. Run it again in 30 days — the default cadence.

Path B

Brownfield — migrating an existing constitution

You already have a ~/.ai/ directory — either the original four-file layout (pre-v2) or an older single-file setup. Follow this path to migrate to the unified Constitution.md format without losing any of your existing rules.

1. Install ai

brew install convergent-systems-co/tap/ai

2. Back up your existing constitution

ai constitution backup

This archives the entire ~/.ai/ directory to ~/.ai-backups/<timestamp>.tar.gz — outside ~/.ai/ so the backup survives a restore. If anything goes wrong, run ai constitution restore to get back to exactly where you were.

3. Detect your current layout

ai doctor

Doctor tells you whether you are on the legacy four-file layout or the v2 unified format. If you see warnings about missing Constitution.md or stale runtime, proceed to step 4.

4a. If you have the four-file legacy layout

Migrate in three steps — each is safe to re-run: 

# Merge Constitution.md + Common.md + Code.md + Writing.md → one file
# Originals archived to ~/.ai/archive/pre-v2/
ai migrate --flatten

# Insert §2 Behavioral Standards section
ai migrate --add-behavioral

# Generate the compact runtime for Copilot / Cursor
ai migrate --generate-runtime

4b. If you already have a unified Constitution.md

# Regenerate the compact form (clients receive this, not the full file)
ai compress

# Re-wire hooks and tool integrations
ai hooks install --all

5. Verify

ai doctor

All checks should show [✓]. Start a new Claude Code session to load the migrated constitution. Your existing memory files, audit logs, and governance plans are preserved — migration only touches the constitution document and tool wiring.

6. Regenerate your constitution from the wizard (optional)

If you want the wizard to produce a fresh personalized constitution (discarding the migrated one), run: 

ai constitution backup   # archive current state first
ai setup                 # re-run the wizard

Your backup is always in ~/.ai-backups/ and restorable with ai constitution restore.

What's next