alex
864447de71
The engineering skills (to-tickets, triage, spec, wayfinder) need to know where issues live for this repo. It is not the Gitea forge remote; it is bd/beads, which AGENTS.md already mandates for all task tracking. Adds docs/agents/issue-tracker.md (bd commands and wayfinding mapping), docs/agents/triage-labels.md (five canonical roles kept as-is, applied with bd tag / bd label add), docs/agents/domain.md (single-context layout: CONTEXT.md plus docs/adr/ at the root), and an 'Agent skills' index block in AGENTS.md. The pre-existing staged deletion of CLAUDE.md is left out of this commit and stays in the index.
2.2 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, orCONTEXT-MAP.mdat the repo root if it exists — it points at oneCONTEXT.mdper context. Read each one relevant to the topic.docs/adr/— read ADRs that touch the area you're about to work in. In multi-context repos, also checksrc/<context>/docs/adr/for context-scoped decisions.
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.
File structure
Single-context repo (most repos):
/
├── CONTEXT.md
├── docs/adr/
│ ├── 0001-two-overlay-strategies.md
│ └── 0002-package-discovery-via-git-index.md
├── packages/
├── overlays/
└── modules/
This repo uses the single-context layout. There is no CONTEXT-MAP.md and no per-directory CONTEXT.md files; the whole overlay is one domain.
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…