enricobuehler
0eb8f2d0f1
The mattpocock engineering skills (/triage, /to-tickets, /to-spec, /wayfinder,
/diagnosing-bugs, /code-review) all assume a per-repo configuration that this
repo never had: they need to know which tracker to talk to, which label strings
carry the five triage roles, and which docs to read before exploring. Without it
each of them guesses, and the guess is GitHub.
Which is wrong here in a way that fails quietly. This repo's remote is
git.unom.io — Gitea. `gh` is installed on the machine and will happily run
against github.com and find nothing; `glab` and `tea` are not installed at all.
So the tracker doc points at the connected `gitea` MCP server instead, and says
so in the first line, because the failure mode is an agent confidently reporting
an empty issue list.
Two traps in that MCP surface are worth the words they take:
- `issue_write` applies labels by numeric ID and `remove_label` takes a
`label_id`, while `list_issues` filters by label *name*. Applying a label
therefore needs a `label_read` lookup first — passing the name silently
gets you nowhere.
- unom/punktfunk has no labels defined at all, on the repo or on the org
(checked both). The first triage run has to create the five before it can
apply any of them.
Gitea writes are outward-facing — a shared instance that mails on activity — so
the doc encodes the standing rule as a gate: reads are free, every write waits
for a go-ahead, subagents included.
Domain docs are single-context: one CONTEXT.md and one docs/adr/ at the root.
Neither exists yet and neither should be created pre-emptively; /domain-modeling
writes them when a term or a decision actually gets resolved. Twenty-seven
crates and nine client platforms is the shape of a repo that eventually wants a
CONTEXT-MAP.md, so the switch path is written down — but they serve one domain
today, and a glossary split four ways before it has a single entry is just four
empty files.
AGENTS.md rather than CLAUDE.md because neither existed, and the cross-tool
convention costs nothing here.
2.3 KiB
Domain Docs
How the engineering skills should consume this repo's domain documentation when exploring the codebase.
This is a single-context repo: one CONTEXT.md and one docs/adr/ at the root, covering the
whole workspace.
Before exploring, read these
CONTEXT.mdat the repo root.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.
Neither file exists yet — that is expected, and not something to fix pre-emptively.
File structure
/
├── CONTEXT.md
├── docs/adr/
│ ├── 0001-....md
│ └── 0002-....md
├── crates/ ← Rust workspace members (host, capture, encode, decode, presenter, …)
├── clients/ ← per-platform clients (android, apple, linux, cli, decky, …)
├── web/ ← web console
├── sdk/
└── plugin-kit/
The code is split across many crates and client platforms, but they serve one domain — a host
captures, encodes, and streams a session to a client that decodes and presents it. Keep the
glossary unified across them rather than splitting per directory. If a genuinely separate domain
appears later, switch to a root CONTEXT-MAP.md pointing at per-context CONTEXT.md files and
update this file.
docs/ already holds release notes (docs/releases/) — those are not domain docs, and ADRs sit
alongside them in docs/adr/, not inside them.
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…