# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Repository Overview

This is the **Outfitter Marketplace** - a collection of Claude Code plugins for developers. The repository hosts multiple plugins that can be installed individually.

## Commands

### Plugin installation (via Claude Code)

```bash
/plugin marketplace add outfitter-dev/agents  # Add marketplace
/plugin install <plugin-name>@outfitter       # Install a plugin
```

## Architecture

### Plugin Structure

Each plugin lives in the `plugins/` directory:

```
plugins/
├── <plugin-name>/
│   ├── agents/           # Custom agents (markdown files)
│   ├── commands/         # Slash commands (markdown files)
│   ├── skills/           # Skills with SKILL.md entry points
│   ├── hooks/            # Event hooks (TypeScript for complex logic)
│   └── README.md
```

Plugin metadata is consolidated in `.claude-plugin/marketplace.json` (no individual plugin.json files needed).

### Available Plugins

| Plugin | Purpose |
|--------|---------|
| **outfitter** | Core methodology + Claude Code extensibility (TDD, debugging, architecture, research, plugins, skills, agents) |
| **but** | GitButler virtual branch workflows for parallel development |
| **gt** | Graphite stacked PR workflows for trunk-based development |
| **cli-dev** | CLI development: argument parsing, help text, subcommands |
| **outfitter-stack** | Outfitter Stack patterns: Result types, handler contract, error taxonomy |

## Working with Skills

Skills are markdown-based instruction sets that guide agent behavior for specific tasks.

### Finding Skills

| Plugin | Path | Contains |
|--------|------|----------|
| outfitter | `plugins/outfitter/skills/` | TDD, debugging, pathfinding, plugin authoring, skills-discovery, skills-workflows |
| outfitter-stack | `plugins/outfitter-stack/skills/` | Stack patterns, templates, review, audit, architecture |
| but | `plugins/but/skills/` | GitButler virtual branch workflows |
| gt | `plugins/gt/skills/` | Graphite stacked PR workflows |
| cli-dev | `plugins/cli-dev/skills/` | CLI development patterns |

### Notable Agents

| Plugin | Agent | Purpose |
|--------|-------|---------|
| outfitter | `workflow-architect` | Design multi-skill workflow systems |
| outfitter | `plugin-engineer` | Transform external repos into plugins |
| outfitter-stack | `stacker` | Stack-specialist for @outfitter/* patterns |

```bash
# List all skills
find . -name "SKILL.md" -not -path "*/node_modules/*"
```

### Loading Skills into Context

To use a skill, read the `SKILL.md` file into context. Skills use **progressive disclosure**:

| Step | File | Contains |
|------|------|----------|
| 1. Core | `SKILL.md` | YAML frontmatter + workflow |
| 2. Deep-dive | `references/*.md` | Detailed patterns, edge cases |
| 3. Examples | `examples/` or `EXAMPLES.md` | Concrete worked patterns |

```bash
# Example: load the pathfinding skill
cat plugins/outfitter/skills/pathfinding/SKILL.md

# If you need more detail on confidence levels
cat plugins/outfitter/skills/pathfinding/references/confidence.md
```

### Skill Anatomy

```markdown
---
name: Skill Name
version: 1.0.0
description: When to use this skill, trigger keywords
---

# Skill Name

<when_to_use>
Conditions that should trigger this skill
</when_to_use>

<workflow>
Step-by-step process
</workflow>

<rules>
ALWAYS: mandatory behaviors
NEVER: prohibited actions
</rules>

<references>
Links to supporting docs
</references>
```

### Formatting Conventions

Skills and output should follow `.claude/rules/FORMATTING.md`:
- Use Unicode indicators (`░▓` for progress, `◇◆` for severity, `△` for caveats)
- Variables in `{ALL_CAPS}`, instructional prose in `{ lowercase with spaces }`
- XML tags for structural sections (`<workflow>`, `<rules>`, etc.)
- Avoid markdown emphasis in instructions; save it for user-facing output

## Marketplace Configuration

The root `.claude-plugin/marketplace.json` defines available plugins with source locations and metadata. Local plugins use explicit `./plugins/<name>` paths in source fields (schema requires `./` prefix for relative paths). External plugins reference GitHub repos.

## Conventions

| Tool | Purpose |
|------|---------|
| Bun | Runtime and package manager |
| Biome | Linting and formatting |
| `.claude/rules/FORMATTING.md` | Skill output formatting conventions |