LeXwDeX · LeXwDeX · Aug 9, 2026 · Aug 9, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -214,3 +214,17 @@ Invariants for extending the SolidJS/opentui TUI. The DAG inspector (`src/featur
 - Keep delivery vocabulary explicit. Prompts steer by default and promote at the next safe provider-turn boundary while the current drain requires continuation. An explicit `queue` input remains pending until the Session would otherwise become idle; promote one queued input at that boundary, then reevaluate continuation before promoting another. Promoting any new user input resets the selected agent's provider-turn allowance; a batch of steers resets it once.
 - Keep EventV2 replay owner claims separate from clustered Session execution ownership.
 - Keep the System Context algebra, registry, and built-ins in `src/system-context`; keep Context Source producers with their observed domains, and keep Session History selection plus Context Epoch persistence Session-owned.
+
+## Agent skills
+
+### Issue tracker
+
+Issues and PRDs are tracked in this repository's GitHub Issues through the `gh` CLI. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+Triage uses the five canonical labels `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, and `wontfix`. See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+This repository uses a multi-context domain-document layout rooted at `CONTEXT-MAP.md`. See `docs/agents/domain.md`.
diff --git a/CONTEXT-MAP.md b/CONTEXT-MAP.md
@@ -0,0 +1,11 @@
+# Context Map
+
+Read the context documents relevant to the code or decision under review. Do not load unrelated contexts by default.
+
+| Context | Domain document | Primary areas |
+| --- | --- | --- |
+| Session Runtime and Client Contract | [`CONTEXT.md`](CONTEXT.md) | `packages/opencode/src/session`, `packages/opencode/src/system-context`, `packages/protocol`, `packages/client`, `packages/sdk` |
+
+## Contexts created lazily
+
+DAG orchestration does not yet have a dedicated `CONTEXT.md`. The full DAG review must establish terminology from implementation, tests, existing specifications, and accepted decisions before `/domain-modeling` creates one. Add future contexts to this map only when they have a stable document to reference.
diff --git a/docs/agents/domain.md b/docs/agents/domain.md
@@ -0,0 +1,37 @@
+# Domain Docs
+
+How engineering skills consume this repository's domain documentation while exploring the codebase.
+
+## Selected layout
+
+This repository uses a **multi-context** layout. `CONTEXT-MAP.md` is the entry point and points to the domain documents relevant to each bounded context.
+
+## Before exploring
+
+1. Read `CONTEXT-MAP.md` at the repository root.
+2. Read each linked `CONTEXT.md` relevant to the work.
+3. Read system-wide ADRs under `docs/adr/` and context-scoped ADRs linked by the map.
+
+If a referenced directory or document does not exist, proceed silently. Do not create speculative terminology or ADRs merely to fill the layout. `/domain-modeling`, reached through `/grill-with-docs` or `/improve-codebase-architecture`, creates them when terms or decisions are actually resolved.
+
+## File structure
+
+```text
+/
+├── CONTEXT-MAP.md                    # context index
+├── CONTEXT.md                        # existing Session Runtime context
+├── docs/adr/                         # system-wide decisions, created lazily
+└── packages/<context>/
+    ├── CONTEXT.md                    # context vocabulary, created lazily
+    └── docs/adr/                     # context decisions, created lazily
+```
+
+## Use the glossary vocabulary
+
+When an issue title, refactor proposal, hypothesis, or test names a domain concept, use the term defined in the relevant `CONTEXT.md`. Do not replace a defined term with a synonym that the glossary explicitly avoids.
+
+If the required concept is absent, reconsider whether the project already uses another term. If the gap is real, record it for `/domain-modeling`.
+
+## Flag ADR conflicts
+
+If proposed work contradicts an existing ADR, state the conflict explicitly rather than silently overriding it.
diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md
@@ -0,0 +1,39 @@
+# Issue tracker: GitHub
+
+Issues and PRDs for this repo live as GitHub issues. Use the `gh` CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
+- **Read an issue**: `gh issue view <number> --comments`, filtering comments by `jq` and also fetching labels.
+- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
+- **Comment on an issue**: `gh issue comment <number> --body "..."`
+- **Apply or remove labels**: `gh issue edit <number> --add-label "..."` or `--remove-label "..."`
+- **Close**: `gh issue close <number> --comment "..."`
+
+Infer the repository from `git remote -v`; `gh` does this automatically when run inside this clone.
+
+## Pull requests as a triage surface
+
+**PRs as a request surface: no.**
+
+Pull requests are delivery artifacts, not incoming requests. `/triage` does not include them in its queue.
+
+GitHub shares one number space across issues and PRs. Resolve an ambiguous `#42` with `gh pr view 42`, then fall back to `gh issue view 42`.
+
+## Skill operations
+
+- When a skill says **publish to the issue tracker**, create a GitHub issue.
+- When a skill says **fetch the relevant ticket**, run `gh issue view <number> --comments`.
+- Use GitHub's native blocking relationships when available. If unavailable, put `Blocked by: #<n>` at the top of the issue body.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The map is one issue with child issues as tickets.
+
+- **Map**: an issue labelled `wayfinder:map`, holding Notes, Decisions-so-far, and Fog.
+- **Child ticket**: a GitHub sub-issue labelled `wayfinder:<type>` where type is `research`, `prototype`, `grilling`, or `task`. If sub-issues are unavailable, link it from a task list in the map and put `Part of #<map>` at the top of the child body.
+- **Blocking**: prefer GitHub native issue dependencies. Use the blocker's numeric database ID with the dependencies API, not its issue number or node ID. Fall back to a `Blocked by:` line only when native dependencies are unavailable.
+- **Frontier query**: select the first open, unassigned child in map order whose blockers are all closed.
+- **Claim**: `gh issue edit <n> --add-assignee @me` is the working session's first write.
+- **Resolve**: comment with the decision, close the child, and add its context pointer to the map's Decisions-so-far.
diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.md
@@ -0,0 +1,13 @@
+# Triage Labels
+
+The engineering skills use five canonical triage roles. This table maps each role to the label used in this repository's GitHub Issues.
+
+| Canonical role | GitHub label | Meaning |
+| --- | --- | --- |
+| `needs-triage` | `needs-triage` | A maintainer needs to evaluate the issue |
+| `needs-info` | `needs-info` | Waiting for more information from the reporter |
+| `ready-for-agent` | `ready-for-agent` | Fully specified and ready for an agent |
+| `ready-for-human` | `ready-for-human` | Requires human implementation or judgment |
+| `wontfix` | `wontfix` | Will not be actioned |
+
+When a skill mentions a triage role, use the corresponding GitHub label from this table.