From 01e02b30b0576344c1146bb92e63b0d2fa11e697 Mon Sep 17 00:00:00 2001 From: MDietermann Date: Thu, 27 Aug 2026 14:17:06 +0200 Subject: [PATCH] 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. --- AGENTS.md | 14 +++++++ docs/agents/domain.md | 51 +++++++++++++++++++++++ docs/agents/issue-tracker.md | 79 ++++++++++++++++++++++++++++++++++++ docs/agents/triage-labels.md | 21 ++++++++++ 4 files changed, 165 insertions(+) create mode 100644 docs/agents/domain.md create mode 100644 docs/agents/issue-tracker.md create mode 100644 docs/agents/triage-labels.md diff --git a/AGENTS.md b/AGENTS.md index 0f3190b..ab8fe2d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -263,3 +263,17 @@ The initial UI rendered by the component on the client must be identical to the * Use the `use_server_future` hook instead of `use_resource`. It runs the future on the server, serializes the result, and sends it to the client, ensuring the client has the data immediately for its first render. * Any code that relies on browser-specific APIs (like accessing `localStorage`) must be run *after* hydration. Place this code inside a `use_effect` hook. + +## Agent skills + +### Issue tracker + +Gitea-Issues auf gitlab.hive-brain.de (trotz des Hostnamens kein GitLab), bedient über die `tea`-CLI. Siehe `docs/agents/issue-tracker.md`. + +### Triage labels + +Die fünf kanonischen Standard-Labels, unverändert. Siehe `docs/agents/triage-labels.md`. + +### Domain docs + +Single-context: `CONTEXT.md` + `docs/adr/` im Repo-Root. Siehe `docs/agents/domain.md`. diff --git a/docs/agents/domain.md b/docs/agents/domain.md new file mode 100644 index 0000000..cc9350e --- /dev/null +++ b/docs/agents/domain.md @@ -0,0 +1,51 @@ +# Domain Docs + +How the engineering skills should consume this repo's domain documentation when exploring the codebase. + +## Before exploring, read these + +- **`CONTEXT.md`** at the repo root, or +- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic. +- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src//docs/adr/` for context-scoped decisions. + +If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved. + +## File structure + +This repo is **single-context**: + +``` +/ +├── CONTEXT.md +├── docs/adr/ +│ ├── 0001-....md +│ └── 0002-....md +└── src/ +``` + +Multi-context repo (presence of `CONTEXT-MAP.md` at the root): + +``` +/ +├── CONTEXT-MAP.md +├── docs/adr/ ← system-wide decisions +└── src/ + ├── ordering/ + │ ├── CONTEXT.md + │ └── docs/adr/ ← context-specific decisions + └── billing/ + ├── CONTEXT.md + └── docs/adr/ +``` + +## Use the glossary's vocabulary + +When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids. + +If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`). + +## Flag ADR conflicts + +If your output contradicts an existing ADR, surface it explicitly rather than silently overriding: + +> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_ diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md new file mode 100644 index 0000000..3779f6a --- /dev/null +++ b/docs/agents/issue-tracker.md @@ -0,0 +1,79 @@ +# Issue tracker: Gitea (via `tea`) + +Issues and specs for this repo live as **Gitea** issues at +. + +> 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`](https://gitea.com/gitea/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 `. For machine-readable output or fields the CLI + omits, use `tea api repos/RDietermann/dionotes-client/issues/`. +- **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 `. +- **Comment on an issue**: `tea comments add --description "..."`. + (The subcommand is `add`, not `create`.) +- **Apply / remove labels**: `tea issues edit --add-labels "a,b"` / `--remove-labels "a"`. +- **Assign**: `tea issues edit --add-assignees RDietermann`. +- **Close**: `tea issues close `. 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 ` makes an authenticated call against the Gitea API for + anything the CLI does not model. `--method POST -d ''` 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 `, 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 ` plus `tea comments ls `. + +## 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 #` as the first line of its description, + plus a `wayfinder:` label (`research` / `prototype` / `grilling` / `task`). + Gitea 1.24+ has native sub-issues, but `tea` does not expose them — the `Part of #` + 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//dependencies -d '{"index": }'`. + Read them back with `tea api repos/RDietermann/dionotes-client/issues//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: #, #` 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 #`, drop any with an assignee (claimed) or an open + blocker; first in map order wins. +- **Claim**: `tea issues edit --add-assignees RDietermann` — the session's first write. +- **Resolve**: `tea comments add --description ""`, then + `tea issues close `, then append a context pointer (gist + link) to the map's + Decisions-so-far. diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.md new file mode 100644 index 0000000..dc04f4a --- /dev/null +++ b/docs/agents/triage-labels.md @@ -0,0 +1,21 @@ +# Triage Labels + +The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker. + +| Label in mattpocock/skills | Label in our tracker | Meaning | +| -------------------------- | -------------------- | ---------------------------------------- | +| `needs-triage` | `needs-triage` | Maintainer needs to evaluate this issue | +| `needs-info` | `needs-info` | Waiting on reporter for more information | +| `ready-for-agent` | `ready-for-agent` | Fully specified, ready for an AFK agent | +| `ready-for-human` | `ready-for-human` | Requires human implementation | +| `wontfix` | `wontfix` | Will not be actioned | + +When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table. + +Labels are not created automatically. Create a missing one with: + +```bash +tea labels create --name needs-triage --color "#ededed" --description "Maintainer needs to evaluate this issue" +``` + +Edit the right-hand column to match whatever vocabulary you actually use.