From 071e63eec63d07275b02664e8c26a5944a230f55 Mon Sep 17 00:00:00 2001 From: Artur Shiriev Date: Sat, 19 Sep 2026 13:49:32 +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 | 15 ++++++++--- docs/agents/domain.md | 48 +++++++++++++----------------------- docs/agents/issue-tracker.md | 20 ++------------- docs/agents/triage-labels.md | 27 +++++++------------- 4 files changed, 39 insertions(+), 71 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 7b9f634..f25e452 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -65,7 +65,14 @@ what breaks it. ## Agent skills -- **Issues and specs** — GitHub Issues on `modern-python/faststream-outbox`, 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` + `docs/adr/`: [`docs/agents/domain.md`](docs/agents/domain.md) +### Issue tracker + +GitHub issues on `modern-python/faststream-outbox`, 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`. diff --git a/docs/agents/domain.md b/docs/agents/domain.md index d767a39..f610abb 100644 --- a/docs/agents/domain.md +++ b/docs/agents/domain.md @@ -1,42 +1,38 @@ # Domain Docs -How the engineering skills should consume this repo's domain documentation when exploring the -codebase. This repo is **single-context**: one package, one domain. +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/adr/`**: read the decision records that touch the area you're about to work in. +- **`CONTEXT.md`** at the repo root. +- **`docs/adr/`**: read ADRs that touch the area you're about to work in. -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 creates them lazily when terms or decisions -actually get resolved. +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/adr/ -│ ├── 0001-….md -│ └── 0002-….md -├── faststream_outbox/ -└── tests/ +│ ├── 0001-metrics-recorders-not-unified.md +│ └── 0002-free-threading-is-compat-only.md +└── faststream_outbox/ ``` -There is no `CONTEXT-MAP.md` and no per-package `CONTEXT.md`: one package, one context. There is no -`architecture/` and no `planning/` — mechanism lives in the code and its `INVARIANT:`-marked tests, -and the spec for a change is its PR body. - ## 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: a row is *leased*, not locked; a handler produces an *outcome*, not a status; `queue` is a -column value, not a topic. +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 ADR conflicts + +If your output contradicts an existing ADR, surface it explicitly rather than silently overriding: -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`). +> _Contradicts ADR-0001 (metrics recorders not unified), but worth reopening because…_ ## Link style inside `docs/` @@ -51,13 +47,3 @@ the same files are read on GitHub. Two rules keep a link working in both renderi - **Never link from a built page 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 `faststream_outbox/…`, `tests/…`, and root files as inline code, never as links. - -## Flag ADR conflicts - -If your output contradicts an existing decision record, surface it explicitly rather than silently -overriding: - -> _Contradicts ADR-NNNN (its title), but worth reopening because…_ - -The record holds the reasoning that settled it. Make the case against that reasoning, not against -the decision. diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md index cadf04a..b258aeb 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/faststream-outbox`. 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`. @@ -39,14 +33,6 @@ Create a GitHub issue. Run `gh issue view --comments`. -## Rejected work: read and write `docs/adr/`, not `.out-of-scope/` - -Where a skill says `.out-of-scope/`, this repo means `docs/adr/`. A rejected enhancement is recorded -there as a decision record (`NNNN-slug.md`, sequential), and the -prior-rejection check during triage reads that directory. Do not create `.out-of-scope/`: this repo -keeps one home for a rejected alternative, and a second one would split the corpus that the check -depends on. - ## Wayfinding operations Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets. @@ -57,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 4c48847..b716855 100644 --- a/docs/agents/triage-labels.md +++ b/docs/agents/triage-labels.md @@ -1,24 +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. +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. - -All five exist on `modern-python/faststream-outbox`. - -The repo's `bug`, `enhancement`, `documentation`, `question`, `duplicate`, `invalid`, -`help wanted`, `good first issue`, and `scheduled-failure` 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.