docs: configure triage roles and domain docs for the agent skills

AGENTS.md

@@ -6,6 +6,14 @@
 
 Issues live in Linear: team **Engineering** (`ENG`), project **omap-stack**. See `docs/agents/issue-tracker.md`.
 
+### Triage labels
+
+Triage and Canceled are Linear states; `needs-info`, `ready-for-agent`, `ready-for-human` are labels. See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context: one `CONTEXT.md` and `docs/adr/` at the repo root. See `docs/agents/domain.md`.
+
 ## Working rules
 
 - No em-dashes in anything you write: use colons, semicolons or parentheses.

docs/agents/domain.md

@@ -0,0 +1,51 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root if it exists: it points at one `CONTEXT.md` per 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 check `src/<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-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…_

docs/agents/triage-labels.md

@@ -0,0 +1,13 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to what this repo's tracker (Linear, team Engineering) actually uses. Two roles are Linear **states**, not labels.
+
+| Role in mattpocock/skills | In our tracker                 | Meaning                                  |
+| ------------------------- | ------------------------------ | ---------------------------------------- |
+| `needs-triage`            | state **Triage**               | Maintainer needs to evaluate this issue  |
+| `needs-info`              | label `needs-info`             | Waiting on reporter for more information |
+| `ready-for-agent`         | label `ready-for-agent`        | Fully specified, ready for an AFK agent  |
+| `ready-for-human`         | label `ready-for-human`        | Requires human implementation            |
+| `wontfix`                 | state **Canceled**             | Will not be actioned                     |
+
+When a skill says "apply" a role that is a state, set the state with `save_issue` (`state: Triage` / `state: Canceled`) instead of adding a label; "remove" it by moving the issue to Backlog. Label roles use `addLabels` / `removeLabels`.