Claude Code Repository Setup Wizard

Interactive setup wizard that configures any repository for optimal AI-assisted development, following best practices from Boris Cherny's workflow.

Overview

This wizard guides you through 5 setup areas:

You can skip any step. Each step analyzes your existing setup and makes recommendations.

Setup Protocol

Step 0: Repository Analysis

Before starting, analyze the repository to understand its structure:

1. Check for existing Claude Code configuration:

   • CLAUDE.md or AGENTS.md at root
   • .claude/ directory
   • .claude/commands/
   • .claude/agents/
   • Project-level settings.local.json

2. Identify repository type:

   • Check package.json for Node.js project
   • Check for Cargo.toml (Rust), go.mod (Go), pyproject.toml (Python)
   • Check for monorepo indicators (nx.json, pnpm-workspace.yaml, lerna.json)
   • Check for framework indicators (Next.js, React, Vite, etc.)

3. Detect existing tooling:

   • Package manager: npm, yarn, pnpm, bun
   • Test runner: jest, vitest, pytest, cargo test
   • Linter: eslint, prettier, biome
   • Build system: nx, turbo, make

4. Present analysis to user:

   textCopy

   Repository Analysis Complete
   
   Type: [Node.js monorepo / Python project / etc.]
   Package Manager: [npm/yarn/pnpm/bun]
   Test Runner: [jest/vitest/etc.]
   Existing Claude Config: [Yes/No - list what exists]
   
   Ready to proceed with setup? [Continue / Abort]
   

Step 1: CLAUDE.md Setup

Goal: Create or enhance the project's CLAUDE.md file with instructions Claude reads on every session.

If CLAUDE.md exists

1. Read the existing file
2. Analyze for completeness against best practices
3. Suggest enhancements (don't overwrite without permission)

If CLAUDE.md doesn't exist

1. Generate a tailored CLAUDE.md based on repository analysis
2. Include:
   • Project overview (inferred from README/package.json)
   • Build commands (detected from package.json scripts)
   • Test commands
   • Code style preferences (inferred from linter configs)
   • Key conventions

CLAUDE.md Template Structure

# CLAUDE.md

## Project Overview

[Brief description of what this project does]

## Build Commands

[Detected from package.json/Makefile/etc.]

## Test Commands

[Detected test runner commands]

## Code Style

[Inferred from .eslintrc, .prettierrc, etc.]

## Key Patterns

[Framework-specific patterns if detected]

## Learnings

[Empty section - add mistakes/corrections here over time]

Ask user:

• "Should I create/enhance CLAUDE.md? [Yes / Skip]"
• If yes, show preview and ask for confirmation

Step 2: Slash Commands Setup

Goal: Create workflow automation commands in .claude/commands/.

Commands to offer:

For each command, ask:

• "Would you like to add /{command-name}? [Yes / No / Customize]"

Customize options:

• Git tool: git vs gh vs gt (Graphite)
• PR creation method: GitHub CLI vs Graphite
• Commit message style: conventional commits vs freeform

Command Template: commit-push-pr.md

---
name: commit-push-pr
description: Commit changes and create a pull request
allowed-tools: Bash(git:*), Bash(gh:*), Read, Glob
---

# Commit, Push, and Create PR

## Steps

1. **Check status**: Run `git status` to see changes
2. **Stage files**: Add changed files individually (never `git add .`)
3. **Generate commit message**: Analyze diff and generate meaningful message
4. **Commit**: Run `git commit -m "[message]"`
5. **Push**: Run `git push -u origin [branch]`
6. **Create PR**: Run `gh pr create --fill` or show PR creation options

## Commit Message Format

Use conventional commits: `type(scope): description`

Types: feat, fix, docs, style, refactor, test, chore

Create directory and files:

mkdir -p .claude/commands

Step 3: Agents Setup

Goal: Create specialized agent assistants in .claude/agents/.

Agents to offer:

For each agent, ask:

• "Would you like to add the {agent-name} agent? [Yes / No]"

Agent Template: verify-app.md

---
name: verify-app
description: Thoroughly verify changes work end-to-end
---

# Verification Agent

Verify that recent changes work correctly before considering them complete.

## Verification Steps

1. **Build Check**: Run the build command and verify success
2. **Test Check**: Run the test suite and verify all tests pass
3. **Type Check**: Run type checking if applicable
4. **Lint Check**: Run linters and verify no errors
5. **Manual Verification**: For UI changes, describe what to check visually

## Output

Report verification results:

- Build: [PASS/FAIL]
- Tests: [PASS/FAIL] - X passed, Y failed
- Types: [PASS/FAIL]
- Lint: [PASS/FAIL]

If any check fails, explain the failure and suggest fixes.

Agent Template: code-simplifier.md

---
name: code-simplifier
description: Simplify and clean up code after changes
---

# Code Simplifier Agent

Review recently changed code and simplify where possible.

## Simplification Targets

1. **Dead code**: Remove unused variables, functions, imports
2. **Duplication**: Extract repeated patterns into functions
3. **Complexity**: Simplify nested conditionals, reduce cognitive load
4. **Naming**: Improve unclear variable/function names
5. **Comments**: Remove obvious comments, add clarifying ones where needed

## Constraints

- Do NOT change behavior
- Do NOT add new features
- Do NOT refactor unrelated code
- Keep changes minimal and focused

## Output

List changes made with before/after snippets.

Create directory:

mkdir -p .claude/agents

Step 4: Hooks Setup

Goal: Configure automatic hooks for formatting and validation.

Available hooks:

Ask user:

• "Would you like to enable auto-formatting on file edits? [Yes / No]"
• "What formatter do you use? [prettier / eslint --fix / biome / detected]"

PostToolUse Hook Configuration

Add to user's global ~/.claude/settings.json (for all projects) or project's .claude/settings.local.json (for this project only):

Note: Hook configuration uses ~/.claude/settings.json, which is different from ~/.claude.json (used for MCP servers).

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "[formatter command]"
          }
        ]
      }
    ]
  }
}

Formatter detection:

• Check for .prettierrc → npx prettier --write
• Check for biome.json → npx biome format --write
• Check for .eslintrc → npx eslint --fix

Step 5: Permissions Setup

Goal: Pre-approve common safe commands to reduce permission prompts.

Permission categories to offer:

Ask user for each category:

• "Pre-approve {category} commands? [Yes / No]"

Permissions Configuration

Add to .claude/settings.local.json:

{
  "permissions": {
    "allow": [
      "Bash(npm run:*)",
      "Bash(npm test:*)",
      "Bash(npx:*)",
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(git log:*)"
    ]
  }
}

Note: Write permissions to project's .claude/settings.local.json, not global settings.

Completion Summary

After all steps, present a summary:

Setup Complete!

Created/Modified:
- [x] CLAUDE.md (created/enhanced)
- [x] .claude/commands/commit-push-pr.md
- [x] .claude/commands/test-and-fix.md
- [x] .claude/agents/verify-app.md
- [x] .claude/agents/code-simplifier.md
- [x] .claude/settings.local.json (hooks + permissions)

Skipped:
- [ ] review-changes command (user skipped)

Next Steps:
1. Review the created files and customize as needed
2. Try running /commit-push-pr on your next commit
3. Add project-specific learnings to CLAUDE.md over time
4. Consider adding the files to .gitignore or committing them

Tips:
- Start sessions in Plan mode (Shift+Tab twice) for complex tasks
- Use verification commands to catch issues early
- Update CLAUDE.md whenever Claude makes a mistake

References

For more details on each component:

• Boris' Setup Guide
• CLAUDE.md Examples
• Command Templates
• Agent Templates

Troubleshooting