# Customization Guide

How to adapt this workflow for your own projects.

## Start With Core (This Is All Most Projects Need)

The core practices run without any `.claude/rules/` files. They're the actual daily workflow:

### 1. Install the Superpowers plugin
```bash
claude plugin install superpowers
```

This gives you: brainstorming before building, TDD enforcement, systematic debugging, verification before completion, code review, and implementation planning. It's the workflow engine.

### 2. Set up the document hierarchy
```bash
cp templates/CLAUDE.md ./CLAUDE.md    # Fill in project state and architecture
cp templates/SESSION.md ./SESSION.md  # AI memory, grows over time
```

Add `CONTEXT.md` if you have infrastructure details. Add `IDEA.md` for new projects.

### 3. Add backup-before-edit to your global instructions
In `~/.claude/CLAUDE.md`:
```
Before editing any file, back up the original to a .backup/ directory.
```

### 4. Install the pre-push hook
```bash
cp hooks/check-secrets-before-push.sh ~/.config/git/check-secrets-before-push.sh
chmod +x ~/.config/git/check-secrets-before-push.sh
```

Add to Claude Code settings (see `settings/settings.example.json`).

### 5. Let the memory system do its job

As you work, correct the AI when it does something wrong. Confirm when it does something right in a non-obvious way. These corrections and confirmations persist as feedback memories that improve behavior over time.

**That's it.** This is the actual workflow for 25 out of 26 projects. The Superpowers plugin enforces the process, the documents provide continuity, the memory system learns, the hook catches secrets.

## When to Add Advanced Rules

Add `.claude/rules/` files when you notice:

- **Convention drift** — Different sessions make inconsistent decisions because there's no explicit standard
- **Onboarding friction** — New contributors (or new AI sessions) take too long to understand how this project works
- **Expensive mistakes** — The project touches production systems where errors have real consequences
- **Multi-domain complexity** — The project spans ML + infrastructure + frontend + deployment and context switching causes errors
- **Session handoff problems** — Multi-session work loses important context despite SESSION.md

### Adding Rules Incrementally

Don't install all 9 rules at once. Add what you need:

**First:** Session discipline + git workflow
```bash
mkdir -p .claude/rules
cp rules/01-session-discipline.md .claude/rules/
cp rules/03-git-workflow.md .claude/rules/
```

These formalize the session start/end protocol and git conventions that the core practices handle implicitly.

**Then:** Reasoning patterns + code quality (if decisions need more rigor)
```bash
cp rules/05-reasoning-patterns.md .claude/rules/
cp rules/08-code-quality.md .claude/rules/
```

**Then:** Proactive steering + context management (if the AI needs to be more autonomous)
```bash
cp rules/04-proactive-steering.md .claude/rules/
cp rules/06-context-management.md .claude/rules/
```

**Then:** Security hardening + authority hierarchy (if the project is security-sensitive or has conflicting guidance)
```bash
cp rules/07-security-hardening.md .claude/rules/
cp rules/02-authority-hierarchy.md .claude/rules/
```

## Customizing Core Practices

### Document hierarchy
- Adjust the CLAUDE.md template to match your project's shape
- Some projects don't need CONTEXT.md (no infrastructure)
- Some projects don't need IDEA.md (existing codebase, no "original intent" to capture)

### Superpowers plugin
- TDD enforcement can be overridden per-request ("skip tests this time" — requires explicit acknowledgment)
- Brainstorming depth scales with task complexity (simple tasks get lighter treatment)
- The plugin is configurable — check its documentation for options

### Memory system
- Review feedback memories periodically — some become outdated
- User memories help the AI tailor explanations to your expertise level
- Project memories capture context that isn't in code or git history

### Commit conventions
- Conventional commits (`feat:`, `fix:`, etc.) are the default but not mandatory
- The core principle is: one logical change per commit, push immediately
- Adapt the types to your team's vocabulary if needed

## Customizing Advanced Rules

### Session discipline (01)
Adapt: The wrap-up questions. Your team might check different things at session end.
Keep: Persisting decisions to files. This is foundational.

### Git workflow (03)
Adapt: Branch naming conventions to match your team.
Keep: Frequent commits and conventional format.

### Proactive steering (04)
Adapt: Phase names to match your team's vocabulary.
Keep: Ending every response with direction.

### Reasoning patterns (05)
Adapt: Documentation lookup tiers to match your tools.
Keep: Clarification before assumption, brainstorm before building.

### Context management (06)
Adapt: Token budget numbers for your AI assistant's context window.
Keep: The execution readiness check.

### Security (07)
Adapt: Deny list patterns for your infrastructure.
Keep: Prompt injection guardrails.

## Removing Things

If a core practice doesn't fit:
- Don't install the Superpowers plugin → brainstorming/TDD become suggestions, not enforced
- Don't use SESSION.md → lose session continuity (not recommended)
- Don't install the pre-push hook → rely on `.gitignore` alone for secret prevention

If an advanced rule doesn't fit:
- Simply don't copy it to `.claude/rules/`. The remaining rules work independently.
- Exception: if you remove `02-authority-hierarchy.md`, conflicts between rules and plugins won't have a clear resolution. Consider keeping it even if simplified.

## Team Adoption

1. Start with core practices only across all projects
2. Standardize the CLAUDE.md format so anyone's AI can pick up any project
3. Let the memory system accumulate team-specific feedback organically
4. Add advanced rules only to projects that demonstrably need them
5. Review rules quarterly — remove any that aren't preventing real problems