optimize-agent-docs

# Agent Knowledge Optimizer

Transform accumulated documentation into a retrieval-optimized knowledge system.

## Core Principle

File organization is a human concern. Agents don't browse—they search and load. Optimize for:
- **Discovery**: What knowledge exists?
- **Relevance**: Is it needed for this task?
- **Efficiency**: What's the minimum to load?

## Workflow

### Phase 1: Knowledge Extraction

Inventory all agent documentation:

```bash
# Find all agent doc sources
find . -maxdepth 2 -name "*.md" -path "*/.claude/*" -o \
       -name "*.md" -path "*/.codex/*" -o \
       -name "*.md" -path "*/.cursor/*" -o \
       -name "CLAUDE.md" -o -name "AGENTS.md" -o -name "INSTRUCTIONS.md"
```

For each file, extract:
- Discrete facts (single pieces of actionable information)
- Instructions (procedures, rules, constraints)
- Context triggers (when is this knowledge needed?)

### Phase 2: Chunk Analysis

Break content into **retrieval units**—the smallest self-contained piece of information that makes sense alone.

Good chunk:
```
## Adding API Endpoints
1. Create handler in src/handlers/
2. Register route in src/routes.rs
3. Add OpenAPI spec to docs/api.yaml
```

Bad chunk (too coupled):
```
See the API section for endpoint patterns, but first read the auth docs,
which reference the middleware guide...
```

Score each chunk:
- **Self-contained?** Can agent act on this without loading more?
- **Task-specific?** Clear when this is needed?
- **Information-dense?** High signal per token?

### Phase 3: Build Knowledge Manifest

Generate `.claude/KNOWLEDGE.md`—a lightweight index the agent reads first:

```markdown
# Knowledge Manifest

## Task → Knowledge Map

| When working on... | Load | Key terms |
|-------------------|------|-----------|
| API endpoints | references/api.md | route, handler, endpoint |
| Authentication | references/auth.md | token, session, login |
| Database changes | references/schema.md | migration, model, query |
| Testing | references/testing.md | s