shd.build/docs/agents/issue-tracker.md

Issue tracker: Gitea

Issues and specs for this repo live as Gitea issues. Use the tea CLI for all operations.

Repository context

Run commands inside the clone so tea can infer the repository and login from its Git remote. If the clone has multiple Gitea remotes or logins, pass --remote <name> or --login <name>. Use --repo <owner>/<repo> only outside the clone.

Before the first operation, verify the instance with tea logins list --output json. If it is missing, ask the user to run tea login add; never ask for or handle their access token.

Conventions

• Create an issue: tea issues create --title "..." --description "...". For a multi-line body, use shell command substitution around a quoted heredoc:

  tea issues create --title "..." --description "$(cat <<'EOF'
  Multi-line issue body.
  EOF
  )"
  

• Read an issue with comments: tea issues <number> --comments --fields index,state,author,url,title,body,assignees,labels,comments --output json.

• List issues: tea issues list --state open --fields index,state,author,url,title,body,assignees,labels,comments --output json, adding --labels "label-one,label-two", --assignee <user>, or another supported filter as needed. Paginate with --page and --limit; do not assume the default first 30 results are complete.

• Comment on an issue: tea comments add <number> --description "...".

• Apply or remove labels: tea issues edit <number> --add-labels "..." or --remove-labels "...". Separate multiple labels with commas.

• Assign or unassign: tea issues edit <number> --add-assignees "..." or --remove-assignees "...".

• Close: post the closing explanation with tea comments add <number> --description "...", then run tea issues close <number>.

• Reopen: tea issues reopen <number>.

• Raw API fallback: use tea api '<endpoint>' only for a Gitea feature without a first-class tea command. Prefer {owner} and {repo} placeholders so repository context remains explicit.

Use --output json for machine-readable reads. Do not scrape table output.

Pull requests as a triage surface

PRs as a request surface: no. (Set this to yes if this repo treats external pull requests as feature requests; /triage reads this flag.)

When set to yes, PRs use the same labels and states as issues:

• Read a PR with comments and diff: tea pulls <number> --comments --fields index,state,author,url,title,body,diff,assignees,labels,comments --output json.
• List open PRs: tea pulls list --state open --fields index,state,author,author-id,url,title,body,assignees,labels,comments --output json. Determine whether an author is external from the repository's Gitea membership data; the PR listing does not classify author membership.
• Comment: tea comments add <number> --description "...".
• Apply or remove labels: tea pulls edit <number> --add-labels "..." or --remove-labels "...".
• Close: tea pulls close <number>.

Gitea pull requests use the repository's issue index space, so #42 may refer to either surface. If the context is unclear, inspect it with tea pulls 42 --output json; if that command reports no PR, read it with tea issues 42 --output json.

When a skill says "publish to the issue tracker"

Create a Gitea issue with tea issues create.

When a skill says "fetch the relevant ticket"

Run tea issues <number> --comments --fields index,state,author,url,title,body,assignees,labels,comments --output json.

Wayfinding operations

/wayfinder uses one map issue with linked child issues. These conventions store relationships in issue bodies, so they work across Gitea versions.

• Map: create one issue labelled wayfinder:map containing the Notes, Decisions-so-far, and Fog sections. Use tea issues create --labels "wayfinder:map" with its title and description.
• Child ticket: start the body with Part of #<map> and apply a wayfinder:<type> label: research, prototype, grilling, or task. Add each child as a task-list item in the map body to preserve frontier order.
• Blocking: put Blocked by: #<n>, #<n> near the top of the child body. A ticket becomes unblocked after every referenced blocker closes.
• Frontier query: list all open children, order them by the map's task list, and discard tickets with an open blocker or an assignee. Select the first remaining ticket. Fetch each referenced blocker; do not infer its state from map text.
• Claim: resolve the active username with tea whoami, then run tea issues edit <n> --add-assignees "<username>" as the session's first write. Do not assume @me works.
• Resolve: run tea comments add <n> --description "<answer>", close the child with tea issues close <n>, then append a context pointer and link to the map's Decisions-so-far section.