diff --git a/.gitignore b/.gitignore index 8cf81af9..d6e84289 100644 --- a/.gitignore +++ b/.gitignore @@ -70,6 +70,10 @@ Carthage/Build IDEWorkspaceChecks.plist +#### +# Local agent scratch space (local-markdown issue tracker; see docs/agents/issue-tracker.md) +.scratch/ + #### # New project build artifacts ShadowsocksX-NG2/.build/ diff --git a/.zcodeignore b/.zcodeignore index 9d1ba130..2ce6b572 100644 --- a/.zcodeignore +++ b/.zcodeignore @@ -70,6 +70,10 @@ Carthage/Build IDEWorkspaceChecks.plist +#### +# Local agent scratch space (local-markdown issue tracker; see docs/agents/issue-tracker.md) +.scratch/ + #### # New project build artifacts ShadowsocksX-NG2/.build/ diff --git a/AGENTS.md b/AGENTS.md index 146f33bb..da3b502c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,7 +6,7 @@ macOS Shadowsocks 客户端。旧版实现已从本仓库移除,归档在 [shado ### Issue tracker -Issue 跟踪在本仓库的 GitHub Issues(qiuyuzhou/ShadowsocksX-NG),统一用 `gh` CLI 操作。见 `docs/agents/issue-tracker.md`。 +Issue 跟踪在本仓库的 GitHub Issues,统一用 `gh` CLI 操作,并在每条命令上显式指定本仓库。见 `docs/agents/issue-tracker.md`。 ### Triage labels diff --git a/docs/agents/domain.md b/docs/agents/domain.md index 1186c34e..4032de01 100644 --- a/docs/agents/domain.md +++ b/docs/agents/domain.md @@ -5,14 +5,14 @@ How the engineering skills should consume this repo's domain documentation when ## Before exploring, read these - **`GLOSSARY.md`** at the repo root, or -- **`GLOSSARY-MAP.md`** at the repo root if it exists — it points at one `GLOSSARY.md` per context. Read each one relevant to the topic. -- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src//docs/adr/` for context-scoped decisions. +- **`GLOSSARY-MAP.md`** at the repo root if it exists: it points at one `GLOSSARY.md` per context. Read each one relevant to the topic. +- **`docs/adr/`**: read ADRs that touch the area you're about to work in. In multi-context repos, also check `src//docs/adr/` for context-scoped decisions. 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 (this repo): +Single-context repo (most repos): ``` / @@ -42,10 +42,10 @@ Multi-context repo (presence of `GLOSSARY-MAP.md` at the root): 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 `GLOSSARY.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`). +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: -> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_ +> _Contradicts ADR-0007 (event-sourced orders), but worth reopening because…_ diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md index 5de448a9..d2a0ad3a 100644 --- a/docs/agents/issue-tracker.md +++ b/docs/agents/issue-tracker.md @@ -11,7 +11,7 @@ Issues and specs for this repo live as GitHub issues. Use the `gh` CLI for all o - **Apply / remove labels**: `gh issue edit --add-label "..."` / `--remove-label "..."` - **Close**: `gh issue close --comment "..."` -**Always pass `--repo qiuyuzhou/ShadowsocksX-NG` explicitly on every `gh` command** (`view`/`edit`/`comment`/`close`/`create`/`api` alike). This clone has an `upstream` remote pointing at the original `shadowsocks/ShadowsocksX-NG`, and `gh`'s automatic inference can resolve there — writes to the upstream repo are forbidden. (An unqualified `gh issue comment` once posted a wayfinder resolution onto an upstream issue by mistake.) +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 @@ -23,7 +23,7 @@ When set to `yes`, PRs run through the same labels and states as issues, using t - **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`. +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" @@ -39,7 +39,7 @@ Used by `/wayfinder`. The **map** is a single issue with **child** issues as tic - **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. +- **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. +- **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.