docs(agents): scaffold agent-skill conventions and move the glossary to CONTEXT.md

[lesnik512]

Closes #429.

Why

The engineering skills (/triage, /to-tickets, /to-spec, /domain-modeling,
/wayfinder) each expect a small set of per-repo configuration files naming the issue
tracker, the triage label strings, and where the glossary and decision records live. None
of it exists here, so every invocation either guesses or stops to ask.

The glossary is the sharper case: it already exists, in the shape the skills want (term,
one-line definition, synonyms to reject), but it sits in CLAUDE.md ## Vocabulary — a file
the skills do not read. The vocabulary is written down and still not reachable by the tools
meant to enforce it.

This is the first of three PRs (#429 → #430 → #431). It is additive and mechanical.

Design

Three configuration files under docs/agents/, the skills' native path, seeded from the
setup skill's templates and edited down to this repo:

• issue-tracker.md — GitHub Issues on modern-python/modern-di via gh. PRs are not a
  request surface; the flag stays no.
• triage-labels.md — the five canonical roles, each label string equal to its role name.
  All five already exist on the repo. The pre-existing bug/enhancement/documentation
  labels are a kind vocabulary and are untouched; they do not overlap the state vocabulary.
• domain.md — the seed template reduced to the single-context tree, plus the ADR link rules.

.claude/ was rejected as the home: it is gitignored, so nothing there would be committed,
and .claude/agents/ is reserved by Claude Code for subagent definitions.

docs/ is docs_dir and every Markdown file under it is currently in nav, so three new
pages would trip omitted_files: warn. mkdocs.yml gains exclude_docs: | with /agents/.
Excluded files are, per MkDocs' release notes, "as good as nonexistent" during a build — not
copied to site/, so they cannot warn. not_in_nav was rejected here because it still
builds and publishes the page, and agent configuration is not user documentation.

The glossary moves to a root CONTEXT.md in the native CONTEXT format: context name,
description, then ## Language with **Term**: / definition / _Avoid_:. All ten terms
carry over unchanged in meaning — Container, Provider, Scope, Group, Resolution, Override,
Bound type, Wiring plan, Finalizer, Connection — and the admission rule ("listed only when
there is a synonym to reject") travels with them, so the glossary does not grow into a
dictionary of general programming terms. CLAUDE.md keeps a one-line pointer where the
section was, and gains an ## Agent skills block pointing at all three config files.

One deliberate forward reference. /triage writes rejected enhancements to
.out-of-scope/ and reads it back to detect re-proposals. This repo's home for that becomes
docs/adr/, which #430 creates. issue-tracker.md states the mapping now rather than later:
left unstated, /triage would create a fourth decision home behind our backs. The cost is
that between this PR and #430, that mapping names a directory that does not exist yet and
CLAUDE.md describes two decision homes — the Workflow section still says
planning/decisions/. Both reviews flagged it; it is a consequence of the PR ordering, not
of the prose, and #430 is already blocked-by this one. Merging #430 promptly closes it.

Non-goals

• Creating docs/adr/ or moving any decision record — Migrate planning/decisions/ to native ADRs in docs/adr/ (29 → 26) #430.
• Migrating deferred items to issues, and deleting planning/index.py — Migrate planning/decisions/ to native ADRs in docs/adr/ (29 → 26) #430/Migrate deferred items to GitHub Issues and retire the deferred concept #431.
• Any change to the modern-python/.github org repo. A deferred.yml issue template was
  rejected: issue forms only fire in the web UI and gh issue create bypasses them, and a
  repo-local ISSUE_TEMPLATE/ would suppress the org's bug_report.yml,
  feature_request.yml, and config.yml entirely — GitHub's precedence for issue templates
  is per-directory, not per-file.
• A deferred label. That concept is being retired, not carried forward.
• wayfinder:* labels. Created if and when /wayfinder is first used.

Verification

No new test seams: this is Markdown plus one MkDocs config key, and the behaviour worth
verifying is already gated. A test asserting that CONTEXT.md contains a particular sentence
would test the diff, not the system.

• just lint-ci — passes. The relevant check is planning/links.py, which walks every *.md
  in the repo and validates relative links and heading anchors under GitHub's slug algorithm;
  the new files fall under it automatically. Confirmed no remaining reference anywhere to the
  old CLAUDE.md#vocabulary anchor.
• just docs-build (mkdocs build --strict) — passes with zero warnings, and site/agents/
  is absent from the build output.
• just test-ci — 514 passed, 100.00% line coverage. No Python changed.
• Term-set diff between main:CLAUDE.md ## Vocabulary and CONTEXT.md: identical, same order.
• gh label list confirms all five triage labels exist before any skill tries to apply one.

Reviewed on both axes (/code-review). Four findings fixed: a two-line rationale comment in
mkdocs.yml cut to one; the admission rule de-duplicated to CONTEXT.md alone; and two
invented ADR references in domain.md (0004-scope-enum.md, ADR-0007) replaced with
NNNN-slug.md placeholders so they cannot read as real records.

---

Before merging

• Behaviour changed? No — documentation and one build-config key. Nothing to pin.
• Adding a fact anywhere? Ran the admission check. The glossary moved rather than grew;
  the docs/agents/ files are agent configuration, which is why they are excluded from the
  published site.
• Rejected an alternative? The three that would be re-litigated (.claude/ as the config
  home, not_in_nav over exclude_docs, a repo-local issue template) are recorded above. The
  decision corpus itself is being migrated in Migrate planning/decisions/ to native ADRs in docs/adr/ (29 → 26) #430; filing new records into
  planning/decisions/ now would add to the corpus that PR has to move.
• Found real work you are not doing now? It is already filed — as Migrate planning/decisions/ to native ADRs in docs/adr/ (29 → 26) #430 and Migrate deferred items to GitHub Issues and retire the deferred concept #431.
• just lint-ci and just test-ci pass.

https://claude.ai/code/session_01FBic7HFGR6sdRfSW3cGEv2

[github-actions]

Benchmark

Details

Benchmark suite	Current: 2103704	Previous: cec6f48	Ratio
benchmarks/test_guard_by_type.py::test_g16_resolve_by_type	3295203.6531430366 iter/sec (stddev: 1.0364868832292987e-8)	2977479.210722789 iter/sec (stddev: 1.3898558032024847e-8)	0.90
benchmarks/test_guard_by_type.py::test_g17_resolve_by_type_large_registry	2958088.4713994195 iter/sec (stddev: 8.794804601038796e-8)	3089453.138355987 iter/sec (stddev: 1.1666309156230705e-8)	1.04
benchmarks/test_guard_cold.py::test_g8_cold_first_resolve	24192.006214943824 iter/sec (stddev: 0.000004209638553554667)	23888.66842243009 iter/sec (stddev: 0.0000038987261993240734)	0.99
benchmarks/test_guard_cold.py::test_g8b_cold_first_resolve_cached	18497.857974507406 iter/sec (stddev: 0.00000238355883673448)	18381.28478309777 iter/sec (stddev: 0.000004353632573182633)	0.99
benchmarks/test_guard_concurrency.py::test_g14_concurrent_cached_hit[1]	466.32677920450004 iter/sec (stddev: 0.00005350843145685869)	422.1753414220939 iter/sec (stddev: 0.00004140616662118259)	0.91
benchmarks/test_guard_concurrency.py::test_g14_concurrent_cached_hit[2]	439.24500519383395 iter/sec (stddev: 0.00004734690801170253)	394.8239188808464 iter/sec (stddev: 0.000039331523697275534)	0.90
benchmarks/test_guard_concurrency.py::test_g14_concurrent_cached_hit[4]	406.05287467093166 iter/sec (stddev: 0.000035507708697057376)	367.53716981725984 iter/sec (stddev: 0.00004375051864138776)	0.91
benchmarks/test_guard_concurrency.py::test_g15_concurrent_first_resolve[1]	2450.489543481939 iter/sec (stddev: 0.000019471722946123)	2314.296017866126 iter/sec (stddev: 0.000024081705188430506)	0.94
benchmarks/test_guard_concurrency.py::test_g15_concurrent_first_resolve[2]	1807.3564921670152 iter/sec (stddev: 0.00017045203073274475)	1721.753994409884 iter/sec (stddev: 0.00015681588075570213)	0.95
benchmarks/test_guard_concurrency.py::test_g15_concurrent_first_resolve[4]	1305.3806659721274 iter/sec (stddev: 0.000032983672034599294)	1207.8562716257854 iter/sec (stddev: 0.000033214537514327445)	0.93
benchmarks/test_guard_lifecycle.py::test_g6_build_child_container	769658.5217545801 iter/sec (stddev: 4.173855612717199e-8)	716393.8823858632 iter/sec (stddev: 6.911410329829162e-8)	0.93
benchmarks/test_guard_lifecycle.py::test_g6b_build_child_container_auto_scope	723412.8593145338 iter/sec (stddev: 2.2323361087048673e-8)	654169.703037286 iter/sec (stddev: 4.0196424991331363e-8)	0.90
benchmarks/test_guard_lifecycle.py::test_g7_request_lifecycle_batch	2477.510462595875 iter/sec (stddev: 0.000014530477298199279)	2345.915838970422 iter/sec (stddev: 0.000013407759101732536)	0.95
benchmarks/test_guard_lifecycle.py::test_g7c_event_loop_floor_control	72406.4558182942 iter/sec (stddev: 0.0000012432323540086351)	61472.29296726047 iter/sec (stddev: 0.0000018891054630220704)	0.85
benchmarks/test_guard_lifecycle.py::test_g13_teardown_at_scale	50351.4370909791 iter/sec (stddev: 0.0000013056578840457992)	43772.58876867358 iter/sec (stddev: 0.000002013253584928783)	0.87
benchmarks/test_guard_resolve.py::test_g1_transient_resolve	2172565.1085200533 iter/sec (stddev: 2.343430243783737e-8)	1918723.542308401 iter/sec (stddev: 2.3987149314378075e-8)	0.88
benchmarks/test_guard_resolve.py::test_g2_cached_resolve	3652202.6415754757 iter/sec (stddev: 5.454077372122843e-9)	3360255.3632681286 iter/sec (stddev: 7.764639013326007e-9)	0.92
benchmarks/test_guard_resolve.py::test_g3_deep_chain	822694.9788637025 iter/sec (stddev: 3.6736157048288335e-8)	726553.10944289 iter/sec (stddev: 3.610223404354342e-8)	0.88
benchmarks/test_guard_resolve.py::test_g4_wide_resolve	456918.6589063521 iter/sec (stddev: 8.089312922825659e-8)	401155.9147211535 iter/sec (stddev: 9.467506695748191e-8)	0.88
benchmarks/test_guard_resolve.py::test_g5_cross_scope	1815883.982079656 iter/sec (stddev: 1.586766302948728e-8)	1557449.7865475337 iter/sec (stddev: 3.482000818030679e-8)	0.86
benchmarks/test_guard_resolve.py::test_g9_context_resolve	936221.5894217069 iter/sec (stddev: 2.193237246811667e-8)	831457.87615994 iter/sec (stddev: 6.909838270654823e-8)	0.89
benchmarks/test_guard_resolve.py::test_g12_override_active_resolve	576009.2769753793 iter/sec (stddev: 1.0868452986028178e-7)	485947.5509520025 iter/sec (stddev: 4.8151653200589186e-8)	0.84
benchmarks/test_guard_resolve.py::test_g18_alias_hop	2420693.716592349 iter/sec (stddev: 8.388685887840745e-9)	2319654.8390739923 iter/sec (stddev: 1.6406785207473637e-8)	0.96
benchmarks/test_guard_validate.py::test_g10_validate_deep_chain	29101.809888145937 iter/sec (stddev: 0.0000020989905313999603)	28376.270098104214 iter/sec (stddev: 0.0000032583968216467984)	0.98
benchmarks/test_guard_validate.py::test_g11_validate_wide	17470.871660108227 iter/sec (stddev: 0.0000034740791695599396)	17025.771109547342 iter/sec (stddev: 0.000004181714276482456)	0.97

This comment was automatically generated by workflow using github-action-benchmark.