diff --git a/AGENTS.md b/AGENTS.md index 8b0e1a2..d67fcc5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -195,15 +195,12 @@ or a meaning subtle enough that code and docs must agree on it. ### Issue tracker -Issues and specs live as GitHub issues on `modern-python/chat-app`, driven with -`gh`. See [`docs/agents/issue-tracker.md`](docs/agents/issue-tracker.md). +GitHub issues on `modern-python/chat-app`, via `gh`. See `docs/agents/issue-tracker.md`. ### Triage labels -The five canonical triage roles, unchanged, applied as GitHub labels. See -[`docs/agents/triage-labels.md`](docs/agents/triage-labels.md). +The five canonical roles, each label string equal to its name. See `docs/agents/triage-labels.md`. ### Domain docs -Single-context: `CONTEXT.md` + `docs/adr/` at the repo root. See -[`docs/agents/domain.md`](docs/agents/domain.md). +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 5815d59..1ec1863 100644 --- a/docs/agents/domain.md +++ b/docs/agents/domain.md @@ -2,30 +2,26 @@ How the engineering skills should consume this repo's domain documentation when exploring the codebase. -This repo is **single-context**: one glossary and one decision log, both at the root. There is no `CONTEXT-MAP.md`, no per-context `CONTEXT.md`, and no context-scoped ADR directory. - ## Before exploring, read these -- **`CONTEXT.md`** at the repo root: the glossary, and nothing but the glossary. -- **`docs/adr/`**: the ADRs that touch the area you're about to work in. `docs/adr/README.md` carries the local standard, which is stricter than the stock ADR format: rejected alternatives and a revisit trigger are required, not optional. +- **`CONTEXT.md`** at the repo root. +- **`docs/adr/`**: read ADRs that touch the area you're about to work in. `docs/adr/README.md` carries the local standard, which is stricter than the stock ADR format: rejected alternatives and a revisit trigger are required, not optional. -If either doesn't exist yet, **proceed silently**. Don't flag its absence; don't suggest creating it upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) 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-sequence-ids-not-snowflakes.md -│ └── 0002-cookie-auth-not-bearer.md -├── app/ -└── tests/ +├── docs/adr/ +│ ├── 0001-sequence-ids-not-snowflakes.md +│ └── 0002-cookie-auth-not-bearer.md +└── app/ ``` -ADR numbers are permanent and mean nothing beyond identity: a new ADR takes the next free number, so the sequence is the order decisions were adopted. Read the ones relevant to your area, not the sequence front to back. - ## 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. @@ -36,4 +32,4 @@ If the concept you need isn't in the glossary yet, that's a signal: either you'r If your output contradicts an existing ADR, surface it explicitly rather than silently overriding: -> _Contradicts ADR-0007 (upsert via duplicate-key recovery), but worth reopening because…_ +> _Contradicts ADR-0001 (sequence ids not snowflakes), but worth reopening because…_ diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md index 3c2736c..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/chat-app`. 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.