docs(agents): configure the engineering skills for this repo

CLAUDE.md

@@ -35,3 +35,11 @@ Key contract: this package does **not** own the container. The user defines a `d
 `tests/sample.py` is the reference fixture model: a `Group` subclass holding `providers.Factory` instances at `APP` and `REQUEST` scopes, plus deliberately non-Provider attributes to exercise the skip path in `expose`.
 
 When a change alters a capability's behavior, update the matching `architecture/<capability>.md` in the same PR.
+
+## Agent skills
+
+- **Issues and specs** — GitHub Issues on `modern-python/modern-di-pytest`, via `gh`:
+  [`docs/agents/issue-tracker.md`](docs/agents/issue-tracker.md)
+- **Triage labels** — the five canonical roles: [`docs/agents/triage-labels.md`](docs/agents/triage-labels.md)
+- **Domain docs** — single-context, `architecture/` + `planning/`:
+  [`docs/agents/domain.md`](docs/agents/domain.md)

docs/agents/domain.md

@@ -0,0 +1,80 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring
+the codebase.
+
+This repo does **not** use the stock `CONTEXT.md` + `docs/adr/` layout. It follows the
+two-axis planning convention (applied version in `planning/.convention-version`), which
+already has a home for each role. Use the repo's own files — do not create `CONTEXT.md`,
+`CONTEXT-MAP.md`, or `docs/adr/`.
+
+## Layout: single-context
+
+| Stock skill concept                | This repo                                       |
+| ---------------------------------- | ----------------------------------------------- |
+| `CONTEXT.md` (ubiquitous language) | `architecture/glossary.md`                      |
+| what the system does now           | `architecture/<capability>.md`, one per capability |
+| `docs/adr/` (durable decisions)    | `planning/decisions/<YYYY-MM-DD>-<slug>.md`     |
+| the *why* behind a shipped change  | `planning/changes/<YYYY-MM-DD>.NN-<slug>.md`    |
+
+`CLAUDE.md` carries the current public contract of `modern_di_pytest/factory.py` under its
+`## Architecture` heading. Read it before proposing anything about `modern_di_fixture` or
+`expose`; it is more specific than anything in `architecture/` today.
+
+## Before exploring, read these
+
+- `CLAUDE.md` — `## Architecture` states the two public symbols and their contract.
+- `architecture/README.md`, then any `architecture/<capability>.md` touching your area.
+  No capability files exist yet; the directory explains when to add the first.
+- `architecture/glossary.md` — the ubiquitous language.
+- `planning/decisions/*.md` whose subject touches your area. Each carries
+  `status: accepted | superseded`; a superseded decision is history, follow
+  `superseded_by`.
+- `planning/changes/*.md` for the rationale behind a specific past change.
+  `just index` prints the change/decision listing.
+
+If any of these don't exist, **proceed silently**. Don't flag their absence; don't suggest
+creating them upfront. `architecture/glossary.md` in particular is authored lazily — it
+appears when the first term is worth pinning down.
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (an issue title, a refactor proposal, a
+hypothesis, a test name), use the term as defined in `architecture/glossary.md`, and honor
+its `_Avoid_:` lines — those synonyms are rejected on purpose.
+
+This package is a thin adapter over `modern-di`, so most domain terms are that project's,
+not this one's: `Container`, `Provider`, `Group`, `Scope`, `Resolution`, `Override`. Its
+glossary is the upstream authority; do not redefine a term here that `modern-di` already
+defines.
+
+If the concept you need is in neither, 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`).
+
+## Writing back
+
+Domain docs here are written under the planning convention, not freehand:
+
+- **A new or sharpened term** → edit `architecture/glossary.md` in the same PR as the
+  change. No frontmatter; each entry is a term, a one-or-two-sentence definition of what
+  it *is*, and an optional `_Avoid_:` line. Seed a new file from
+  `planning/_templates/glossary.md`.
+- **A behavior change** → hand-edit the affected `architecture/<capability>.md` in the
+  implementing PR, alongside the code. Never as a separate post-merge step.
+- **A design decision, especially a rejected option** → a new
+  `planning/decisions/<YYYY-MM-DD>-<slug>.md` from `planning/_templates/decision.md`,
+  including its **Revisit trigger**.
+- Run `just check-planning` and `just check-links` before pushing. The link checker walks
+  every relative Markdown link and heading anchor in the repository, including this file.
+
+## Flag conflicts
+
+If your output contradicts an accepted decision or a capability page, surface it
+explicitly rather than silently overriding:
+
+> _Contradicts `planning/decisions/2026-06-26-expose-installs-into-modules-only.md`, but
+> worth reopening because…_
+
+A decision's **Revisit trigger** names the concrete signal that should reopen it. If that
+signal has fired, say so.

docs/agents/issue-tracker.md

@@ -0,0 +1,45 @@
+# Issue tracker: GitHub
+
+Issues and specs 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 / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- **Close**: `gh issue close <number> --comment "..."`
+
+Infer the repo from `git remote -v`; `gh` does this automatically when run inside a clone.
+
+## Pull requests as a triage surface
+
+**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests; `/triage` reads this flag.)_
+
+When set to `yes`, PRs run through the same labels and states as issues, using the `gh pr` equivalents:
+
+- **Read a PR**: `gh pr view <number> --comments` and `gh pr diff <number>` for the diff.
+- **List external PRs for triage**: `gh pr list --state open --json number,title,body,labels,author,authorAssociation,comments` then keep only `authorAssociation` of `CONTRIBUTOR`, `FIRST_TIME_CONTRIBUTOR`, or `NONE` (drop `OWNER`/`MEMBER`/`COLLABORATOR`).
+- **Comment / label / close**: `gh pr comment`, `gh pr edit --add-label`/`--remove-label`, `gh pr close`.
+
+GitHub shares one number space across issues and PRs, so a bare `#42` may be either: resolve with `gh pr view 42` and fall back to `gh issue view 42`.
+
+## 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`.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.
+
+- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `gh issue create --label wayfinder:map`.
+- **Child ticket**: an issue linked to the map as a GitHub sub-issue (`gh api` on the sub-issues endpoint). Where sub-issues aren't enabled, add the child to a task list in the map body and put `Part of #<map>` at the top of the child body. Labels: `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
+- **Blocking**: GitHub's **native issue dependencies**, the canonical, UI-visible representation. Add an edge with `gh api --method POST repos/<owner>/<repo>/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-db-id>`, where `<blocker-db-id>` is the blocker's numeric **database id** (`gh api repos/<owner>/<repo>/issues/<n> --jq .id`, _not_ the `#number` or `node_id`). GitHub reports `issue_dependencies_summary.blocked_by` (open blockers only, the live gate). Where dependencies aren't available, fall back to a `Blocked by: #<n>, #<n>` line at the top of the child body. A ticket is unblocked when every blocker is closed.
+- **Frontier query**: list the map's open children (`gh issue list --state open`, scoped to the map's sub-issues / task list), drop any with an open blocker (`issue_dependencies_summary.blocked_by > 0`, or an open issue in the `Blocked by` line) or an assignee; first in map order wins.
+- **Claim**: `gh issue edit <n> --add-assignee @me`, the session's first write.
+- **Resolve**: `gh issue comment <n> --body "<answer>"`, then `gh issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.

docs/agents/triage-labels.md

@@ -0,0 +1,15 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+
+| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
+| -------------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
+
+Edit the right-hand column to match whatever vocabulary you actually use.