manage-agent-instructions

<essential_principles>
## Core Principles

These principles apply to ALL agent instruction files (CLAUDE.md, AGENTS.md).

### 1. Minimal Root File

The root instruction file should be as small as possible. Every token loads on every request regardless of relevance.

**Absolute minimum content:**
- One-sentence project description (acts as role prompt)
- Package manager (if not npm)
- Non-standard build/test commands

Everything else belongs in progressive disclosure files.

### 2. Progressive Disclosure

Agents navigate documentation hierarchies efficiently. Structure knowledge in layers:

```
Level 1: Root file (~100-300 words)
Level 2: docs/CONVENTIONS.md, docs/TYPESCRIPT.md, etc.
Level 3: Nested references within those files
```

Load context only when needed for the current task.

### 3. Describe Capabilities, Not Paths

File paths change constantly. Documentation that says "auth logic lives in src/auth/handlers.ts" becomes stale and poisons context.

Instead: "Authentication is handled by the AuthService module" and let the agent discover current paths.

Domain concepts (organization vs workspace vs group) are more stable than file paths.

### 4. No Instruction Bloat

Avoid the feedback loop:
1. Agent does something wrong
2. Add rule to prevent it
3. Repeat hundreds of times
4. File becomes unmaintainable "ball of mud"

Curate ruthlessly. Remove:
- Redundant instructions (agent already knows)
- Vague guidance ("write clean code")
- Contradicting rules
- Auto-generated boilerplate

### 5. Tool-Specific Files

Claude Code uses CLAUDE.md, not AGENTS.md. For multi-tool support:

```bash
# Option A: Symlink (both tools read same content)
ln -s AGENTS.md CLAUDE.md

# Option B: Redirect (AGENTS.md points to CLAUDE.md)
# AGENTS.md content: "See CLAUDE.md for instructions"
```

### 6. Monorepo Strategy

Nested instruction files merge with root level:

| Level | Content |
|-------|---------|
| Root | Monorepo purpose, navigation, shared tools |
| Package | Package purpos