# Customization Guide

How to adapt this workflow for your own projects.

## Start Small

You don't need to adopt everything at once. Here's a recommended progression:

### Level 1: Essentials (Start Here)
```
.claude/rules/
  01-session-discipline.md    # Session start/end protocol
  03-git-workflow.md           # Conventional commits, branches
  09-context-doc-maintenance.md # Keep docs current
```

Plus the templates:
- `CLAUDE.md` -- project instructions
- `SESSION.md` -- AI memory across sessions

This gives you: session continuity, clean git history, and documentation that stays current.

### Level 2: Quality
Add:
```
.claude/rules/
  05-reasoning-patterns.md    # Brainstorm before building, Five Whys
  08-code-quality.md           # Quality checklist, immutability
```

This gives you: better architectural decisions, fewer bugs, and consistent code quality.

### Level 3: Sophisticated AI Assistance
Add:
```
.claude/rules/
  02-authority-hierarchy.md    # What overrides what
  04-proactive-steering.md     # AI as co-pilot, not passive tool
  06-context-management.md     # Token budgets, session management
```

This gives you: an AI assistant that actively steers the project, manages its own context, and follows a clear authority hierarchy.

### Level 4: Security Hardening
Add:
```
.claude/rules/
  07-security-hardening.md     # Deny lists, injection guards
```

Plus the pre-push hook:
```bash
cp hooks/check-secrets-before-push.sh ~/.config/git/check-secrets-before-push.sh
```

This gives you: secret scanning, file access restrictions, and prompt injection awareness.

## Customizing Individual Rules

### Session Discipline (01)

**Adapt:** The session wrap-up questions. Your team might have different things to check at session end. The handoff document format might need project-specific sections.

**Don't remove:** The principle of persisting decisions to files. This is the foundation of session continuity.

### Git Workflow (03)

**Adapt:** Branch naming conventions to match your team's standard. Commit types if you use a different convention than conventional commits.

**Don't remove:** Frequent commits and conventional format. These create searchable, revertible history.

### Proactive Steering (04)

**Adapt:** The phase names (IDEATION, PLANNING, etc.) to match your team's vocabulary. The auto-invoke tool signals to match your toolchain.

**Don't remove:** The principle of ending every response with direction. This prevents "what now?" dead ends.

### Reasoning Patterns (05)

**Adapt:** The documentation lookup tiers to match your documentation tools. The Adopt/Extend/Compose/Build thresholds based on your project's tolerance for dependencies.

**Don't remove:** Clarification before assumption and brainstorm before building. These prevent wasted work.

### Context Management (06)

**Adapt:** The token budget numbers based on your AI assistant's context window. The thinking mode names to match your tool's syntax.

**Don't remove:** The execution readiness check. Starting 3+ tasks at high context usage compounds errors.

### Security (07)

**Adapt:** The deny list patterns to match your infrastructure. Add paths specific to your cloud provider, secrets manager, etc.

**Don't remove:** The prompt injection guardrails. External content is always untrusted input.

## Adding Project-Specific Rules

Create additional rules in `.claude/rules/` with higher numbers:

```
.claude/rules/
  10-api-conventions.md        # Your API design standards
  11-testing-requirements.md   # Your testing requirements
  12-deployment-process.md     # Your deployment workflow
```

Higher numbers load after lower numbers. Project-specific rules can reference the base rules:

```markdown
# API Conventions

In addition to the quality standards in `08-code-quality.md`:

- All endpoints must return JSON
- All errors must use RFC 7807 format
- All endpoints must have OpenAPI documentation
```

## Removing Rules

If a rule doesn't fit your workflow, simply don't copy it to `.claude/rules/`. The remaining rules continue to work independently.

**Caveat:** If you remove `02-authority-hierarchy.md`, be aware that conflicts between rules, plugins, and defaults won't have a clear resolution order. Consider keeping it even if simplified.

## Team Adoption

For teams adopting this workflow:

1. **Start with Level 1** across all projects
2. **Standardize CLAUDE.md format** so any team member's AI assistant can pick up any project
3. **Share SESSION.md conventions** so session memories are consistently structured
4. **Discuss which rules to add** based on the team's pain points
5. **Customize rule content** to match team conventions, but keep the rule structure

The templates in `templates/` are starting points. Evolve them as your team discovers what works.

## Measuring Success

You'll know the workflow is working when:
- New sessions start productive immediately (no "where was I?")
- Decisions made last week are documented and discoverable
- The AI suggests next steps you agree with (proactive steering is calibrated)
- No secrets are committed (security rules are working)
- Git history tells a clear story (conventional commits + frequent commits)
- Context doesn't degrade in long sessions (context management is working)