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: /CONTEXT.md
• Monorepo / multiple bounded contexts: /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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: GanyuanRan
• Source: GanyuanRan/Aegis
• License: MIT

Install and usage instructions live in the source repository linked above.