LLM-Server/docs/agents/issue-tracker.md

Issue tracker: Gitea

Issues and specs for this repo live as Gitea issues on the self-hosted instance at git.arthurerlich.de (repo: haylan/LLM-Server).

Use the tea CLI (already installed and authenticated as haylan via tea login) for all operations — it's faster and needs no extra setup. Fall back to the gitea skill (Membrane-based) only for operations tea doesn't cover.

Conventions

• Create an issue: tea issues create --title "..." --description "..." --labels "..."
• Read an issue: tea issues <index> --comments
• List issues: tea issues list --state open --labels "..." (add -f to control which fields print)
• Comment on an issue: tea comments create <index> --description "..." (check tea comments -h for exact flags)
• Apply / remove labels: tea issues edit <index> --add-labels "..." / --remove-labels "..."
• Close: tea issues close <index>
• Labels: tea labels create --name "..." --color "#hex" --description "..."; tea labels list

tea infers the repo from the working directory's git remote; pass -r haylan/LLM-Server when running outside the repo.

Issue dependencies (native blocking)

tea has no dependency subcommand — use the raw API. Get a token from ~/.git-credentials (the git.arthurerlich.de line) or tea login list.

• Add a "blocked by" edge (child index is blocked by blocker index) — owner/repo in the body are required, index alone 404s: curl -s -X POST "https://git.arthurerlich.de/api/v1/repos/haylan/LLM-Server/issues/<child>/dependencies" -H "Authorization: token $TOKEN" -H "Content-Type: application/json" -d '{"index": <blocker>, "owner": "haylan", "repo": "LLM-Server"}'
• List dependencies: GET the same URL.
• Remove: DELETE the same URL with the same body.

Confirmed present and working on this instance (Gitea 1.27.2, enable_issue_dependencies: true; verified live against the map created by this skill's first run).

Pull requests as a triage surface

PRs as a request surface: no. (Set to yes if this repo treats external PRs as feature requests.)

When a skill says "publish to the issue tracker"

Create a Gitea issue via tea issues create.

When a skill says "fetch the relevant ticket"

Fetch the issue (with comments) via tea issues <index> --comments.

Wayfinding operations

Used by /wayfinder. This Gitea instance (1.27.2) has no native sub-issue/parent-child relation in its API (only dependencies, confirmed via swagger) — so the map uses the body-convention fallback the skill describes for that case. It does have native issue dependencies, used for blocking.

• Map: a single issue labelled wayfinder:map, holding the Notes / Decisions-so-far / Not-yet-specified body. tea issues create --labels "wayfinder:map" --title "..." --description "...".
• Child ticket: a plain issue, linked to the map via a task-list line in the map body (- [ ] <child title> (#<child>)) and a Part of #<map> line at the top of the child's body — sub-issues aren't available here. Labels: wayfinder:<type> (research/prototype/grilling/task). Once claimed, assign it to the driving dev (tea issues edit <n> --add-assignees haylan).
• Blocking: native issue dependencies via the raw API calls above. A ticket is unblocked when every dependency (GET .../dependencies) is closed.
• Frontier query: tea issues list --state open --labels "wayfinder:<type1>,wayfinder:<type2>,..." scoped to the map's children (cross-check against the map's task list), drop any with an open dependency or an assignee.
• Claim: tea issues edit <n> --add-assignees haylan — the session's first write.
• Resolve: tea comments create <n> --description "<answer>", then tea issues close <n>, then append a context pointer (gist + link) to the map's Decisions-so-far, and check off its line in the map's task list.