establishing-project-context

# Establishing Project Context

## Overview

Maintain a `CONTEXT.md` file at the project root that defines the project's domain language — a single source of truth for terminology shared between the agent and the human. Borrowed from Domain-Driven Design's "ubiquitous language" principle.

CONTEXT.md is about the user's project domain, NOT about Aegis governance. For Aegis governance docs, see `docs/current/` and `docs/adr/`.

## Where CONTEXT.md Lives

- **Single project**: `<project_root>/CONTEXT.md`
- **Monorepo / multiple bounded contexts**: `<project_root>/CONTEXT-MAP.md` maps context names to their locations:

  ```
  ordering → src/ordering/CONTEXT.md
  billing  → src/billing/CONTEXT.md
  ```

  System-wide terms still go in root `CONTEXT.md`.

Create files lazily — only when you have something to write.

## When to Use

**On first entering a project:**

1. Check if `CONTEXT.md` (or `CONTEXT-MAP.md`) exists
2. If not, ask briefly: "Want me to set up a shared language glossary for this project?"
3. If yes, start with 3-5 core domain terms, then iterate

**During brainstorming / planning / debugging:**

- When user uses a vague or overloaded term, propose a precise canonical term
- Check against existing CONTEXT.md glossary before proposing
- Write each term resolution immediately — don't batch

## CONTEXT.md Format

See `CONTEXT-FORMAT.md` in this directory for the canonical template.

Key rules:
- Only include terms meaningful to domain experts
- Don't couple CONTEXT.md to implementation details
- Each term: name, one-sentence definition, and what to avoid calling it
- Record resolved ambiguities so they aren't re-litigated

## Integration with Aegis Workflows

- **brainstorming**: Reads CONTEXT.md in Step 1 (Explore project context), tightens terminology during Step 4 (Ask clarifying questions)
- **writing-plans**: Uses CONTEXT.md terms in plan task descriptions
- **systematic-debugging**: References CONTEXT.md for canonical component names

## Boundary: CONTEXT.md vs baseline/

CONTEXT.md and `docs/aegis/baseline/` serve different purposes:

| | CONTEXT.md | baseline/ |
|---|-----------|-----------|
| What | Domain language, ubiquitous terminology | Technical architecture snapshot |
| Audience | Domain experts + agents | Agents + developers |
| Content | Terms, definitions, resolved ambiguities | Ownership, contracts, dependencies, anti-patterns |
| Updates | Immediately on term resolution | After architecture review or material change |
| Trigger | establishing-project-context skill | brainstorming, writing-plans, code-review, systematic-debugging |

Do NOT put implementation details in CONTEXT.md.
Do NOT put domain glossary terms in baseline/.

## Red Flags

- Don't turn CONTEXT.md into architecture documentation (that's ADRs)
- Don't add implementation details (class names, file paths, config keys)
- Don't batch term updates — write immediately when resolved
- Don't create CONTEXT.md without user consent