Setup Rules

/setup-rules - Set Up Project Rules

Set up and audit project rules. Reads your codebase, generates modular rules, and documents MCP servers.

Flow: Read existing → Migrate → Quality audit → Explore → Compare → Sync rules → Sync MCP → Discover rules → Cross-check → Summary

Skill creation: Use /create-skill to create workflow skills — /setup-rules focuses exclusively on rules and MCP documentation.

Phase 0: Reference

Guidelines

• Always use AskUserQuestion when asking the user anything
• Read before writing — check existing rules before creating
• Write concise rules — every word costs tokens in context
• Idempotent — running multiple times produces consistent results

Project Slug

Derive the project slug from the git repo or directory name. Use it as a prefix for ALL created rules and skills to avoid name collisions across repositories.

# Derive slug: git repo name (preferred) or directory basename
SLUG=$(basename "$(git remote get-url origin 2>/dev/null | sed 's/\.git$//')" 2>/dev/null || basename "$PWD")
# Result: "pilot-shell", "my-api", "acme-backend"

Use {slug}- prefix on everything: {slug}-project.md, {slug}-mcp-servers.md, {slug}-{topic}.md.

Output Locations

Custom rules in .claude/rules/: {slug}-project.md (tech stack, structure), {slug}-mcp-servers.md (custom MCP servers), {slug}-{pattern-name}.md (tribal knowledge).

Use unique names (not plan, implement, verify, standards-*) for custom rules.

Recommended Directory Structure

For monorepos with multiple products/teams, organize rules in nested subdirectories:

.claude/rules/
├── README.md                          # Structure guide (generated by /setup-rules)
├── {slug}-project.md                  # Repo-wide: tech stack, structure, commands
├── {slug}-mcp-servers.md              # MCP server documentation
├── {slug}-conventions.md              # Repo-wide coding conventions
├── {product-a}/                       # Product A rules
│   ├── {slug}-{product-a}-project.md  # Product-wide: stack, patterns, commands
│   ├── {slug}-{product-a}-api.md      # Product-wide: API conventions
│   ├── team-x/                        # Team X rules (MUST use `paths`)
│   │   └── {slug}-team-x-data.md      # Team-specific patterns
│   └── team-y/                        # Team Y rules (MUST use `paths`)
│       └── {slug}-team-y-frontend.md  # Team-specific patterns
├── {product-b}/                       # Product B rules (same structure)
│   └── ...
└── common/                            # Shared libraries rules
    └── {slug}-common-utils.md         # Shared utility conventions

Scoping rules:

⛔ Team-level rules without paths frontmatter load every session for every file — defeating the purpose of scoping. Always add paths to team-level rules.

Example paths frontmatter:

---
paths:
  - "src/ubervoice/**"
  - "tests/ubervoice/**"
---

When to use nested structure vs flat: If the repo has 2+ distinct products, teams, or major modules with different conventions → nested. If it's a single-product repo → flat is fine.

Error Handling

Writing Rules

Rules load every session — every word costs tokens.

• Lead with the rule — what to do first, why second
• Code examples over prose — show, don't tell
• Skip the obvious — don't document standard framework behavior
• One concept per rule — don't combine unrelated patterns
• Bullet points > paragraphs — scannable beats readable
• Max ~100 lines per file — split large topics
• Meaningful descriptions — never write vague comments like "Also an entry". State what it does and when it's used.
• Portable paths — use relative paths or variables, not absolute paths that break on other machines (cd tests/unit, not cd /home/user/project/tests/unit)
• Current syntax — use modern tool versions and command syntax (e.g., docker compose not docker-compose)

Claude Code Best Practices Reference

From the official Claude Code documentation — use these as the quality baseline for the Quality Audit (Phase 3).

What belongs in rules (loaded every session):

• Bash commands Claude can't guess
• Code style rules that differ from defaults
• Testing instructions and preferred test runners
• Repository etiquette (branch naming, PR conventions)
• Architectural decisions specific to the project
• Developer environment quirks (required env vars)
• Common gotchas or non-obvious behaviors

What does NOT belong in rules:

• Anything Claude can figure out by reading code
• Standard language conventions Claude already knows
• Detailed API documentation (link to docs instead)
• Information that changes frequently
• Long explanations or tutorials
• File-by-file descriptions of the codebase
• Self-evident practices like "write clean code"

Structure & size:

• Target under 200 lines per file — longer files reduce adherence
• Use markdown headers and bullets — organized sections > dense paragraphs
• Write instructions concrete enough to verify: "Use 2-space indentation" not "Format code properly"
• Remove conflicting instructions — contradictions cause arbitrary behavior
• Use emphasis ("IMPORTANT", "YOU MUST") for critical rules
• Use @path/to/import syntax to reference external files instead of inlining

Scoping:

• Use paths frontmatter in .claude/rules/ to scope rules to specific file types — reduces noise and saves context
• Domain knowledge or workflows only relevant sometimes → skills (loaded on demand), not rules (loaded every session)
• Use CLAUDE.local.md for personal project preferences not shared via git

Litmus test for every instruction: "Would removing this cause Claude to make mistakes?" If not, cut it.

Phase 1: Read Existing Rules & Skills

MANDATORY FIRST STEP.

1. Derive the project slug (see Phase 0 → Project Slug)
2. find .claude/rules/ -name '*.md' -not -name 'README.md' 2>/dev/null | sort — read each rule file (including subdirectories)
3. Check for legacy CLAUDE.md: ls CLAUDE.md claude.md .claude.md 2>/dev/null — read if found
4. Detect unscoped legacy files — look for project.md, mcp-servers.md, or any rule without the {slug}- prefix. Flag for migration in Phase 2.
5. Detect nested rule directories — check for subdirectories within .claude/rules/ (product/team structure per Phase 0 → Recommended Directory Structure). Map each subdirectory, its depth level (product vs team), and contents. Also check for sub-projects with their own .claude/rules/ or CLAUDE.md.
6. Validate path-scoping — for rules in nested subdirectories, check that they have paths frontmatter. Flag any team-level rules (depth 2+) missing paths as errors for Phase 3.
7. Build inventory: documented rules (with directory structure map), CLAUDE.md contents, gaps, outdated items, legacy files, nested directories, path-scoping violations

Phase 2: Migrate Unscoped Assets — CONDITIONAL

Only if Phase 1 found unscoped files.

AskUserQuestion: "Found unscoped assets that should be prefixed with '{slug}-' for better Team sharing. Migrate now?"

• "Yes, migrate all" — rename each to {slug}-{name}, update internal references, delete old file
• "Review each" — show each file, let user decide per-file
• "Skip" — leave as-is, continue sync

Migration rules:

• project.md → {slug}-project.md | mcp-servers.md → {slug}-mcp-servers.md | {topic}.md → {slug}-{topic}.md (unless managed by a framework like Pilot Shell)
• Do NOT migrate files from ~/.claude/rules/ — those are global user rules

Phase 3: Quality Audit

Audit all existing rules and CLAUDE.md files against Claude Code best practices (Phase 0 → Best Practices Reference). Present findings as improvement suggestions — do NOT modify files without user confirmation.

Skip this phase if: No existing rules or CLAUDE.md files found in Phase 1 (nothing to audit).

Step 3.1: Run Checks

For each rule file and CLAUDE.md found in Phase 1, evaluate:

How to check for specificity: Look for adjectives without measurable criteria ("good", "clean", "proper", "nice"), instructions that restate language defaults, and rules without concrete examples or verifiable outcomes.

How to check for stale references: For each file path, command, or tool name referenced in rules, verify existence:

# File paths
ls -la <referenced-path> 2>/dev/null

# Commands
which <referenced-command> 2>/dev/null

# Code patterns (Probe if available, otherwise Grep)
probe search "<referenced-pattern>" ./ --max-results 1 --max-tokens 500
# Fallback: Grep(pattern="<referenced-pattern>", head_limit=5)

Step 3.2: Present Findings

Group findings by severity and present to user:

## Quality Audit Results

### Errors (should fix)
- ❌ **Conflict:** `.claude/rules/style.md` says "use tabs" but `CLAUDE.md` says "use 2-space indent"
- ❌ **Stale:** `.claude/rules/project.md` references `src/legacy/` which no longer exists

### Warnings (recommended)
- ⚠️ **Size:** `CLAUDE.md` is 340 lines — split into modular rules or use @imports (target: <200 lines)
- ⚠️ **Vague:** `.claude/rules/style.md` line 12: "Format code properly" → suggest: "Run `prettier --write` before committing"
- ⚠️ **Overlap:** Authentication instructions appear in both `CLAUDE.md` and `.claude/rules/auth.md`

### Suggestions (nice to have)
- 💡 **Path-scope:** `.claude/rules/testing.md` only mentions `*.test.ts` files — add `paths: ["**/*.test.ts"]` frontmatter
- 💡 **Emphasis:** `.claude/rules/security.md` line 5: "Never commit secrets" — add "IMPORTANT:" prefix
- 💡 **Import:** `CLAUDE.md` inlines API docs — replace with `@docs/api-reference.md`

Step 3.3: User Decision

AskUserQuestion (multiSelect): "Select improvements to apply:"

• List each finding with checkbox
• Group by file for clarity
• Options: "Fix all errors & warnings" | "Review each" | "Fix errors only" | "Skip audit"

Step 3.4: Apply Selected Fixes

For each selected improvement:

1. Read the target file
2. Apply the specific fix (rewrite vague instruction, add paths frontmatter, split large file, remove stale reference, add emphasis, resolve conflict)
3. Show the diff to user before writing
4. Write the updated file

For file splits: When splitting a file over 200 lines, create new modular files in .claude/rules/ with the {slug}- prefix and add @path imports in the original if appropriate.

For conflict resolution: Present both conflicting instructions, ask user which is correct, update both files to be consistent.

Phase 4: Explore Codebase

Step 4.1: Setup

1. Check probe --version — if available, use Probe for semantic exploration (Step 4.2). If not installed, skip Step 4.2 and use Grep/Glob/Read in Step 4.3.
2. Ensure docs/plans/ exists — /spec stores plans here: mkdir -p ./docs/plans
3. Directory structure: tree -L 3 -I 'node_modules|.git|__pycache__|dist|build|.venv|.next|coverage|.cache|cdk.out'
4. Technologies: Check package.json, pyproject.toml, tsconfig.json, go.mod
5. Source documents: Find and read canonical docs — docs/, **/ARCHITECTURE.md, **/CONTRIBUTING.md, **/docs/*.md. These are the source of truth for generated rules — keep them open when writing.

Step 4.2: Semantic Exploration with Probe — OPTIONAL

Skip if Probe is not installed. Use probe search (via Bash) to understand each area that rules need to cover. Always use --max-results 5 --max-tokens 2000 to keep context lean. Adapt queries to what the project actually does — these are starting points, not a checklist:

# Architecture & structure
probe search "how is the application structured and what are the main entry points" ./ --max-results 5 --max-tokens 2000
probe search "how are services or modules organized" ./ --max-results 5 --max-tokens 2000

# Patterns & conventions
probe search "how are API endpoints defined and routed" ./ --max-results 5 --max-tokens 2000
probe search "how is authentication and authorization handled" ./ --max-results 5 --max-tokens 2000
probe search "how is configuration loaded and environment variables used" ./ --max-results 5 --max-tokens 2000
probe search "how is error handling done" ./ --max-results 5 --max-tokens 2000
probe search "how are database models or data access patterns structured" ./ --max-results 5 --max-tokens 2000

# Testing
probe search "how are tests organized and what testing patterns are used" ./ --max-results 5 --max-tokens 2000
probe search "test fixtures and helpers" ./ --max-results 5 --max-tokens 2000

# Build & deploy
probe search "how is the application built and deployed" ./ --max-results 5 --max-tokens 2000
probe search "CI/CD pipeline configuration" ./ --max-results 5 --max-tokens 2000

Follow up with probe extract to pull concrete examples for rules:

probe extract src/routes/users.ts#createUser
probe extract tests/conftest.py:1-30

Step 4.3: Fill Gaps

This is the primary exploration step when Probe is not available.

1. Grep for key patterns — entry points, route definitions, config loading, error handling, auth, test organization
2. Glob for file structure — **/*.test.*, **/routes/**, **/config/**, **/middleware/**
3. Read 5-10 representative files in key directories
4. For each gap from Phase 1: run a targeted search (Probe if available, otherwise Grep) to find current patterns
5. Use CodeGraph (codegraph_context to orient, codegraph_search → codegraph_explore for deep understanding, codegraph_callers/codegraph_files for structure) — CodeGraph is the primary exploration tool, not a fallback

Monorepo: Repeat Steps 4.1-4.3 for each sub-project identified in Phase 1. Each sub-project gets its own exploration context.

Phase 5: Compare & Identify Gaps

1. For each existing rule: still accurate? new patterns? tech stack changed? commands/paths correct?
2. Identify gaps: undocumented tribal knowledge, new conventions, changed patterns
3. AskUserQuestion to confirm findings: "Update all" | "Review each" | "Show details" | "Skip updates"

Phase 6: Sync Project Rule

Update .claude/rules/{slug}-project.md with current project state.

Also look for a legacy unscoped project.md — if found, migrate its content into {slug}-project.md and delete the old file.

Step 6.1: Handle Existing CLAUDE.md — CONDITIONAL

Only if Phase 1 found a CLAUDE.md file.

If both CLAUDE.md AND {slug}-project.md exist: merge unique content from CLAUDE.md into the project rule. If fully redundant, suggest removing CLAUDE.md.

If CLAUDE.md exists but NO {slug}-project.md: AskUserQuestion:

• "Migrate to modular rules (Recommended)" — Split into {slug}-project.md + topic-specific files. Read CLAUDE.md, identify logical sections, create rule files, confirm split before writing. Then ask: "Remove CLAUDE.md?" | "Rename to .bak" | "Keep both".
• "Keep CLAUDE.md as-is" — Skip project rule creation.
• "Create alongside" — Keep both. Project rule gets tech stack/structure, CLAUDE.md keeps custom instructions.

Step 6.2: Create or Update {slug}-project.md

If exists: compare tech stack, verify structure/commands, update timestamp, preserve custom sections. Re-read source docs while writing — every significant section in the source must have corresponding coverage in the generated rules.

If doesn't exist, create:

# Project: [Name]

**Last Updated:** [Date]

## Overview
[Brief description from README or ask user]

## Technology Stack
- **Language / Framework / Build Tool / Testing / Package Manager**

## Directory Structure
[Simplified tree — key directories only]

## Key Files
- **Configuration / Entry Points / Tests**

## Development Commands
| Task | Command |
|------|---------|
| Install / Dev / Build / Test / Lint | `[command]` |

## Architecture Notes
[Brief patterns description]

Monorepo / Multi-product: Create a root {slug}-project.md with the overall structure. Then for each product/team area, create nested directories per Phase 0 → Recommended Directory Structure:

1. Product-level: .claude/rules/{product}/{slug}-{product}-project.md — tech stack, patterns, commands specific to that product. Add paths frontmatter pointing to the product's source directories.
2. Team-level: .claude/rules/{product}/{team}/{slug}-{team}-{topic}.md — team-specific conventions. MUST have paths frontmatter.
3. Common/shared: .claude/rules/common/{slug}-common-{topic}.md — patterns for shared libraries.

Cross-reference between root and nested rules using @path/to/rule.md imports where helpful.

Step 6.3: Generate Rules README — CONDITIONAL

Only if nested directories exist (detected in Phase 1 step 5) or are being created in this sync.

Create or update .claude/rules/README.md:

# Rules Directory Structure

> Auto-generated by `/setup-rules` on [Date]. Describes how rules are organized.

## How Rules Work

Rules in `.claude/rules/` load into Claude's context each session.
Use `paths` frontmatter to scope rules to specific files — unscoped rules load every time.

## Organization

| Directory | Scope | Contents |
|-----------|-------|----------|
| `./` | Repo-wide | [List root-level rule files with one-line descriptions] |
| `./{product}/` | Product-wide | [List product rules with descriptions] |
| `./{product}/{team}/` | Team-specific | [List team rules with descriptions and their `paths` globs] |

## Adding Rules

1. Identify the narrowest scope: team > product > repo
2. Place file in the corresponding directory
3. Add `paths` frontmatter (**mandatory** for team-level, recommended for product-level)
4. Prefix filename with `{slug}-`
5. Run `/setup-rules` to validate and update this README

README rules:

• Auto-generate the table from actual files on disk — don't hardcode
• Include each rule's description (from frontmatter description field or first heading)
• For team-level rules, show the paths globs so developers know what's scoped where
• Keep the README under 80 lines — it's a navigation aid, not documentation

Phase 7: Sync MCP Rules

Document user-configured MCP servers. Skip framework-provided servers (e.g., Pilot core: context7, mem-search, web-search, web-fetch, grep-mcp) — only document servers the user added themselves.

Step 7.1: Discover

Parse .mcp.json, exclude framework-provided servers (Pilot core servers if present: context7, mem-search, web-search, web-fetch, grep-mcp).

Step 7.2: Smoke-Test

For each user server:

1. ToolSearch(query="+server-name keyword") to discover tools
2. Call 1-2 read-only tools per server as a connectivity check (safety: only read-only tools) — no need to test every tool, just confirm the server responds
3. Record per-server: ✅ connected | ⚠️ partial (note issues) | ❌ unreachable
4. Report health check:

   ✅ polar — connected, tools responding
   ⚠️ typefully — connected, 1 permission error on write tools
   ❌ my-api — connection refused
   

5. If issues: AskUserQuestion "Document working servers only" | "Document all with status notes" | "Skip MCP sync"

Step 7.3: Document

Compare against existing {slug}-mcp-servers.md. If changes detected, ask user: "Update all" | "Review each" | "Skip"

Also look for a legacy unscoped mcp-servers.md — if found, migrate content into {slug}-mcp-servers.md and delete the old file.

Step 7.4: Write

MCP tools are self-describing — Claude Code already gets tool names, descriptions, and schemas when it connects to a server. Do NOT enumerate individual tools or create per-tool tables. That information is redundant and wastes context tokens every session.

Focus on behavioral guidance — what the rules should capture is context that tool descriptions alone cannot provide: when to consult the server, how it fits into the project's workflow, and decision-making guidance.

Create/update .claude/rules/{slug}-mcp-servers.md:

## [server-name]

**Purpose:** [What this server provides — one line]
**Status:** ✅ All working | ⚠️ Partial (note which tools have issues) | ❌ Broken

**Consult this MCP when:**
- [Situation where this server should be used instead of alternatives]
- [Decision point where the server provides relevant context]
- [Workflow step where consulting this server prevents mistakes]

**Usage:** `ToolSearch(query="+server-name keyword")` then call the discovered tools directly.

Do NOT include:

• Per-tool tables (| Tool | Description |) — tools describe themselves
• Tool parameter documentation — schemas are provided by the server
• Usage examples for individual tools — Claude reads the tool schema

DO include:

• When to consult vs. when NOT to (decision boundaries)
• Project-specific workflow context (e.g., "check this before upgrading @dialpad/ deps")
• Gotchas or non-obvious behaviors specific to this project's usage
• Required env vars or auth setup if not obvious from server config

Skip if: no .mcp.json, no user-added servers, user declines.

Phase 8: Discover New Rules

1. List undocumented areas (comparing Phase 1 + Phase 4)
2. For each candidate area, find the actual patterns before drafting:

   # With Probe (preferred)
   probe search "how is [pattern] implemented across the codebase" ./ --max-results 5 --max-tokens 2000
   probe extract src/example.ts#patternFunction
   
   # Without Probe (fallback)
   # Grep(pattern="[pattern]", head_limit=10)
   # Read representative files directly
   

3. Prioritize by: frequency, uniqueness, mistake likelihood
4. AskUserQuestion (multiSelect): which areas to document
5. For each: ask clarifying questions, draft rule using search results and code examples, confirm before creating
6. Place in correct directory based on scope:
   • Repo-wide → .claude/rules/{slug}-{pattern-name}.md
   • Product-specific → .claude/rules/{product}/{slug}-{product}-{pattern-name}.md (add paths frontmatter)
   • Team-specific → .claude/rules/{product}/{team}/{slug}-{team}-{pattern-name}.md (must have paths frontmatter)
   • If nested directories exist (from Phase 1), always ask which scope level the rule belongs to
   • Create product/team directories as needed (mkdir -p)

Rule format: Standard Name → When to Apply → The Pattern (code examples) → Why (if not obvious) → Common Mistakes → Good/Bad examples.

Phase 9: Cross-Check

Re-read all generated/updated files and verify against source docs and each other.

1. Build entity index — collect all services, entry points, modules, config keys, and enum values mentioned across generated files
2. Cross-file completeness — for each entity, verify it appears in all related files (e.g., a service in {slug}-deployment.md must also be in {slug}-architecture.md and {slug}-project.md)
3. Source fidelity — for each identifier in generated rules, search source docs (Probe if available, otherwise Grep) to confirm exact spelling. If spelling differs between source and generated rule, fix the rule to match the source verbatim
4. Section coverage — for each significant section in source docs (CLAUDE.md, docs/), confirm a corresponding rule section exists
5. Reference validity — cross-references between files point to files that actually exist
6. README currency — if .claude/rules/README.md exists, verify it lists all current rule files and directories. Update if stale.
7. Path-scoping enforcement — re-verify all team-level rules have paths frontmatter (final check)

Auto-fix any issues found. Report fixes in summary.

Phase 10: Summary

Report:

• Directory structure: flat | nested (list products/teams)
• README: created | updated | not needed (flat structure)
• Quality audit: errors fixed, warnings addressed, suggestions applied, skipped
• Rules: created, updated, unchanged (by directory level)
• Path-scoping: team rules validated, violations fixed
• Cross-check: issues found and fixed (if any)
• Probe: available / not available

Then offer: "Share via Share dashboard" (direct user to Console Share page at #/share) | "Discover more standards" | "Create skills with /create-skill" | "Done"