Setup AI

Codebase AI Setup

One-command setup for AI-assisted development. Generates the context files AI tools need, configures your environment, and detects what's already configured — only adds what's missing.

Arguments: $ARGUMENTS

Modes

• No arguments / --project: Set up the current codebase — generate AGENTS.md, CLAUDE.md symlink, STYLE_GUIDE.md, initialize Beads, create directories (default behavior)
• --global: Configure machine-level settings (~/.claude/settings.json) — notification hooks, plugin checklist
• --check: Read-only — verify your environment is fully configured. Reports what's present, what's missing, what needs attention. Does not write anything.

If no mode is specified, default to --project (setup the current project).

--project Mode (default)

Step 0: Install Dependencies

Check and install required tooling:

# Beads -- AI-native task/issue tracker
# Check if bd is installed (cross-platform)
npx --yes @beads/bd --version || npm install -g @beads/bd

If bd is already installed, skip. If not, install it globally. This gives the project bd for issue tracking, dependency-aware task management, and git-synced work coordination between human and AI agents.

Note: npx works on both macOS and Windows. Do NOT use which (Unix-only) or where (Windows-only) to check for binaries.

Step 1: File Protection Protocol (MANDATORY)

Before ANY write to CLAUDE.md, AGENTS.md, or STYLE_GUIDE.md, you MUST run this check. This is not optional.

# Deterministic pre-flight check — run BEFORE any file generation
CLAUDE_EXISTS=false; AGENTS_EXISTS=false; STYLE_EXISTS=false
CLAUDE_IS_SYMLINK=false
[ -f "CLAUDE.md" ] && CLAUDE_EXISTS=true
[ -L "CLAUDE.md" ] && CLAUDE_IS_SYMLINK=true
[ -f "AGENTS.md" ] && AGENTS_EXISTS=true
[ -f "STYLE_GUIDE.md" ] && STYLE_EXISTS=true
[ -f ".cursorrules" ] && echo ".cursorrules found"
[ -d ".beads" ] && echo ".beads/ found"
[ -d ".claude/learnings" ] && echo ".claude/learnings/ found"
[ -d "docs/solutions" ] && echo "docs/solutions/ found"
[ -d "docs/claude" ] && echo "docs/claude/ found"
echo "CLAUDE.md exists: $CLAUDE_EXISTS (symlink: $CLAUDE_IS_SYMLINK)"
echo "AGENTS.md exists: $AGENTS_EXISTS"
echo "STYLE_GUIDE.md exists: $STYLE_EXISTS"

If AGENTS.md exists ($AGENTS_EXISTS = true):

1. Report: "Found existing AGENTS.md (N lines). Skipping (will not overwrite)."
2. Default action: SKIP. Continue with other setup steps without touching it.
3. Only if the user explicitly asks to regenerate, offer these options:
   • (a) Show what would be generated — display the scaffold so the user can manually merge.
   • (b) Regenerate — only with explicit confirmation. Back up first: cp AGENTS.md AGENTS.md.bak
4. NEVER use the Write tool on AGENTS.md when it already exists without explicit user request AND creating a .bak first.

If CLAUDE.md exists and is NOT a symlink ($CLAUDE_EXISTS = true, $CLAUDE_IS_SYMLINK = false):

1. Report: "Found existing CLAUDE.md (N lines, standalone file). Skipping (will not overwrite)."
2. Default action: SKIP. Continue with other steps without touching it.
3. Only if the user explicitly asks to modify, offer these options:
   • (a) Append Quality Gates section — add the Quality Gates block to the end if not already present. Does not modify existing content. Uses Edit (append), not Write.
   • (b) Migrate to AGENTS.md — incorporate content into AGENTS.md and replace CLAUDE.md with a symlink. Only with explicit user confirmation and .bak backup.
   • (c) Show scaffold diff — display what the scaffold WOULD contain, so the user can manually merge.
4. NEVER use the Write tool on CLAUDE.md when it already exists — only Edit (append) for option (a), or skip.

If CLAUDE.md exists and IS a symlink ($CLAUDE_IS_SYMLINK = true):

1. Report: "Found existing CLAUDE.md (symlink → AGENTS.md). Already configured correctly."
2. Skip — no action needed.

If STYLE_GUIDE.md exists ($STYLE_EXISTS = true):

1. Report: "Found existing STYLE_GUIDE.md (N lines). Skipping."
2. Default action: SKIP. Only regenerate if user explicitly asks, and back up first: cp STYLE_GUIDE.md STYLE_GUIDE.md.bak

Step 2: Generate AGENTS.md (if needed)

If no AGENTS.md exists (or user approved regeneration):

Analyze the codebase and generate AGENTS.md. This is the primary context file — tool-agnostic, works with Claude Code, Copilot, Cursor, Codex, etc.

AGENTS.md should contain:

• Project overview — 1-2 sentence description (what it does, who it's for)
• Stack deviations — only what DIFFERS from framework defaults. "React 19" = discoverable, skip it. "We use Bun not npm" = valuable, include it.
• Commands — dev server, test, build, lint commands in a table. Auto-detect from package.json/Makefile. Include ALL non-standard scripts and custom CLIs.
• Conventions summary — reference STYLE_GUIDE.md for details
• Critical warnings — project-specific footguns agents can't discover on their own
• Behavior Directives (always include — these CANNOT be inferred from code):

<avoid_over_engineering>
Only make changes that are directly requested or clearly necessary.
</avoid_over_engineering>

<run_tests_in_background>
Run long commands (tests, typechecks, builds) with `run_in_background=true`.
Check results with `TaskOutput` -- don't block on slow operations.
</run_tests_in_background>

<tdd_required>
TDD is mandatory for ALL code changes -- features and bug fixes alike.

**Bug Fix Process:**
1. **Write a failing test FIRST** -- reproduce the bug
2. **Verify test fails** -- confirm it catches the bug
3. **Fix the implementation** -- minimal change
4. **Verify test passes** -- confirm the fix works

**Feature Process:**
1. **Write a failing test** -- define expected behavior
2. **Implement minimal code** to make it pass
3. **Refactor** if needed, keeping tests green

**DO NOT fix first then write a test.** The test must fail before the fix. This is non-negotiable -- subagents must follow TDD too.
</tdd_required>

<use_beads_for_task_management>
ALWAYS use `bd` (beads) for task management -- never use TodoWrite or internal task tools. Break work into beads issues, update status as you go, and close when done.

Key commands: `bd create`, `bd list`, `bd show <id>`, `bd update <id> --status <status>`, `bd close <id>`.

**Sync protocol:** Beads data lives in `.beads/issues.jsonl` (git-tracked). The Dolt DB is local-only.
- **Session start:** Run `bd list` -- this auto-imports from JSONL if it's newer than local Dolt DB.
- **Before committing:** Run `bd backup` to flush Dolt -> JSONL, then include the `.beads/` changes in your commit.
- **After pulling:** Any `bd` command auto-detects stale DB and re-imports.
</use_beads_for_task_management>

• Quality Gates (always include):

## Quality Gates

### Canonical Workflow (Do NOT skip or reorder)
1. Draft plan (if non-trivial) → `/critic-review` → address feedback → finalize
2. Implement → run tests
3. `superpowers:code-reviewer` — review against plan and standards
4. `/simplify` — review for reuse/quality/efficiency. Re-run until clean
5. Commit → create PR → push

**Pre-PR:** `/simplify` is mandatory before every PR. No exceptions. If suggestions conflict with `<avoid_over_engineering>`, the directive wins.

• Detailed Guides — link to docs/claude/ for topic-specific deep dives
• Style Guide — link to STYLE_GUIDE.md for coding conventions

Do NOT generate:

• Tech stack lists or project structure sections — agents discover these from source files
• Content that duplicates README, package.json, or tsconfig — redundant context increases inference cost 14-22% per ETH Zurich research

Keep it under 200 lines total. If .cursorrules exists, incorporate its content.

Step 3: Create CLAUDE.md Link

After AGENTS.md is written, detect the platform and create the appropriate link:

macOS/Linux:

ln -sf AGENTS.md CLAUDE.md

Windows (PowerShell or cmd):

# Copy instead of symlink -- Windows symlinks require Developer Mode or admin
copy AGENTS.md CLAUDE.md

Platform detection: Check os.platform() or uname to determine which approach to use. On Windows, prefer copying AGENTS.md to CLAUDE.md since symlinks require Developer Mode enabled or admin privileges. The tradeoff: Windows users must re-copy after editing AGENTS.md (or just edit CLAUDE.md directly). On macOS/Linux, always use a symlink.

This ensures Claude Code reads the project context natively while AGENTS.md remains the primary, tool-agnostic file.

If AGENTS.md was skipped but CLAUDE.md doesn't exist either, generate a standalone CLAUDE.md scaffold with just the behavior directives and quality gates sections (no project context — that's AGENTS.md's job).

If both AGENTS.md and CLAUDE.md already exist: When scaffolding is not needed, add this awareness comment if creating any new file alongside them:

<!-- This project has both AGENTS.md and CLAUDE.md.
     AGENTS.md is for project context; CLAUDE.md is for behavioral directives.
     Keep them separate — don't duplicate content between files. -->

Step 4: Generate STYLE_GUIDE.md (if needed)

If no STYLE_GUIDE.md exists (or user approved regeneration):

Follow the full style guide generation process:

1. Detect tech stack from dependency/config files
2. Read existing linter/formatter configs (.eslintrc, .prettierrc, .rubocop.yml, biome.json, etc.)
3. Sample 10-15 representative files for patterns
4. Identify testing patterns from test files
5. Check git history for commit/branch conventions

Generate STYLE_GUIDE.md with evidence-backed conventions for:

• Language & formatting
• Naming conventions (files, variables, functions, classes, database)
• Code organization and import ordering
• Function patterns and error handling
• Testing standards
• API and database patterns
• Git conventions
• Anti-patterns to avoid

Rules for style guide generation:

• ONLY document patterns you actually observe in the code. Never hallucinate conventions.
• When patterns are inconsistent across the codebase, note the inconsistency and ask the user which convention to standardize on.
• Cite specific files as evidence: "Based on src/services/UserService.ts, src/services/OrderService.ts..."
• If a STYLE_GUIDE.md already exists, read it first and improve/incorporate rather than overwriting.

For deeper standalone style analysis (17-section output, full evidence citations), use /generate-comprehensive-style-guide. For pre-commit/pre-PR style enforcement against the generated guide, use /review-style-guide.

Step 5: Initialize Beads (if needed)

If no .beads/ directory exists:

bd init

This creates the .beads/ directory with config, issue tracking, and git hooks. After init, add the Beads integration to .claudeignore:

# Beads internals
.beads/dolt/

(Keep .beads/issues.jsonl and .beads/config.yaml tracked in git — only exclude the Dolt database files.)

If .beads/ already exists, skip initialization.

Step 6: Create Directories

Create if missing:

• docs/solutions/ — institutional learnings for AI retrieval (Compound Engineering pattern: markdown with YAML frontmatter, grouped by category subdirs such as best-practices/, runtime-errors/). Agents and hooks search here alongside AGENTS.md / CLAUDE.md when the project documents that path. Add docs/solutions/.gitkeep if the tree is empty so git tracks the directory.
• docs/claude/ — for dynamic imports from AGENTS.md / CLAUDE.md
• .claude/learnings/ — optional; freeform notes if you use session hooks that read this path (not the same layout as docs/solutions/)

Step 7: Add Cross-References

If both AGENTS.md and STYLE_GUIDE.md were generated:

• Add to the bottom of AGENTS.md: ## Style Guide\nSee [STYLE_GUIDE.md](STYLE_GUIDE.md) for detailed coding conventions.
• Ensure STYLE_GUIDE.md header notes the generation date

Step 8: Summary

Present a deterministic report card. Track each file's outcome through the run and display the final state:

## Setup Complete

| File | Status |
|------|--------|
| AGENTS.md | ✅ Created (N lines) | ⏭️ Skipped (already existed, N lines) |
| CLAUDE.md | ✅ Created (symlink → AGENTS.md) | ⏭️ Skipped (symlink intact) | ⏭️ Skipped (standalone file, N lines) |
| STYLE_GUIDE.md | ✅ Created (N lines) | ⏭️ Skipped (already existed, N lines) |
| .beads/ | ✅ Initialized | ⏭️ Skipped (already existed) |
| docs/solutions/ | ✅ Created | ⏭️ Already existed |
| docs/claude/ | ✅ Created | ⏭️ Already existed |
| .claude/learnings/ | ✅ Created | ⏭️ Already existed |

Then add:

1. File structure note: "AGENTS.md is the primary file. CLAUDE.md is a symlink (macOS/Linux) or copy (Windows) of it."
2. Any ambiguities or inconsistencies that need a human decision (e.g., conflicting naming patterns, unclear conventions)
3. "Review generated files. AI gets ~80% right — the 20% you fix is the most valuable part."
4. Next steps:
   • "Run /audit-claude-md to score your setup and see where to improve."
   • "Run /generate-comprehensive-style-guide for a deeper 17-section style analysis."
   • "Run /review-style-guide before PRs to enforce style conventions."

--global Mode

1. Notification Hook (macOS)

Plays the macOS "Funk" sound when Claude Code needs your attention. Essential when running multiple parallel sessions.

Check: Read ~/.claude/settings.json, inspect hooks.Notification array.

If empty or missing, add:

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "afplay \"/System/Library/Sounds/Funk.aiff\""
          }
        ]
      }
    ]
  }
}

Important: Merge into existing settings — do NOT overwrite other hook categories (SessionStart, Stop, etc.). Use jq or read-modify-write to safely merge.

Platform note: This uses macOS afplay. On Linux, suggest paplay or aplay as alternatives. On Windows/WSL, suggest powershell.exe -c "(New-Object Media.SoundPlayer 'C:\Windows\Media\chord.wav').PlaySync()".

2. Recommended Plugins Check

Report which recommended plugins are installed vs missing:

Don't auto-install plugins — just report what's missing and provide install commands.

Execution Flow

1. Read ~/.claude/settings.json
2. For each missing global config:
   a. Show what will be added
   b. Ask for confirmation
   c. Apply the change
3. Report final state

--check Mode

Read-only audit of your setup. Does not write anything.

1. Read ~/.claude/settings.json
2. Report:
   ✅ Notification hook: configured (Funk.aiff)
   ❌ Notification hook: not configured
   ✅ Plugin: superpowers (installed)
   ❌ Plugin: episodic-memory (not installed)
   ...
3. If in a project, also check:
   ✅ AGENTS.md exists (142 lines) — run /audit-claude-md to score it
   ✅ CLAUDE.md exists (symlink → AGENTS.md)
   ⚠️  CLAUDE.md over 200 lines (287 lines) — may increase inference cost 14-22%
   ❌ CLAUDE.md missing — run /setup-ai to scaffold
   ✅ STYLE_GUIDE.md exists (87 lines)
   ❌ STYLE_GUIDE.md missing — run /setup-ai or /generate-comprehensive-style-guide
   ✅ .beads/ initialized
   ❌ .beads/ missing — run /setup-ai or bd init
   ✅ docs/solutions/ exists (structured learnings / Compound pattern)
   ❌ docs/solutions/ missing — run /setup-ai or mkdir -p docs/solutions && touch docs/solutions/.gitkeep
   ✅ docs/claude/ exists
   ❌ docs/claude/ missing
   ✅ .claude/learnings/ exists (optional hook notes)
   ✅ Background processes directive found
   ✅ TDD directive found (tdd_required section detected)
   ❌ TDD directive missing — add <tdd_required> block to Behavior Directives
   ✅ Quality Gates workflow found
   ❌ Quality Gates missing — add Canonical Workflow section
   ✅ Non-standard tools documented (3 found: uv, custom-cli, deploy.sh)
   ⚠️  Tech stack section may duplicate package.json — consider trimming
   ✅ Behavior directives present (XML-style sections detected)

Safety Rules

• NEVER overwrite CLAUDE.md, AGENTS.md, or STYLE_GUIDE.md without explicit user confirmation. Run the bash existence check first, present options, wait for their answer. No exceptions. No "I'll just replace it with a better version." The user's existing files are sacred.
• NEVER use the Write tool on any of these files when they already exist — only with explicit user approval AND after creating a .bak backup first. Use Edit (append) for safe additions like Quality Gates.
• NEVER choose options on behalf of the user. Present the options and wait for their response.
• ONLY document patterns you actually observe in the code. Never hallucinate conventions.
• When patterns are inconsistent, note the inconsistency and ask which to standardize on.
• Cite specific files as evidence for every convention.
• If only one file needs generating, skip the others gracefully.
• AGENTS.md is always the primary file. CLAUDE.md is a symlink (macOS/Linux) or copy (Windows). On macOS/Linux, never write content to CLAUDE.md directly — edit AGENTS.md and the symlink follows. On Windows, edits to either file are fine but keep them in sync.
• Never overwrite existing configuration — only add missing pieces.
• Always confirm before writing to settings.json.
• Read-modify-write for JSON files — never clobber existing keys.
• Don't auto-install plugins — report what's missing and provide commands.
• Detect platform — macOS vs Linux vs WSL for notification hook sound command and symlink strategy.
• Commit the symlink (or copy) to git so it persists for the whole team.