# Tool Patterns Catalog

Patterns for building robust, self-correcting Claude Code tools (skills, agents, commands).

## Pattern Summary

| Pattern | Purpose | When to Use |
|---------|---------|-------------|
| [Audit](audit-pattern.md) | Smart implicit audits | Modifying existing tools, vague requests |
| [Verification](verification-pattern.md) | Mandatory completion checks | Before claiming any work complete |
| [Brainstorming](brainstorming-pattern.md) | Design decision refinement | Design decisions, new concepts |
| [Reversion Protection](reversion-protection.md) | Prevent behavior regression | All tools with defined behaviors |
| [Decisions Record](decisions-record.md) | Capture audit decisions | During any audit workflow |
| [Deterministic Scripting](deterministic-scripting.md) | Shift mechanical work to scripts | Planning/design, identifying automation |
| [Adaptive Verbosity](adaptive-verbosity.md) | Scale output to complexity | Skills with variable complexity (simple to complex scenarios) |
| [Role-Workflow](role-workflow-pattern.md) | Multi-workflow orchestration | Plugins with 2+ subagent workflows needing synthesis |

## Quick Decision Guide

**Starting a new tool?**
1. Brainstorm the design first (if non-trivial)
2. If orchestrating 2+ subagent workflows with synthesis → use Role-Workflow pattern
3. Identify scripting opportunities (mechanical, repeatable tasks)
4. Define invariants and golden examples (reversion protection)
5. Build with verification hooks

**Modifying an existing tool?**
1. Check for prior decisions (`.decisions/`)
2. Run implicit audit before changes
3. Verify against golden examples
4. Record any new decisions made

**Reviewing a tool?**
1. Run audit workflow
2. Record decisions made
3. Update golden examples if behavior changes were intentional

**During planning/design?**
1. For each component, ask: "Is this mechanical, repeatable, and unambiguous?"
2. If yes → recommend a script (see deterministic-scripting pattern)
3. Choose language based on project context

## Integration Points

These patterns work together:

```
Brainstorming ──→ Design decisions captured
        │
        ↓
    Planning ──→ Script opportunities identified
        │        Multi-workflow orchestration? → Role-Workflow pattern
        ↓
    Building ──→ Invariants + golden examples defined
        │        Scripts implement mechanical tasks
        │        Role-Workflow: Task files + dispatch structure
        ↓
   Modifying ──→ Audit runs implicitly
        │        │
        │        ↓
        │   Decisions recorded
        │        │
        ↓        ↓
 Verification ──→ Golden examples checked
                 Scripts provide deterministic evidence
                 Role-Workflow: Synthesis step verifies completeness
```

## Model Guidance

| Pattern | Recommended Model |
|---------|-------------------|
| Audit execution - structure | Haiku |
| Audit execution - content/quality | Opus |
| Decision recording | Haiku |
| Brainstorming | Opus |
| Verification | Haiku |
| Golden example comparison | Opus |
| Role-Workflow - research | Haiku |
| Role-Workflow - processing | Sonnet |
| Role-Workflow - judgment | Opus |
| Cleanup | Haiku |