OpenParable
Skip to content
← Back to skills

Establishing Project Context

Productivity
establishing-project-context

Establishing Project Context is an Agent Skill for productivity published in the hashgraph-online/awesome-codex-plugins repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use when entering a project for the first time, or when the user asks to establish shared language, define domain terms, or create a project glossary.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/hashgraph-online/awesome-codex-plugins/blob/HEAD/plugins/GanyuanRan/Aegis/skills/establishing-project-context/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/establishing-project-context, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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.mdbaseline/
WhatDomain language, ubiquitous terminologyTechnical architecture snapshot
AudienceDomain experts + agentsAgents + developers
ContentTerms, definitions, resolved ambiguitiesOwnership, contracts, dependencies, anti-patterns
UpdatesImmediately on term resolutionAfter architecture review or material change
Triggerestablishing-project-context skillbrainstorming, 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