From f045d1bc9321890e8d930a333782394fcc3b0b2f Mon Sep 17 00:00:00 2001 From: ArthurErlich Date: Tue, 1 Sep 2026 20:58:56 +0200 Subject: [PATCH] chore: set up agent skills config (issue tracker, domain docs) Add AGENTS.md/CLAUDE.md agent-skills block, docs/agents/issue-tracker.md (Gitea via tea CLI) and docs/agents/domain.md (single-context layout). Co-Authored-By: Claude Sonnet 5 --- AGENTS.md | 9 +++++++ CLAUDE.md | 1 + docs/agents/domain.md | 51 ++++++++++++++++++++++++++++++++++++ docs/agents/issue-tracker.md | 39 +++++++++++++++++++++++++++ 4 files changed, 100 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 docs/agents/domain.md create mode 100644 docs/agents/issue-tracker.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..24b5174 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,9 @@ +## Agent skills + +### Issue tracker + +Issues live as Gitea issues on git.arthurerlich.de/haylan/Smart-Tablet-Screen, managed via the `tea` CLI. 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/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/docs/agents/domain.md b/docs/agents/domain.md new file mode 100644 index 0000000..b548c53 --- /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 + +Single-context repo (most repos): + +``` +/ +├── CONTEXT.md +├── docs/adr/ +│ ├── 0001-event-sourced-orders.md +│ └── 0002-postgres-for-write-model.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..2b61290 --- /dev/null +++ b/docs/agents/issue-tracker.md @@ -0,0 +1,39 @@ +# Issue tracker: Gitea + +Issues and specs for this repo live as Gitea issues on `git.arthurerlich.de/haylan/Smart-Tablet-Screen`. Use the `tea` CLI for all operations. + +## Conventions + +- **Create an issue**: `tea issues create -r haylan/Smart-Tablet-Screen --title "..." --description "..."` +- **Read an issue**: `tea issues view -r haylan/Smart-Tablet-Screen ` +- **List issues**: `tea issues list -r haylan/Smart-Tablet-Screen` +- **Comment on an issue**: `tea comment -r haylan/Smart-Tablet-Screen "..."` +- **Apply / remove labels, assignees, milestone**: `tea issues edit -r haylan/Smart-Tablet-Screen --add-labels "..." --add-assignees "..." ` (use `--remove-labels`/`--remove-assignees` to unset) +- **Close / reopen**: `tea issues close -r haylan/Smart-Tablet-Screen ` / `tea issues reopen -r haylan/Smart-Tablet-Screen ` + +Repo is inferred from `git remote -v` when running `tea` from the repo root; pass `-r haylan/Smart-Tablet-Screen` explicitly if inference fails. + +## Pull requests as a triage surface + +**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests; `/triage` reads this flag — not relevant yet since `triage` isn't installed.)_ + +When set to `yes`, use the `tea pulls` equivalents: `tea pulls view`, `tea pulls create`, `tea comment "..."`, `tea pulls merge`. + +## When a skill says "publish to the issue tracker" + +Create a Gitea issue with `tea issues create`. + +## When a skill says "fetch the relevant ticket" + +Run `tea issues view -r haylan/Smart-Tablet-Screen `. + +## Wayfinding operations + +Gitea has no native issue-dependency/blocking API (unlike GitHub/GitLab), so fall back to plain-text conventions: + +- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. +- **Child ticket**: an issue with `Part of #` at the top of its description, labelled `wayfinder:` (`research`/`prototype`/`grilling`/`task`). Once claimed, assign it to the driving dev. +- **Blocking**: a `Blocked by: #, #` line at the top of the description — no native link available. A ticket is unblocked when every blocker listed there is closed. +- **Frontier query**: `tea issues list -r haylan/Smart-Tablet-Screen`, scoped to the map's children, drop any with an open blocker in its `Blocked by` line or an assignee; first in map order wins. +- **Claim**: `tea issues edit -r haylan/Smart-Tablet-Screen --add-assignees "@me" ` — the session's first write. +- **Resolve**: `tea comment -r haylan/Smart-Tablet-Screen ""`, then `tea issues close -r haylan/Smart-Tablet-Screen `, then append a context pointer to the map's Decisions-so-far.