From d19381174ff7a96180a010d5e6a6cd75c3a35094 Mon Sep 17 00:00:00 2001 From: Artur Shiriev Date: Sat, 19 Sep 2026 13:49:46 +0300 Subject: [PATCH] docs: restore the agent artifacts to the setup skill's templates MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Brings this repo's agent artifacts back to the setup skill's seed templates. They had drifted — sections renamed and reordered, wording rephrased, and in places an older copy of the template than the skill now ships (for example `issue-tracker.md` predates the wayfinding section). Template-owned wording is restored verbatim. Anything the template has no slot for is kept: sections this repo added are carried over unchanged, and repo-specific facts inside template sections are preserved rather than reset away. `AGENTS.md` moves from a bulleted variant to the block the skill writes: one `###` sub-block per artifact, each a one-line summary and a pointer. --- AGENTS.md | 20 ++++++++++++---- docs/agents/domain.md | 44 +++++++++++++++--------------------- docs/agents/issue-tracker.md | 12 ++-------- docs/agents/triage-labels.md | 23 ++++++++----------- 4 files changed, 44 insertions(+), 55 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ba18fbe5..7682873f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -70,8 +70,18 @@ description, and PyPI does not rewrite relative links, so a relative one 404s on ## Agent skills -- **Issues and specs** — GitHub Issues on `modern-python/modern-di`, 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, `CONTEXT.md`; public choices on the design-decisions page, internal ones in `docs/adr/`: [`docs/agents/domain.md`](docs/agents/domain.md) -- **Cutting a release** (maintainers) — [`docs/agents/release.md`](docs/agents/release.md) +### Issue tracker + +GitHub issues on `modern-python/modern-di`, via `gh`. See `docs/agents/issue-tracker.md`. + +### Triage labels + +The five canonical roles, each label string equal to its name. See `docs/agents/triage-labels.md`. + +### Domain docs + +Single-context: `CONTEXT.md` and `docs/adr/` at the repo root. See `docs/agents/domain.md`. + +### Cutting a release + +Maintainers only. See `docs/agents/release.md`. diff --git a/docs/agents/domain.md b/docs/agents/domain.md index ad72bf3a..9104d3b6 100644 --- a/docs/agents/domain.md +++ b/docs/agents/domain.md @@ -1,40 +1,39 @@ # Domain Docs -How the engineering skills should consume this repo's domain documentation when exploring the -codebase. This repo is **single-context**. +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: the domain glossary. -- **`docs/introduction/design-decisions.md`**: the deliberate choices behind the public API and - the non-goals. Anything a user can observe is decided there, in user-facing terms. -- **`docs/adr/`**: decisions about internals only, the ones a maintainer would otherwise "fix": - the shape of the resolve path, registry memo invalidation, and the like. An ADR earns its place - only when the decision is hard to reverse, surprising without context, and a real trade-off; - most internal choices are none of these and need no record. +- **`CONTEXT.md`** at the repo root. +- **`docs/introduction/design-decisions.md`**: the deliberate choices behind the public API and the non-goals. Anything a user can observe is decided there, in user-facing terms. +- **`docs/adr/`**: decisions about internals only — the shape of the resolve path, registry memo invalidation, and the like. + +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: + ``` / ├── CONTEXT.md ├── docs/introduction/design-decisions.md ← public API choices and non-goals ├── docs/adr/ ← internal design decisions -├── modern_di/ -└── tests/ +│ └── 0001-resolver-hot-path-generated-source.md +└── modern_di/ ``` -There is no `CONTEXT-MAP.md` and no per-package `CONTEXT.md`: one package, one context. - ## 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: write `Container` and not `injector`, `Provider` and not `service`, `Resolution` and not -`injection`. +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 conflicts with a recorded decision -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`). +If your output contradicts a choice on the design-decisions page or an ADR, surface it explicitly rather than silently overriding: + +> _Contradicts design decision "…" (or ADR-0001), but worth reopening because…_ ## Link style inside `docs/` @@ -46,10 +45,3 @@ working in both renderings: - **Never link from a file inside `docs/` to a path outside it.** It cannot resolve in both renderings: MkDocs emits `links.not_found` and ships the link verbatim, so it 404s on the site. Cite `modern_di/...`, `tests/...`, and root files as inline code, never as links. - -## Flag conflicts with a recorded decision - -If your output contradicts a choice on the design-decisions page or an ADR, surface it explicitly -rather than silently overriding: - -> _Contradicts design decision "…" (or ADR-NNNN), but worth reopening because…_ diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md index d1faa8c0..b258aeb3 100644 --- a/docs/agents/issue-tracker.md +++ b/docs/agents/issue-tracker.md @@ -1,7 +1,6 @@ # Issue tracker: GitHub -Issues and specs for this repo live as GitHub issues on `modern-python/modern-di`. Use the `gh` CLI -for all operations. +Issues and specs for this repo live as GitHub issues. Use the `gh` CLI for all operations. ## Conventions @@ -21,12 +20,7 @@ Infer the repo from `git remote -v`; `gh` does this automatically when run insid 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 --json` has no `authorAssociation` field, so the association has to come from the REST API, where it is `author_association` (snake_case): - ``` - gh api "repos/{owner}/{repo}/pulls?state=open&per_page=100" \ - --jq '.[] | select(.author_association | IN("CONTRIBUTOR","FIRST_TIME_CONTRIBUTOR","NONE")) | {number, title, author: .user.login}' - ``` - That keeps only external authors; `OWNER`, `MEMBER` and `COLLABORATOR` are dropped. `gh api` substitutes `{owner}`/`{repo}` from the current clone. +- **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`. @@ -49,5 +43,3 @@ Used by `/wayfinder`. The **map** is a single issue with **child** issues as tic - **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. - -The `wayfinder:*` labels do not exist in this repo yet. Create them the first time `/wayfinder` runs. diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.md index c4b275da..b716855d 100644 --- a/docs/agents/triage-labels.md +++ b/docs/agents/triage-labels.md @@ -1,20 +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. All five exist on `modern-python/modern-di`. +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. -| Canonical role | 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 | +| 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. +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. - -The repo's `bug`, `enhancement`, and `documentation` labels are a separate *kind* vocabulary. They do -not overlap these *state* labels, and triage leaves them alone unless it is setting the category role.