diff --git a/AGENTS.md b/AGENTS.md index 721a5a41..61981b1e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,11 +14,24 @@ Write commit messages in English using Conventional Commits. ### Issue tracker -Track issues in this repository's GitHub Issues. Use the `gh` CLI and explicitly specify this repository in every command. See `docs/agents/issue-tracker.md`. +Issue tracker configuration is contributor-local. -### Code comments +Before using an issue-tracking skill: -When writing or modifying code comments, do not reference fork repository issues through numbers such as `#123`, qualified references such as `owner/repo#123`, or issue links. These references cannot be tracked through upstream issues after merging. State the behavior, constraint, or design rationale directly so the comment is understandable without consulting a fork issue. +1. Resolve the Git common directory: + + `git rev-parse --path-format=absolute --git-common-dir` + +2. Read `/agent/issue-tracker.md`. + +3. Follow the tracker configuration found there. + +If the file does not exist, ask the contributor to +configure their preferred tracker. + +Never assume GitHub Issues is the default. +Never commit personal tracker configuration. +Never reference personal tracker issues or tasks in code, commit messages, pull requests, or GitHub comments. ### Triage labels @@ -35,3 +48,4 @@ Current code, `GLOSSARY.md`, and `docs/adr/` define the current state and accept `docs/design/` records requirements, designs, and specifications at the time of each task. It is historical reference and does not represent the latest implementation. `docs/research/` contains research reports. Each report records upstream capabilities, candidate solutions, and conclusions at the time of writing. It does not describe the project's current state or establish that a design has been adopted. + diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md deleted file mode 100644 index d2a0ad3a..00000000 --- a/docs/agents/issue-tracker.md +++ /dev/null @@ -1,45 +0,0 @@ -# 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 "..."` - -Resolve the target repository from this clone and pin it explicitly: `REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)`, then pass `--repo "$REPO"` on every `gh` command (`view`/`edit`/`comment`/`close`/`create`/`api` alike). A clone can carry more than one remote, and `gh`'s automatic inference can pick the wrong one: an unqualified `gh issue comment` once landed on a different repository by mistake. **Never write to a repository other than this one.** - -## 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.