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.
This commit is contained in:
51
docs/agents/domain.md
Normal file
51
docs/agents/domain.md
Normal file
@@ -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/<context>/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…_
|
||||
79
docs/agents/issue-tracker.md
Normal file
79
docs/agents/issue-tracker.md
Normal file
@@ -0,0 +1,79 @@
|
||||
# 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`](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 <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.
|
||||
21
docs/agents/triage-labels.md
Normal file
21
docs/agents/triage-labels.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user