Palash Debnath
74796bb2ab
Scaffolds the per-repo agent configuration the engineering skills assume: where issues live (GitHub Issues via the gh CLI), the five canonical triage labels, and the single-context domain-doc layout. Adds docs/agents/{issue-tracker,triage-labels,domain}.md and an '## Agent skills' block in both CLAUDE.md and AGENTS.md so the two stay in sync.
Documentation only — no runtime code is touched.
Review fixes: CONTEXT.md is now described as 'read it when it exists' rather than stating its absence as permanent, and both directory-tree fences carry a language identifier (markdownlint MD040).
2.1 KiB
Domain Docs
How the engineering skills should consume this repo's domain documentation when exploring the codebase.
Before exploring, read these
CONTEXT.mdat the repo root — read it whenever it exists. It has not been created yet, so today this usually resolves to nothing; see below.docs/adr/— read ADRs that touch the area you're about to work in.
If any of these files don't exist, proceed silently. Don't flag their absence; don't suggest creating them upfront. The /domain-modeling skill (reached via /grill-with-docs and /improve-codebase-architecture) creates them lazily when terms or decisions actually get resolved.
CLAUDE.md is the de-facto context document today — it carries the project
constraints, the versioning/docs-sync/changelog/fix-quality rules, and the
local-first guarantee. Read it as context alongside anything here.
File structure
Single-context repo (most repos):
/
├── CONTEXT.md
├── docs/adr/
│ ├── 0001-event-sourced-orders.md
│ └── 0002-postgres-for-write-model.md
└── src/
Multi-context repo (presence of CONTEXT-MAP.md at the root):
/
├── CONTEXT-MAP.md
├── docs/adr/ ← system-wide decisions
└── src/
├── ordering/
│ ├── CONTEXT.md
│ └── docs/adr/ ← context-specific decisions
└── billing/
├── CONTEXT.md
└── docs/adr/
Use the glossary's vocabulary
When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in CONTEXT.md. Don't drift to synonyms the glossary explicitly avoids.
If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for /domain-modeling).
Flag ADR conflicts
If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…