Files

MDietermann 01e02b30b0 docs: Agent-Skills-Konfiguration fuer den Gitea-Tracker hinterlegen

Die Engineering-Skills (wayfinder, triage, to-tickets, to-spec) erwarten pro
Repo eine Tracker-Beschreibung. Hier ist das Gitea, nicht GitHub oder GitLab -
der Host heisst zwar gitlab.hive-brain.de, spricht aber die Gitea-API, also
tea statt glab.

Issue-Dependencies und Sub-Issues kann tea 0.15 nicht abbilden; beides ist in
der Doku als ungeprueft bzw. mit Body-Konvention als Fallback vermerkt, damit
keine Session sich auf ungetestete Kommandos verlaesst.

2026-08-27 14:17:06 +02:00

4.5 KiB

Raw Blame History

Issue tracker: Gitea (via `tea`)

Issues and specs for this repo live as Gitea issues at https://gitlab.hive-brain.de/RDietermann/dionotes-client.

The host is named gitlab.hive-brain.de, but the server is Gitea 1.25.5, not GitLab. glab will not work. Use the tea CLI (v0.15 installed).

Run tea from inside the clone — it resolves owner/repo from git remote. It prints NOTE: no login matched this repository, falling back to login 'hive' on every call; that is harmless. Add --login hive to silence ambiguity, or --repo RDietermann/dionotes-client when running from outside the clone.

Conventions

Create an issue: tea issues create --title "..." --description "..." --labels "a,b". Use a heredoc piped through a shell variable for multi-line descriptions — --description takes a single string, there is no -F file flag.
Read one issue: tea issues <index>. For machine-readable output or fields the CLI omits, use tea api repos/RDietermann/dionotes-client/issues/<index>.
List issues: tea issues ls --output json --fields index,title,state,labels,assignees,body with --labels, --assignee, --state filters as needed.
Read comments: tea comments ls <index>.
Comment on an issue: tea comments add <index> --description "...". (The subcommand is add, not create.)
Apply / remove labels: tea issues edit <index> --add-labels "a,b" / --remove-labels "a".
Assign: tea issues edit <index> --add-assignees RDietermann.
Close: tea issues close <index>. It takes no closing comment, so post the explanation first with tea comments add, then close.
Create a label (they are not auto-created): tea labels create --name "..." --color "#rrggbb".
Escape hatch: tea api <path> makes an authenticated call against the Gitea API for anything the CLI does not model. --method POST -d '<json>' for writes.

The auth token carries write:issue,write:repository,write:user — but not write:organization. Creating repos or issues under an org will fail; personal-account operations work.

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, using tea pulls ls, tea pulls <index>, and the same tea comments / tea issues edit commands — in Gitea, PRs share the issue index space, so #42 is either an issue or a PR, never both.

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> plus tea comments ls <index>.

Wayfinding operations

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

Map: an issue labelled wayfinder:map, holding the Destination / Notes / Decisions-so-far / Not-yet-specified / Out-of-scope body. tea issues create --title "..." --labels wayfinder:map --description "...".
Child ticket: an issue carrying Part of #<map> as the first line of its description, plus a wayfinder:<type> label (research / prototype / grilling / task). Gitea 1.24+ has native sub-issues, but tea does not expose them — the Part of #<map> line is the convention here, and Gitea renders it as a cross-reference on the map.
Blocking: Gitea has native issue dependencies, which is what renders the frontier in the web UI. tea does not wrap them, so use the API: tea api --method POST repos/RDietermann/dionotes-client/issues/<child>/dependencies -d '{"index": <blocker>}'. Read them back with tea api repos/RDietermann/dionotes-client/issues/<child>/dependencies. Unverified — the first session to wire a blocking edge should confirm this endpoint works and fix this line. If it does not, fall back to a Blocked by: #<n>, #<n> line at the top of the description. A ticket is unblocked when every blocker is closed.
Frontier query: tea issues ls --output json --labels wayfinder:grilling,wayfinder:research,wayfinder:prototype,wayfinder:task, keep those whose body says Part of #<map>, drop any with an assignee (claimed) or an open blocker; first in map order wins.
Claim: tea issues edit <index> --add-assignees RDietermann — the session's first write.
Resolve: tea comments add <index> --description "<answer>", then tea issues close <index>, then append a context pointer (gist + link) to the map's Decisions-so-far.

4.5 KiB Raw Blame History

Issue tracker: Gitea (via tea)