From 3d768181e3db27f0192403e7535b6f80ff916b7e Mon Sep 17 00:00:00 2001 From: Haylan Date: Mon, 24 Aug 2026 12:13:21 +0200 Subject: [PATCH] Set up agent skills config and chart wayfinder map for local AI stack Co-Authored-By: Claude Sonnet 5 --- CLAUDE.md | 9 +++++++ docs/agents/domain.md | 35 +++++++++++++++++++++++++ docs/agents/issue-tracker.md | 51 ++++++++++++++++++++++++++++++++++++ 3 files changed, 95 insertions(+) create mode 100644 CLAUDE.md create mode 100644 docs/agents/domain.md create mode 100644 docs/agents/issue-tracker.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..d16970e --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,9 @@ +## Agent skills + +### Issue tracker + +Issues live as Gitea issues on `git.arthurerlich.de` (repo `haylan/LLM-Server`); use the `tea` CLI (already authenticated) for all operations. See `docs/agents/issue-tracker.md`. + +### Domain docs + +Single-context: `CONTEXT.md` + `docs/adr/` at the repo root. See `docs/agents/domain.md`. diff --git a/docs/agents/domain.md b/docs/agents/domain.md new file mode 100644 index 0000000..fa4a6de --- /dev/null +++ b/docs/agents/domain.md @@ -0,0 +1,35 @@ +# 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, if it exists. +- **`docs/adr/`** — read ADRs that touch the area you're about to work in. + +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 + +Single-context repo (this repo): + +``` +/ +├── CONTEXT.md +├── docs/adr/ +│ ├── 0001-....md +│ └── 0002-....md +└── src/ +``` + +## 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..06503ea --- /dev/null +++ b/docs/agents/issue-tracker.md @@ -0,0 +1,51 @@ +# 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 --comments` +- **List issues**: `tea issues list --state open --labels "..."` (add `-f` to control which fields print) +- **Comment on an issue**: `tea comments create --description "..."` (check `tea comments -h` for exact flags) +- **Apply / remove labels**: `tea issues edit --add-labels "..."` / `--remove-labels "..."` +- **Close**: `tea issues close ` +- **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//dependencies" -H "Authorization: token $TOKEN" -H "Content-Type: application/json" -d '{"index": , "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 --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 (`- [ ] (#)`) and a `Part of #` line at the top of the child's body — sub-issues aren't available here. Labels: `wayfinder:` (`research`/`prototype`/`grilling`/`task`). Once claimed, assign it to the driving dev (`tea issues edit --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:,wayfinder:,..."` 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 --add-assignees haylan` — the session's first write. +- **Resolve**: `tea comments create --description ""`, then `tea issues close `, 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.