ImageApi/docs/agents/issue-tracker.md

Issue tracker: Gitea (self-hosted)

Issues and specs for this repo live as issues on Gitea (https://git.crkc.xyz/Apps/ImageApi). Use the tea CLI for all operations.

Conventions

• Create an issue: tea issues create --title "..." --description-file - (read the body from a heredoc on stdin), or --description "..." for a one-liner. Add labels at creation with --labels "..." (the labels must already exist — see below).
• Read an issue: tea issues <index> --comments. Use tea issues list -f index,title,body,labels,comments -o json for machine-readable output.
• List issues: tea issues list --state open (default state is open) with appropriate --labels / --keyword filters.
• Comment on an issue: tea comments add <index> "..." (alias: tea comments <index> "...").
• Apply / remove labels: tea issues edit <index> --add-labels "..." / --remove-labels "...".
• Labels must exist first. Neither issues create --labels nor issues edit --add-labels creates a missing label: an unknown name is silently dropped — the command succeeds and the issue ends up unlabelled (verified against this server, tea 0.16). Check with tea labels list; create with tea labels create --name "..." --color "#rrggbb" --description "...", then apply. After labelling, confirm it stuck (tea issues <index>). The triage labels (triage-labels.md) exist; the wayfinder:* labels below must be created before first use.
• Close: tea issues close <index>. It does not accept a closing comment, so post the explanation first with tea comments add <index> "...", then close.
• Raw API access (for anything the tea subcommands don't cover): tea api <endpoint> makes an authenticated request to the Gitea API (prefixes /api/v1/ when the path doesn't start with /api/). Placeholders {owner} and {repo} are replaced from the current repo context. Use -F for typed fields (numbers, booleans) and -d for raw JSON bodies.

Infer the repo from the git remote (-R lets tea discover the Gitea login from the remote); tea does this automatically when run inside a clone. Confirm the acting user with tea whoami.

Unlike GitHub, Gitea numbers issues and pull requests separately, so a bare #42 is unambiguous once you know which surface it refers to.

Pull requests as a triage surface

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 tea pulls equivalents (tea pulls list/view/edit, tea pulls close, plus tea comments which covers PRs). Keep only PRs from outside collaborators (drop the repo owner and team members) when listing external PRs for triage.

When a skill says "publish to the issue tracker"

Create a Gitea issue.

When a skill says "fetch the relevant ticket"

Run tea issues <index> --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 issues create --title "..." --labels wayfinder:map --description-file -.
• Child ticket: an issue carrying Part of #<map> at the top of its description, labelled wayfinder:<type> (research/prototype/ grilling/task). Once claimed, the ticket is assigned to the driving dev.
• Blocking: Gitea's native issue dependencies (enabled on this server), the canonical, UI-visible representation. Add an edge with tea api --method POST repos/{owner}/{repo}/issues/<child>/dependencies -d '{"index": <blocker-index>, "owner": "<owner>", "repo": "<repo>"}' (201 on success). Gotchas, verified against Gitea 1.27:
  • The route is .../dependencies — there is no blocked_by subpath (that 404s).
  • The JSON body must name the blocker's repo (owner + repo); omitting them yields a misleading 404 repository does not exist even though the child's path is correct.
  • index is the visible #number, not an internal database id. Verify with tea api repos/{owner}/{repo}/issues/<child>/dependencies (lists blockers); remove with --method DELETE and the same body. Where dependencies aren't available, fall back to a Blocked by: #<n>, #<n> line at the top of the child description. A ticket is unblocked when every blocker is closed.
• Frontier query: list the map's open children (issues whose description carries Part of #<map>), drop any with an open blocker (dependency or Blocked by line) or an assignee; first in map order wins.
• Claim: tea issues edit <n> --add-assignees <username> (the session's first write; <username> from tea whoami).
• Resolve: tea comments add <n> "<answer>", then tea issues close <n>, then append a context pointer (gist + link) to the map's Decisions-so-far.