From 1b5398afdce0ad069c4962c3ee89728abad8e1aa Mon Sep 17 00:00:00 2001 From: Steve Beaulac Date: Thu, 9 Jul 2026 12:51:58 -0400 Subject: [PATCH] docs(setup-skills): add wayfinder operations and update skill references - Add wayfinding operations section to all issue tracker backends (GitHub, GitLab, Gitea) - Update skill names from `to-issues`/`to-prd` to `to-tickets`/`to-spec` - Fix Gitea CLI reference from `gitea` to `tea` - Fix ADR path from `adr` to `docs/adr` - Fix various typos and whitespace issues in Gitea tracker docs --- common/engineering/setup-skills/SKILL.md | 4 ++-- .../setup-skills/issue-tracker-gitea.md | 22 ++++++++++++++----- .../setup-skills/issue-tracker-github.md | 11 ++++++++++ .../setup-skills/issue-tracker-gitlab.md | 11 ++++++++++ docs/agents/issue-tracker.md | 11 ++++++++++ 5 files changed, 51 insertions(+), 8 deletions(-) diff --git a/common/engineering/setup-skills/SKILL.md b/common/engineering/setup-skills/SKILL.md index e7a12a2..bc0dd6e 100644 --- a/common/engineering/setup-skills/SKILL.md +++ b/common/engineering/setup-skills/SKILL.md @@ -35,7 +35,7 @@ Assume the user does not know what these terms mean. Each section starts with a Section A - Issue tracker: -> Explainer: The "issue tracker" is where issues live for this repo. Skills like `to-issues`, `triage`, `to-prd`, and `qa` read from and write to it — they need to know whether to call `gh issue create`, write a markdown file under `.scratch/`, or follow some other workflow you describe. Pick the place you actually track work for this repo. +> Explainer: The "issue tracker" is where issues live for this repo. Skills like `to-tickets`, `triage`, `to-spec`, and `qa` read from and write to it — they need to know whether to call `gh issue create`, write a markdown file under `.scratch/`, or follow some other workflow you describe. Pick the place you actually track work for this repo. Default posture: these skills were designed for GitHub. If a `git remote` points at GitHub, propose that. If a `git remote` points at GitLab (`gitlab.com` or a self-hosted host), propose GitLab. If a `git remote` point at a Gitea (a self-hosted host with a `gitea` in the url). Otherwise ask the user, offer: @@ -64,7 +64,7 @@ Default: each role's string equals its name. Ask the user if they want to overri Confirm the layout: -- **Single-context** — one `CONTEXT.md` + `adr` at the repo root. Most repos are this. +- **Single-context** — one `CONTEXT.md` + `docs/adr` at the repo root. Most repos are this. - **Multi-context** — `CONTEXT-MAP.md` at the root pointing to per-context `CONTEXT.md` files (typically a monorepo). **Section D — ADR wiki.** diff --git a/common/engineering/setup-skills/issue-tracker-gitea.md b/common/engineering/setup-skills/issue-tracker-gitea.md index 527e50a..2dde47d 100644 --- a/common/engineering/setup-skills/issue-tracker-gitea.md +++ b/common/engineering/setup-skills/issue-tracker-gitea.md @@ -1,6 +1,6 @@ # Issue tracker: Gitea -Issues and PRDs for this repo live as Gitea issues. Use the `gitea` CLI for all operations. +Issues and PRDs for this repo live as Gitea issues. Use the `tea` CLI for all operations. ## Conventions @@ -8,7 +8,7 @@ Issues and PRDs for this repo live as Gitea issues. Use the `gitea` CLI for all - **Read an issue**: `tea issue --comments`. Use `-o json` for machine-readable output. - **List issues**: `tea issue list --state open -o json` with appropriate `--labels` and `--state` filters. - **Comment on an issue**: `tea comment "..."`. -- **Apply / remove labels**: `tea issue edit --add-label "..."` / `--remove-label "..."`. Multiple labels can be comma-separated or by repeating the flag.les +- **Apply / remove labels**: `tea issue edit --add-label "..."` / `--remove-label "..."`. Multiple labels can be comma-separated or by repeating the flag. - **Close**: `tea issue close `. `tea issue close` does not accept a closing comment, so post the explanation first with `tea comment "..."`, then close. Infer the repo from git remote -v — `tea` does this automatically when run inside a clone. @@ -17,11 +17,10 @@ Infer the repo from git remote -v — `tea` does this automatically when run ins **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: +When set to `yes`, PRs run through the same labels and states as issues, using the `tea pr` equivalents: -- **Read a PR**: `tea pr --comments` and `tea api /repos/{owner}/{repo}/pulls/.diff` for the diff. - -- **List external PRs for triage**: `tea pr list --state open -o json ` then keep only PRs whose author is not a project member/owner (a contributor's MR, not a maintainer's in-flight work). +- **Read a PR**: `tea pr --comments` and `tea api /repos/{owner}/{repo}/pulls/.diff` for the diff. +- **List external PRs for triage**: `tea pr list --state open -o json` then keep only PRs whose author is not a project member/owner (a contributor's MR, not a maintainer's in-flight work). - **Comment / label / close**: `tea comment "..."`, `tea pr edit --add-label`/`--remove-label`, `tea pr close`. Gitea shares one number space across issues and PRs, so a bare `#42` may be either — resolve with `tea pr 42` and fall back to `tea issue 42`. @@ -33,3 +32,14 @@ Create a Gitea issue. ## When a skill says "fetch the relevant ticket" Run `tea issue --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. `tea issue create --label wayfinder:map`. +- **Child ticket**: an issue linked to the map as a GitHub sub-issue (`tea 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 `tea api --method POST /repos/{owner}/{repo}/issues//dependencies -F index= -F repo= -F owner=`, where `` is the blocker's numeric **issue number** (`tea api repos/{owner}/{repo}/issues/ --jq ".number. .repository.name, .repository.owner"`, where `.number` is the ``, `.repository.name` is the `` and `.repository.owner` is the ``. 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 dependencies (`tea api /repos/{owner}/{repo}/issues//dependencies | jq '.[] | select(.state = "open") .number'`, scoped to the map's sub-issues / task list), drop any with an open blocker (`list of dependencies is not empty`, or an open issue in the `Blocked by` line) or an assignee; first in map order wins. +- **Claim**: `tea issue edit --add-assignees @me` — the session's first write. +- **Resolve**: `tea comments ""`, then `tea issue close `, then append a context pointer (gist + link) to the map's Decisions-so-far. diff --git a/common/engineering/setup-skills/issue-tracker-github.md b/common/engineering/setup-skills/issue-tracker-github.md index 53ad3ec..82cfbf5 100644 --- a/common/engineering/setup-skills/issue-tracker-github.md +++ b/common/engineering/setup-skills/issue-tracker-github.md @@ -32,3 +32,14 @@ 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. diff --git a/common/engineering/setup-skills/issue-tracker-gitlab.md b/common/engineering/setup-skills/issue-tracker-gitlab.md index 2c6cf58..8a54714 100644 --- a/common/engineering/setup-skills/issue-tracker-gitlab.md +++ b/common/engineering/setup-skills/issue-tracker-gitlab.md @@ -33,3 +33,14 @@ Create a GitLab issue. ## When a skill says "fetch the relevant ticket" Run `glab 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. `glab issue create --label wayfinder:map`. (On GitLab tiers with native epics, an epic may hold the map instead; a labelled issue works everywhere.) +- **Child ticket**: an issue carrying `Part of #` at the top of its description and labels `wayfinder:` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev. +- **Blocking**: GitLab's **native blocking link** — the canonical, UI-visible representation. Add it with the `/blocked_by #` quick action, posted as a note (`glab issue note --message "/blocked_by #"`). Native blocking links are a Premium/Ultimate feature; on the free tier (or where unavailable) fall back to a `Blocked by: #, #` line at the top of the description. A ticket is unblocked when every blocker is closed. +- **Frontier query**: `glab issue list -F json` scoped to the map's children, drop any with an open blocker — a native `blocked_by` link to an open issue (`glab api projects/:id/issues/:iid/links`), or an open issue in the `Blocked by` line — or an assignee; first in map order wins. +- **Claim**: `glab issue update --assignee @me` — the session's first write. +- **Resolve**: `glab issue note --message ""`, then `glab issue close `, then append a context pointer (gist + link) to the map's Decisions-so-far. diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md index ca7ebfe..3f74fcc 100644 --- a/docs/agents/issue-tracker.md +++ b/docs/agents/issue-tracker.md @@ -32,3 +32,14 @@ Create a Gitea issue. ## When a skill says "fetch the relevant ticket" Run `tea issue --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. `tea issue create --label wayfinder:map`. +- **Child ticket**: an issue linked to the map as a GitHub sub-issue (`tea 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 `tea api --method POST /repos/{owner}/{repo}/issues//dependencies -F index= -F repo= -F owner=`, where `` is the blocker's numeric **issue number** (`tea api repos/{owner}/{repo}/issues/ --jq ".number. .repository.name, .repository.owner"`, where `.number` is the ``, `.repository.name` is the `` and `.repository.owner` is the ``. 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 dependencies (`tea api /repos/{owner}/{repo}/issues//dependencies | jq '.[] | select(.state = "open") .number'`, scoped to the map's sub-issues / task list), drop any with an open blocker (`list of dependencies is not empty`, or an open issue in the `Blocked by` line) or an assignee; first in map order wins. +- **Claim**: `tea issue edit --add-assignees @me` — the session's first write. +- **Resolve**: `tea comments ""`, then `tea issue close `, then append a context pointer (gist + link) to the map's Decisions-so-far.