{"id":"240af044-5665-4fe3-b2f2-f0d3430b56cc","shortId":"ANS3Sq","kind":"skill","title":"establishing-project-context","tagline":"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.","description":"# Establishing Project Context\n\n## Overview\n\nMaintain 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.\n\nCONTEXT.md is about the user's project domain, NOT about Aegis governance. For Aegis governance docs, see `docs/current/` and `docs/adr/`.\n\n## Where CONTEXT.md Lives\n\n- **Single project**: `<project_root>/CONTEXT.md`\n- **Monorepo / multiple bounded contexts**: `<project_root>/CONTEXT-MAP.md` maps context names to their locations:\n\n  ```\n  ordering → src/ordering/CONTEXT.md\n  billing  → src/billing/CONTEXT.md\n  ```\n\n  System-wide terms still go in root `CONTEXT.md`.\n\nCreate files lazily — only when you have something to write.\n\n## When to Use\n\n**On first entering a project:**\n\n1. Check if `CONTEXT.md` (or `CONTEXT-MAP.md`) exists\n2. If not, ask briefly: \"Want me to set up a shared language glossary for this project?\"\n3. If yes, start with 3-5 core domain terms, then iterate\n\n**During brainstorming / planning / debugging:**\n\n- When user uses a vague or overloaded term, propose a precise canonical term\n- Check against existing CONTEXT.md glossary before proposing\n- Write each term resolution immediately — don't batch\n\n## CONTEXT.md Format\n\nSee `CONTEXT-FORMAT.md` in this directory for the canonical template.\n\nKey rules:\n- Only include terms meaningful to domain experts\n- Don't couple CONTEXT.md to implementation details\n- Each term: name, one-sentence definition, and what to avoid calling it\n- Record resolved ambiguities so they aren't re-litigated\n\n## Integration with Aegis Workflows\n\n- **brainstorming**: Reads CONTEXT.md in Step 1 (Explore project context), tightens terminology during Step 4 (Ask clarifying questions)\n- **writing-plans**: Uses CONTEXT.md terms in plan task descriptions\n- **systematic-debugging**: References CONTEXT.md for canonical component names\n\n## Boundary: CONTEXT.md vs baseline/\n\nCONTEXT.md and `docs/aegis/baseline/` serve different purposes:\n\n| | CONTEXT.md | baseline/ |\n|---|-----------|-----------|\n| What | Domain language, ubiquitous terminology | Technical architecture snapshot |\n| Audience | Domain experts + agents | Agents + developers |\n| Content | Terms, definitions, resolved ambiguities | Ownership, contracts, dependencies, anti-patterns |\n| Updates | Immediately on term resolution | After architecture review or material change |\n| Trigger | establishing-project-context skill | brainstorming, writing-plans, code-review, systematic-debugging |\n\nDo NOT put implementation details in CONTEXT.md.\nDo NOT put domain glossary terms in baseline/.\n\n## Red Flags\n\n- Don't turn CONTEXT.md into architecture documentation (that's ADRs)\n- Don't add implementation details (class names, file paths, config keys)\n- Don't batch term updates — write immediately when resolved\n- Don't create CONTEXT.md without user consent","tags":["establishing","project","context","aegis","ganyuanran","add","agent-skills","ai-agents","ai-coding","baseline-first","claude-code","codex"],"capabilities":["skill","source-ganyuanran","skill-establishing-project-context","topic-add","topic-agent-skills","topic-ai-agents","topic-ai-coding","topic-baseline-first","topic-claude-code","topic-codex","topic-coding-agents","topic-evidence-driven","topic-first-principles","topic-opencode","topic-software-architecture"],"categories":["Aegis"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/GanyuanRan/Aegis/establishing-project-context","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add GanyuanRan/Aegis","source_repo":"https://github.com/GanyuanRan/Aegis","install_from":"skills.sh"}},"qualityScore":"0.581","qualityRationale":"deterministic score 0.58 from registry signals: · indexed on github topic:agent-skills · 262 github stars · SKILL.md body (2,969 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T18:54:49.118Z","embedding":null,"createdAt":"2026-05-04T19:05:07.832Z","updatedAt":"2026-05-18T18:54:49.118Z","lastSeenAt":"2026-05-18T18:54:49.118Z","tsv":"'-5':172 '/context-map.md':104 '/context.md':99 '1':142,269 '2':149 '3':166,171 '4':277 'add':393 'adr':390 'aegi':84,87,262 'agent':60,323,324 'ambigu':252,330 'anti':335 'anti-pattern':334 'architectur':318,343,386 'aren':255 'ask':18,152,278 'audienc':320 'avoid':247 'baselin':303,311,378 'batch':209,404 'bill':113 'borrow':64 'bound':102 'boundari':300 'brainstorm':179,264,354 'briefli':153 'call':248 'canon':193,219,297 'chang':347 'check':143,195 'clarifi':279 'class':396 'code':359 'code-review':358 'compon':298 'config':400 'consent':417 'content':326 'context':4,33,103,106,272,352 'context-format.md':213 'context-map.md':147 'context.md':37,74,95,123,145,198,210,233,266,285,295,301,304,310,370,384,414 'contract':332 'core':173 'coupl':232 'creat':27,124,413 'debug':181,293,363 'defin':23,44 'definit':243,328 'depend':333 'descript':290 'design':69 'detail':236,368,395 'develop':325 'differ':308 'directori':216 'doc':89 'docs/adr':93 'docs/aegis/baseline':306 'docs/current':91 'document':387 'domain':24,48,67,81,174,228,313,321,374 'domain-driven':66 'driven':68 'enter':7,139 'establish':2,20,31,350 'establishing-project-context':1,349 'exist':148,197 'expert':229,322 'explor':270 'file':38,125,398 'first':12,138 'flag':380 'format':211 'glossari':30,162,199,375 'go':120 'govern':85,88 'human':63 'immedi':206,338,408 'implement':235,367,394 'includ':224 'integr':260 'iter':177 'key':221,401 'languag':22,49,72,161,314 'lazili':126 'litig':259 'live':96 'locat':110 'maintain':35 'map':105 'materi':346 'meaning':226 'monorepo':100 'multipl':101 'name':107,239,299,397 'one':241 'one-sent':240 'order':111 'overload':188 'overview':34 'ownership':331 'path':399 'pattern':336 'plan':180,283,288,357 'precis':192 'principl':73 'project':3,9,29,32,41,46,80,98,141,165,271,351 'propos':190,201 'purpos':309 'put':366,373 'question':280 're':258 're-litig':257 'read':265 'record':250 'red':379 'refer':294 'resolut':205,341 'resolv':251,329,410 'review':344,360 'root':42,122 'rule':222 'see':90,212 'sentenc':242 'serv':307 'set':157 'share':21,57,160 'singl':51,97 'skill':353 'skill-establishing-project-context' 'snapshot':319 'someth':131 'sourc':52 'source-ganyuanran' 'src/billing/context.md':114 'src/ordering/context.md':112 'start':169 'step':268,276 'still':119 'system':116 'system-wid':115 'systemat':292,362 'systematic-debug':291,361 'task':289 'technic':317 'templat':220 'term':25,118,175,189,194,204,225,238,286,327,340,376,405 'terminolog':56,274,316 'tighten':273 'time':13 'topic-add' 'topic-agent-skills' 'topic-ai-agents' 'topic-ai-coding' 'topic-baseline-first' 'topic-claude-code' 'topic-codex' 'topic-coding-agents' 'topic-evidence-driven' 'topic-first-principles' 'topic-opencode' 'topic-software-architecture' 'trigger':348 'truth':54 'turn':383 'ubiquit':71,315 'updat':337,406 'use':5,136,184,284 'user':17,78,183,416 'vagu':186 'vs':302 'want':154 'wide':117 'without':415 'workflow':263 'write':133,202,282,356,407 'writing-plan':281,355 'yes':168","prices":[{"id":"c97643be-a235-4d7a-9a73-c1b8d0d6a2ad","listingId":"240af044-5665-4fe3-b2f2-f0d3430b56cc","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"GanyuanRan","category":"Aegis","install_from":"skills.sh"},"createdAt":"2026-05-04T19:05:07.832Z"}],"sources":[{"listingId":"240af044-5665-4fe3-b2f2-f0d3430b56cc","source":"github","sourceId":"GanyuanRan/Aegis/establishing-project-context","sourceUrl":"https://github.com/GanyuanRan/Aegis/tree/main/skills/establishing-project-context","isPrimary":false,"firstSeenAt":"2026-05-04T19:05:07.832Z","lastSeenAt":"2026-05-18T18:54:49.118Z"}],"details":{"listingId":"240af044-5665-4fe3-b2f2-f0d3430b56cc","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"GanyuanRan","slug":"establishing-project-context","github":{"repo":"GanyuanRan/Aegis","stars":262,"topics":["add","agent-skills","ai-agents","ai-coding","architecture-driven-development","baseline-first","claude-code","codex","coding-agents","evidence-driven","first-principles","opencode","software-architecture","tdd","tlref"],"license":"mit","html_url":"https://github.com/GanyuanRan/Aegis","pushed_at":"2026-05-18T11:05:01Z","description":"Make AI coding agents architecture-aware: baseline-first, evidence-verified, drift-checked, and safe across long tasks.","skill_md_sha":"3b6f57a32fe55eb79b26feb52bdf0ca18242d8c7","skill_md_path":"skills/establishing-project-context/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/GanyuanRan/Aegis/tree/main/skills/establishing-project-context"},"layout":"multi","source":"github","category":"Aegis","frontmatter":{"name":"establishing-project-context","description":"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."},"skills_sh_url":"https://skills.sh/GanyuanRan/Aegis/establishing-project-context"},"updatedAt":"2026-05-18T18:54:49.118Z"}}