# Component Mapping Reference

Detailed decision logic for mapping patterns to Claude Code components.

## Decision Tree

```text
START: Pattern Identified
    │
    ├── USER-INVOKED?
    │   │
    │   ├── YES → Requires domain expertise throughout?
    │   │         │
    │   │         ├── YES → AGENT
    │   │         │         (specialized system prompt, deep knowledge)
    │   │         │
    │   │         └── NO → Fully automatable?
    │   │                   │
    │   │                   ├── YES → COMMAND
    │   │                   │         (script-based, deterministic)
    │   │                   │
    │   │                   └── NO → SKILL
    │   │                             (structured guidance, judgment needed)
    │   │
    │   └── NO (EVENT-TRIGGERED) → Modifies behavior?
    │                               │
    │                               ├── YES → HOOK
    │                               │         (can block/augment operations)
    │                               │
    │                               └── NO → Question if needed
```

## Examples by Decision Path

<example name="tdd-workflow">
Path: User-invoked → No domain expertise → Not fully automatable → **SKILL**

Why not COMMAND: Requires judgment on test design, refactoring decisions
Why not AGENT: General software practice, not specialized domain

Composite: Add `/run-tdd-cycle` COMMAND for mechanical test execution
</example>

<example name="security-audit">
Path: User-invoked → Requires domain expertise → **AGENT**

Why AGENT: Security requires deep specialized knowledge for every decision
Why not SKILL: Can't encode all security judgment in progressive disclosure

Composite: AGENT can use vulnerability-scanning SKILL, `/check-deps` COMMAND
</example>

<example name="code-formatting">
Path: User-invoked → No expertise → Fully automatable → **COMMAND**

Why COMMAND: Deterministic, rule-based, no judgment needed
Why not SKILL: No guidance needed, just run the tool

Composite: Add pre-commit HOOK for automatic formatting
</example>

<example name="pre-commit-validation">
Path: Event-triggered → Modifies behavior → **HOOK**

Why HOOK: Automatically runs on git event, can block commit
Implementation: `pre-commit` hook runs validation script
</example>

<example name="git-linear-integration">
Path: Event-triggered → Modifies behavior → **HOOK**

Why HOOK: Triggered by commit, augments with Linear updates
No user action required, happens in normal git workflow
</example>

## Edge Cases

### Manual + Automated

Running tests: both manual and CI use cases

```text
COMMAND: /run-tests
  User-invoked, allows parameters (--watch, --coverage)

HOOK: pre-push
  Automatically runs tests, blocks on failure
  Calls same script as COMMAND
```

### Guidance + Enforcement

PR size limits: suggest vs block

```text
SKILL: pr-workflow
  Provides guidance on optimal size
  Helps plan PR stack structure

HOOK: pre-push (optional)
  Warns or blocks on threshold
  User configures hard vs soft limit
```

### Encodable Expertise

TypeScript type design: expert knowledge that can be captured

```text
SKILL (not AGENT) because:
  - Don't need specialized prompt for every decision
  - Expertise can be progressively disclosed
  - Works in general engineering context

Use AGENT when:
  - Type-level programming (mapped, conditional, template types)
  - Designing complex type system for library
  - Every interaction requires type theory
```

### Mixed Automation

Feature development: some steps automatable, some need judgment

```text
SKILL: feature-development
  Overall workflow guidance
  Design decisions, quality criteria

COMMANDs orchestrated by SKILL:
  - /create-feature-branch
  - /run-tests
  - /generate-pr-description
```

## Selection Matrix

| Criteria | Skill | Command | Agent | Hook |
|----------|-------|---------|-------|------|
| User-invoked | ✓ | ✓ | ✓ | ✗ |
| Event-triggered | ✗ | ✗ | ✗ | ✓ |
| Requires judgment | ✓ | ✗ | ✓ | ✗ |
| Fully automatable | ✗ | ✓ | ✗ | ✓ |
| Domain expertise | ✗ | ✗ | ✓ | ✗ |
| Progressive disclosure | ✓ | ✗ | rarely | ✗ |
| Can block operations | ✗ | can fail | ✗ | ✓ (pre-*) |

## Composite Patterns

**SKILL + COMMAND**: Workflow has guidance + automation needs
- SKILL provides strategy, COMMAND handles execution
- Example: TDD skill + `/run-tests`

**SKILL + HOOK**: Guidance reinforced with automated checks
- SKILL teaches best practices, HOOK enforces them
- Example: PR workflow + pre-push size validation

**AGENT + SKILL**: Expert needs extended capabilities
- AGENT embodies expertise, SKILLs extend it
- Example: Security agent + vulnerability scanning skill

**COMMAND + HOOK**: Same operation, manual and automatic
- COMMAND for manual, HOOK for automation
- Example: `/format-code` + pre-commit format hook

**Multi-component (SKILL + COMMAND + HOOK)**: Complete workflow
- SKILL guides, COMMAND automates, HOOK enforces
- Example: Testing (strategy skill + /run-tests + pre-push coverage)

## Common Mistakes

**Creating AGENT for non-expert work**

```text
✗ file-organizer-agent
✓ COMMAND for organization, SKILL for strategy
```

**Using SKILL when COMMAND suffices**

```text
✗ run-prettier-skill (no guidance needed)
✓ COMMAND /format
```

**Creating HOOK for user-driven action**

```text
✗ on-user-request hook
✓ COMMAND or SKILL
```

**Encoding expertise in COMMAND**

```text
✗ grep-based security check
✓ AGENT for real review, or external scanning tool
```

**Over-compositing**

```text
✗ SKILL + COMMAND + HOOK + AGENT for simple linting
✓ COMMAND, optionally HOOK for pre-commit
```

## Decision Checklist

1. **Invocation**: How triggered?
   - User request → SKILL/COMMAND/AGENT
   - Event → HOOK
   - Both → COMMAND + HOOK

2. **Automation**: Fully automatable?
   - Yes, no judgment → COMMAND
   - No, requires decisions → SKILL or AGENT

3. **Expertise**: Specialized domain knowledge?
   - Yes, for every step → AGENT
   - Yes, but encodable → SKILL
   - No → SKILL or COMMAND

4. **Behavior**: Modifies agent behavior or enforces rules?
   - Yes (event-triggered) → HOOK
   - No → SKILL/COMMAND/AGENT

5. **Value**: Saves time or reduces errors?
   - Yes → Worth capturing
   - Marginal → Question if needed
   - No → Don't create component