Issue tracker: Gitea

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

Repository context

Run commands from 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> explicitly. Use --repo <owner>/<repo> only when operating outside the clone.

Before the first operation, verify that the instance is configured with tea logins list --output json. If it is not, 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 / remove labels: tea issues edit <number> --add-labels "..." / --remove-labels "...". Comma-separate multiple labels.
Assign / unassign: tea issues edit <number> --add-assignees "..." / --remove-assignees "...".
Close: post any closing explanation first 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 not exposed by 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 to yes if this repo treats external pull requests as feature requests; /triage reads this flag.)

When set to yes, PRs run through 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 using the repository's Gitea membership data; the PR listing does not include an author-membership classification.
Comment: tea comments add <number> --description "...".
Apply / remove labels: tea pulls edit <number> --add-labels "..." / --remove-labels "...".
Close: tea pulls close <number>.

Gitea pull requests use the repository's issue index space, so a bare #42 may refer to either surface. If the context is unclear, inspect it with tea pulls 42 --output json; if that is not a 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

Used by /wayfinder. The map is a single issue with linked child issues as tickets. These conventions use ordinary issue bodies rather than instance/version-specific dependency APIs, so they work consistently across Gitea installations.

Map: a single issue labelled wayfinder:map, holding the Notes / Decisions-so-far / Fog body. Create it with tea issues create --labels "wayfinder:map" plus its title and description.
Child ticket: an issue with Part of #<map> at the top of its body and 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 is unblocked when every referenced blocker is closed.
Frontier query: list all open children, order them by the map's task list, and discard any ticket with an open blocker or an assignee. The first remaining ticket wins. Fetch referenced blockers explicitly; do not infer their state from stale 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 is accepted.
Resolve: tea comments add <n> --description "<answer>", then tea issues close <n>, then append a context pointer and link to the map's Decisions-so-far.

5.0 KiB Raw Blame History