---
name: context-dependency-graph
description: Break project context into a dependency graph of focused markdown files. Each agent reads only what its task requires — never a monolith dump. Source: Alja, Director of Engineering, Elephant.
version: 1.0.0
metadata:
  filePattern: "**/*.md"
priority: 88
---

# Context Dependency Graph

## Core Principle
Never dump all context into one prompt. Map context as a directed dependency graph.
Each agent or task declares exactly which files it needs — nothing more.
AI has PhD-level skills but zero experience — YOU provide the experience via targeted context.

## Standard File Map

| File | Who Reads It |
|------|-------------|
| `PRD.md` | PM agent, planning agent, solutions agent |
| `design-system.md` | Front-end agent ONLY |
| `api-contract.md` | Front-end agent + back-end agent |
| `db-schema.md` | Back-end agent + migration agent ONLY |
| `adr/*.md` | ALL agents (read-only, never modify) |
| `research/*.md` | Planning agent, implementing agent |
| `CLAUDE.md` | Primary orchestrator agent ONLY |

## Rules

1. **Declare dependencies explicitly** — every skill/task states which files it reads
2. **Front-end agents MUST NOT receive `db-schema.md`** — they don't need it
3. **`adr/*.md` is read-only** for all agents — ADRs are immutable
4. **When a context file grows beyond 400 lines** → split into two focused files, update the map
5. **CLAUDE.md is for orchestration rules only** — not a dumping ground for all docs
6. **Skills are stack-agnostic** — never hardcode tech stack references in skills

## When Building a New Feature

1. Identify which context files are relevant to this task
2. Declare them explicitly at the top of your task or skill
3. Load ONLY those files
4. If a required file doesn't exist yet → create it before starting work

## Decision Matrix: Which Files to Load

| Task | Load |
|------|------|
| UI component | design-system.md, api-contract.md |
| API endpoint | api-contract.md, db-schema.md |
| Database migration | db-schema.md, adr/*.md |
| New feature planning | PRD.md, adr/*.md, research/*.md |
| Architecture review | adr/*.md, architectural-doc.md |
| Onboarding new engineer | adr/*.md (start here, always) |

## Skill-as-Code Rules

Treat skills like production software:
- **Refactor** when output quality drifts (not the prompt — the skill)
- **Version** skills (`version: 1.0.0` in frontmatter, bump on changes)
- **Template** outputs so results are deterministic
- **Vet** every skill sourced externally before adopting (generate from source → review)
- **Measure** token cost per task — high cost = skill needs refactoring

## Skill Refactoring Loop

```
Measure output quality
    ↓
Identify drift (outputs inconsistent or off-target)
    ↓
Refactor skill (smaller scope, better triggers, clearer rules)
    ↓
Validate (run on same task, compare output)
    ↓
Version bump
```

## Anti-Patterns
- ❌ Loading the entire `docs/` directory into every agent
- ❌ Skills longer than one page (AI misses the second half — split them)
- ❌ No dependency declaration (agents read whatever they find)
- ❌ Editing an ADR (create a new superseding ADR instead)
- ❌ Hardcoding tech stack references in skills (keep them stack-agnostic)