maintaining-project-context

# Maintaining Project Context

**REQUIRED SUB-SKILL:** Use ed3d-extending-claude:writing-claude-md-files for all context file creation and updates.

## Core Principle

Context files (CLAUDE.md or AGENTS.md) document contracts and architectural intent. When code changes contracts, the documentation must update. Stale documentation is worse than no documentation.

**Trigger:** End of development phase, branch completion, or any work that changed contracts, APIs, or domain structure.

## Format Detection (MANDATORY FIRST STEP)

Before any updates, detect what format this repository uses:

```bash
# Check for AGENTS.md at root
ls -la AGENTS.md 2>/dev/null

# Check for CLAUDE.md at root
ls -la CLAUDE.md 2>/dev/null
```

| Root AGENTS.md? | Format | Action |
|-----------------|--------|--------|
| Yes | AGENTS.md-canonical | Update AGENTS.md files, create companion CLAUDE.md |
| No | CLAUDE.md-canonical | Update CLAUDE.md files directly |

**Key principle:** We use OUR format structure (Purpose, Contracts, Dependencies, Invariants, etc.) regardless of filename. AGENTS.md is just for cross-platform AI agent compatibility.

### AGENTS.md-Canonical Repos

When the repo uses AGENTS.md:

1. **Read AGENTS.md first** before making any updates
2. **Write content to AGENTS.md** using our standard structure
3. **Create companion CLAUDE.md** next to each AGENTS.md with exactly this content:

```markdown
Read @./AGENTS.md and treat its contents as if they were in CLAUDE.md
```

## When to Update Context Files

| Change Type | Update Required? | What to Update |
|-------------|------------------|----------------|
| New domain/module | Yes | Create domain context file |
| API/interface change | Yes | Contracts section |
| Architectural decision | Yes | Key Decisions section |
| Invariant change | Yes | Invariants section |
| Dependency change | Yes | Dependencies section |
| Bug fix (no contract change) | No | - |
| Refactor (same behavior) | No | - |
| Test additions | No | - |

## Th