setup-repository

What this skill does

# 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](https://howborisusesclaudecode.com/).

## Overview

This wizard guides you through 5 setup areas:

| Step | Area               | What It Creates                                          |
| ---- | ------------------ | -------------------------------------------------------- |
| 1    | **CLAUDE.md**      | Project-specific instructions Claude reads on startup    |
| 2    | **Slash Commands** | Workflow automation (commit-push-pr, test-and-fix, etc.) |
| 3    | **Agents**         | Specialized assistants (verify-app, code-simplifier)     |
| 4    | **Hooks**          | Automatic formatting on file edits                       |
| 5    | **Permissions**    | Pre-approved safe commands                               |

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:**

   ```text
   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

```markdown
# 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:**

| Command          | Description                                      | When to use                                 |
| ---------------- | ------------------------------------------------ | ------------------------------------------- |
| `commit-push-pr` | Stage, commit, push, create PR                   | Daily workflow - Boris uses dozens of times |
| `test-and-fix`   | Run tests, fix failures iteratively              | After code changes                          |
| `review-changes` | Review uncommitted changes, suggest improvements | Before committing                           |
| `quick-commit`   | Stage all and commit with generated message      | Fast commits                                |

**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

```markdown
---
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:**

```bash
mkdir -p .claude/commands
```

---

### Step 3: Agents Setup

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

**Agents to offer:**

| Agent             | Description                        | When to use                |
| ----------------- | ---------------------------------- | -------------------------- |
| `verify-app`      | End-to-end verification of changes | After completing a feature |
| `code-simplifier` | Clean up and simplify code         | After Claude writes code   |
| `build-validator` | Ensure project builds correctly    | Before creating PR         |

**For each agent, ask:**

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

#### Agent Template: verify-app.md

```markdown
---
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

```markdown
---
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:**

```bash
mkdir -p .claude/agents
```

---

### Step 4: Hooks Setup

**Goal:** Configure automatic hooks for formatting and validation.

**Available hooks:**

| Hook          | Trigger                   | Action                    |
| ------------- | ------------------------- | ------------------------- |
| `PostToolUse` | After Write/Edit          | Auto-format changed files |
| `PreToolUse`  | Before dangerous commands | Confirm with user         |

**Ask user:**

- "Would you like to enable auto-formatting on file