# For Developers

You cloned the repo. You want to understand the dispatch model, add a component, or ship a change. This is the map.

## Architecture in 60 Seconds

The system has one path. Every request passes through four layers.

```
User request → Router (/do) → Agent (*.md) → Skill (SKILL.md) → Script (*.py)
```

The router classifies intent. It selects an agent and pairs it with a skill when the task type demands methodology. Agents carry domain knowledge. Skills carry workflow structure. Scripts do mechanical work where you want deterministic behavior, not judgment calls. Hooks fire at lifecycle events to inject context, learn from errors, and enforce gates.

This is the entire execution model. There is nothing else.

## Directory Structure

```
agents/              Domain experts. One .md per agent, optional references/ subdirectory
  INDEX.json         Generated routing index (don't hand-edit)

skills/              Workflow methodologies. One directory per skill, each with SKILL.md
  INDEX.json         Generated skill index

hooks/               Event-driven Python scripts. Fire on lifecycle events
  lib/               Shared utilities (hook_utils.py, learning_db_v2.py, feedback_tracker.py)
  tests/             Hook-specific tests

scripts/             Deterministic CLI tools. Python scripts for mechanical operations
  tests/             Script-specific tests

commands/            Slash command definitions

templates/           Scaffolding templates for new components

adr/                 Architecture Decision Records (gitignored, local working documents)
```

Three things the listing does not communicate. INDEX.json files in `agents/` and `skills/` are generated by scripts (`scripts/generate-agent-index.py`, `scripts/generate-skill-index.py`). Hooks import shared code from `hooks/lib/`, never from each other. The eval system spans two locations: `skills/meta/skill-eval/` for methodology, `scripts/skill_eval/` for runner scripts.

### Private Skills

Skills you write but keep out of the public repo. Create a separate private git repository at `~/private-skills/` using the same category structure:

```
~/private-skills/
├── content/
│   └── my-custom-skill/
│       ├── SKILL.md
│       └── references/
├── engineering/
│   └── internal-tool/
│       ├── SKILL.md
│       └── references/
```

The sync hook discovers `~/private-skills/` automatically — any directory with a SKILL.md inside a category folder gets deployed to `~/.claude/skills/` alongside public skills. No configuration needed.

**Setup:**

```bash
mkdir -p ~/private-skills
cd ~/private-skills
git init
# Create your category/skill/SKILL.md structure
git add -A && git commit -m "initial private skills"
# Optional: push to a private GitHub repo
gh repo create my-private-skills --private --source=. --push
```

**How it works:**

| What you do | What happens |
|---|---|
| Create `~/private-skills/content/my-skill/SKILL.md` | Sync deploys it as `~/.claude/skills/my-skill` |
| Create `~/private-skills/engineering/my-tool/SKILL.md` | Sync deploys it as `~/.claude/skills/my-tool` |
| Delete a skill directory | Next sync removes it from `~/.claude/skills/` |

Skills in `~/private-skills/` follow the same conventions as public skills: YAML frontmatter, workflow phases, reference files. The sync hook runs on every session start, so new private skills are available immediately.

## Creating Components

Tell `/do` what you want. Describe the domain and purpose. The creator agent handles structure, registration, and routing integration.

### Agents

```
/do create an agent for [your domain]
```

Example prompts:
- `/do create an agent for Terraform infrastructure management that knows HCL, state management, and module patterns`
- `/do create an agent for Redis caching that specializes in data structures, eviction policies, and cluster management`

### Skills

```
/do create a skill for [your workflow]
```

Example prompts:
- `/do create a skill for database migration safety with pre-migration checks, rollback validation, and post-migration verification`
- `/do create a skill for API contract testing that validates OpenAPI specs against implementation`

### Hooks

```
/do create a hook for [your purpose]
```

Example prompts:
- `/do create a hook that warns when test files are modified without updating test fixtures`
- `/do create a PostToolUse hook that detects when a git merge conflict marker is written to a file`

## Key Architecture Points

The constraint that governs all component design: each type has exactly one job.

- **Agents** (`agents/*.md`) know *what* to do. Domain expertise, patterns, failure modes.
- **Skills** (`skills/*/*/SKILL.md`) know *how* to structure work. Phases, gates, methodology.
- **Hooks** (`hooks/*.py`) respond to *events*. JSON in, JSON out, 50ms budget.
- **Scripts** (`scripts/*.py`) perform *deterministic* operations. Indexing, validation, linting.

If a process is mechanical and measurable, it belongs in a script. If it requires contextual judgment, it belongs in an agent or skill. The boundary is not negotiable.

The `/do` router connects everything. After creating any component, test routing:

```
/do [request that should trigger your new component]
```

## PR Workflow

The full cycle, in order:

1. **Branch** from main (`feature/`, `fix/`, `refactor/` prefix)
2. **Implement** changes
3. **Wave review** via parallel reviewer agents
4. **Fix** findings (up to 3 review-fix iterations)
5. **Retro** captures learnings into the learning database
6. **Graduate** validated learnings into agent/skill files
7. **Commit** in conventional format
8. **Push** to remote with tracking
9. **PR** creation via `gh pr create`
10. **CI** must pass
11. **Merge** after CI and human review

The `pr-workflow` skill automates steps 3 through 10.

## Testing

Framework: pytest.

```bash
pytest -v                            # all tests
pytest hooks/tests/ -v               # hook tests
pytest scripts/tests/ -v             # script tests
pytest hooks/tests/test_learning_system.py -v   # single file
```

What to test by component type:

| Component | Approach |
|-----------|----------|
| Hooks | Feed JSON input, assert JSON output. Test happy path and silent path. Mock external deps. |
| Scripts | Test CLI interface. Deterministic: input X always produces output Y. |
| Agents/Skills | Use `skills/meta/skill-eval/` methodology and `scripts/skill_eval/` runner for quality assessment. |

Fixtures: `scripts/tests/fixtures/` for script test data. Hook tests inline their fixtures.

## Key Conventions

**Conventional commits.** `type(scope): description`. Types: feat, fix, refactor, docs, test, chore. Focus on what and why.

**No AI attribution.** Omit "Generated with Claude Code" and co-author lines from all commits.

**Branch safety.** Create feature branches for all work. The `pretool-branch-safety.py` hook enforces this by blocking commits to protected branches.

**Wabi-sabi in docs.** Sentence fragments where they're clear. Varied length. No "delve", "leverage", "comprehensive", "robust", "streamline", "empower." The `scripts/scan-ai-patterns.py` script catches these.

**INDEX.json is generated.** Run the generation scripts. They parse frontmatter and build the index. Hand-edits get overwritten.

**Hooks live in hooks/.** Write there. The sync hook deploys to `~/.claude/hooks/` on session start.

**Scripts are deterministic.** No LLM calls. No judgment. If it involves reasoning, it is an agent or skill.

**50ms hook budget.** Hooks fire on every tool call or prompt. Keep them fast. Profile with `scripts/benchmark-hooks.py` if uncertain.
