vac-optimizer/docs/agents/issue-tracker.md

Issue tracker: Gitea

Issues and specs live in nessar/vac-optimizer on Gitea. Use the configured tea-cli login for supported operations.

Access and command version

The installed binary is tea-cli 0.9.2. Its commands below use the pre-1.0 interface; other installations may call the binary tea. Check tea-cli --help and subcommand help before using commands from another version. This version supports YAML, TSV, CSV, simple, and table output; it has no JSON output, issue-edit command, or api command.

Run inside the clone so the CLI discovers the repository and login from origin. Use --repo nessar/vac-optimizer and --login <login-name> when an explicit selection is needed. Options go before positional issue or PR numbers. Existing authentication can be checked with tea-cli whoami; for a new login, use interactive tea-cli login add and select https://gitea.nessar.fr.

Conventions

• Create an issue: tea-cli issues create --title "..." --description "..." --labels "needs-triage". Multiple labels or assignees are comma-separated. For multiline text, prepare a draft and pass its contents as one quoted description argument.
• Read an issue: tea-cli issues --comments <number>. Detail views render for display even with --output yaml; use list output or the REST operations below for structured data.
• List issues: tea-cli issues --state open --labels "needs-triage" --fields index,title,body,state,labels,assignees,url --output yaml. Use --page and --limit to read all pages; the server may cap the requested page size.
• Comment: tea-cli comment <number> "..."; this works for issues and PRs.
• Apply / remove labels, edit a body, or assign: use the Gitea UI or the REST operations below; this CLI version does not support these edits. Preserve unrelated labels and assignees.
• Close: post the explanation with tea-cli comment <number> "...", then run tea-cli issues close <number>.
• Create a pull request: tea-cli pulls create --base develop --title "docs: update Gitea documentation" --description "...". Read with tea-cli pulls --comments <number>; list with tea-cli pulls --state open --output yaml.
• List milestones: tea-cli milestones --state all --fields id,title --output tsv. Issue numbers were preserved during migration, but milestone IDs changed; V1 stats is milestone 13.

REST operations for CLI gaps

The instance's API explorer and schema describe the supported endpoints. Paths below are relative to https://gitea.nessar.fr/api/v1; authenticate with an existing authorized Gitea API token without displaying or committing it. Check the installed CLI help first when it is upgraded.

• Read full issue data or comments as JSON: GET /repos/nessar/vac-optimizer/issues/<number> and GET /repos/nessar/vac-optimizer/issues/<number>/comments. Paginate comment lists.
• Find label IDs: GET /repos/nessar/vac-optimizer/labels; paginate and match exact names from triage-labels.md.
• Add labels: POST /repos/nessar/vac-optimizer/issues/<number>/labels with {"labels":[<label-id>]}. Remove one label: DELETE /repos/nessar/vac-optimizer/issues/<number>/labels/<label-id>. These operations preserve other labels.
• Edit a body or assign: PATCH /repos/nessar/vac-optimizer/issues/<number> with {"body":"..."} or {"assignees":["<username>"]}. Read current assignees before updating the list.
• Read a PR diff: GET /repos/nessar/vac-optimizer/pulls/<number>.diff.

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 enabled, use tea-cli pulls --comments <number> to read and tea-cli pulls --state open --fields index,title,body,author,labels,url --output yaml to list. Keep only external contributors' requests, checking repository collaborators or organization membership rather than guessing from the author's name. Comment with tea-cli comment, edit labels through the issue-label API, and close with tea-cli pulls close <number>.

For a bare #<number>, check the resource kind: tea-cli issues --kind all --fields index,kind,title,url --output yaml, or inspect the issue API's pull_request field. PR URLs use /pulls/<number>; issue URLs use /issues/<number>.

When a skill says "publish to the issue tracker"

Create a Gitea issue with tea-cli issues create.

When a skill says "fetch the relevant ticket"

Run tea-cli issues --comments <number> and read its labels and assignees.

Wayfinding operations

Used by /wayfinder. The map is a single issue with child issues as tickets.

• Map: create an issue labelled wayfinder:map, holding the Notes / Decisions-so-far / Fog body, with tea-cli issues create --title "..." --description "..." --labels "wayfinder:map".
• Child ticket: an issue carrying Part of #<map> at the top of its description and labels wayfinder:<type> (research/prototype/grilling/task). Maintain the ordered child links in the map's body. Once claimed, the ticket is assigned to the driving dev.
• Blocking: use Gitea's native dependencies. POST /repos/nessar/vac-optimizer/issues/<child>/dependencies with {"owner":"nessar","repo":"vac-optimizer","index":<blocker-number>} makes the child depend on that blocker. Read blockers with GET on the same path; use DELETE with the same body to remove a dependency. Where dependencies are unavailable, retain a Blocked by: #<n>, #<n> line at the top of the description. A ticket is unblocked when every blocker is closed.
• Frontier query: list the map's open children with tea-cli issues --state open --fields index,title,body,assignees,labels --output yaml, reading all pages. Drop tickets with an assignee or an open native dependency or description-line blocker; first in map order wins.
• Claim: assign the authenticated username through the issue PATCH endpoint or Gitea UI — the session's first write.
• Resolve: tea-cli comment <n> "<answer>", then tea-cli issues close <n>, then append a context pointer (gist + link) to the map's Decisions-so-far through the issue PATCH endpoint or Gitea UI.