From 1a6a57173e8053fa2f410a223411ccde2394d855 Mon Sep 17 00:00:00 2001 From: Artur Shiriev Date: Sun, 6 Sep 2026 11:23:43 +0300 Subject: [PATCH] docs(agents): configure the engineering skills for this repo Add docs/agents/{issue-tracker,triage-labels,domain}.md so /triage, /code-review and friends can run here, and link them from CLAUDE.md. domain.md is adapted rather than stock: it maps the skills' CONTEXT.md + docs/adr/ model onto this repo's architecture/ + planning/ convention instead of introducing a second truth home, and points at modern-di's glossary as the upstream authority for shared terms. --- CLAUDE.md | 8 ++++ docs/agents/domain.md | 80 ++++++++++++++++++++++++++++++++++++ docs/agents/issue-tracker.md | 45 ++++++++++++++++++++ docs/agents/triage-labels.md | 15 +++++++ 4 files changed, 148 insertions(+) create mode 100644 docs/agents/domain.md create mode 100644 docs/agents/issue-tracker.md create mode 100644 docs/agents/triage-labels.md diff --git a/CLAUDE.md b/CLAUDE.md index f69821a..a4b1960 100644 --- a/CLAUDE.md +++ b/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/.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) diff --git a/docs/agents/domain.md b/docs/agents/domain.md new file mode 100644 index 0000000..cf02514 --- /dev/null +++ b/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/.md`, one per capability | +| `docs/adr/` (durable decisions) | `planning/decisions/-.md` | +| the *why* behind a shipped change | `planning/changes/.NN-.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/.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/.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/-.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. diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md new file mode 100644 index 0000000..b258aeb --- /dev/null +++ b/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 --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 --body "..."` +- **Apply / remove labels**: `gh issue edit --add-label "..."` / `--remove-label "..."` +- **Close**: `gh issue close --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 --comments` and `gh pr diff ` 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 --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 #` at the top of the child body. Labels: `wayfinder:` (`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///issues//dependencies/blocked_by -F issue_id=`, where `` is the blocker's numeric **database id** (`gh api repos///issues/ --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: #, #` 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 --add-assignee @me`, the session's first write. +- **Resolve**: `gh issue comment --body ""`, then `gh issue close `, then append a context pointer (gist + link) to the map's Decisions-so-far. diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.md new file mode 100644 index 0000000..b716855 --- /dev/null +++ b/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.