Tell the agents where the issues live: AGENTS.md and docs/agents/ #310

2026-08-18T19:32:29Z

enricobuehler commented

2026-08-18 19:32:29 +00:00

The mattpocock engineering skills — /triage, /to-tickets, /to-spec, /wayfinder, /diagnosing-bugs, /code-review — all read 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 a codebase. Absent that, each one guesses, and the guess is GitHub.

Which is wrong here in a way that fails quietly rather than loudly. Our remote is git.unom.io — Gitea. gh is installed on the machine and will run against github.com perfectly happily and find nothing at all; glab and tea aren't installed. An agent that reaches for the default comes back with an empty issue list and no error to explain it. So docs/agents/issue-tracker.md points at the connected gitea MCP server, and says so in its first line.

Two traps in that MCP surface earn their words:

Labels are written by numeric ID and read by name. issue_write takes labels as an array of numbers, remove_label takes a label_id — but list_issues filters on label names. Applying a label needs a label_read lookup first; passing the string gets you silently nowhere.
The repo has no labels at all. Checked both unom/punktfunk and the unom org — both empty. The first triage run has to create the five before it can apply any.

Gitea writes are outward-facing: a shared instance that mails on activity. The doc encodes that as a gate rather than a suggestion — reads are free, every write waits for a go-ahead, subagents included.

Domain docs

Single-context: one CONTEXT.md, one docs/adr/, both at the root. Neither exists yet, and docs/agents/domain.md explicitly tells agents not to flag that or create them 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 — a host captures, encodes and streams a session; a client decodes and presents it — and a glossary split four ways before it holds a single entry is just four empty files.

Why AGENTS.md

Neither AGENTS.md nor CLAUDE.md existed, so there was no house convention to follow. AGENTS.md is read by Claude Code and by the other tools too, and costs nothing extra here.

Scope

Four new files, 206 lines, all Markdown. No code, no build inputs, no CI surface touched. Generated by /setup-matt-pocock-skills; the three docs under docs/agents/ are meant to be hand-edited from here on — re-running the skill is only for switching trackers or starting over.

The mattpocock engineering skills — `/triage`, `/to-tickets`, `/to-spec`, `/wayfinder`, `/diagnosing-bugs`, `/code-review` — all read 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 a codebase. Absent that, each one guesses, and the guess is GitHub. Which is wrong here in a way that fails quietly rather than loudly. Our remote is git.unom.io — Gitea. `gh` is installed on the machine and will run against github.com perfectly happily and find nothing at all; `glab` and `tea` aren't installed. An agent that reaches for the default comes back with an empty issue list and no error to explain it. So `docs/agents/issue-tracker.md` points at the connected `gitea` MCP server, and says so in its first line. Two traps in that MCP surface earn their words: - **Labels are written by numeric ID and read by name.** `issue_write` takes `labels` as an array of numbers, `remove_label` takes a `label_id` — but `list_issues` filters on label *names*. Applying a label needs a `label_read` lookup first; passing the string gets you silently nowhere. - **The repo has no labels at all.** Checked both `unom/punktfunk` and the `unom` org — both empty. The first triage run has to create the five before it can apply any. Gitea writes are outward-facing: a shared instance that mails on activity. The doc encodes that as a gate rather than a suggestion — reads are free, every write waits for a go-ahead, subagents included. ### Domain docs Single-context: one `CONTEXT.md`, one `docs/adr/`, both at the root. Neither exists yet, and `docs/agents/domain.md` explicitly tells agents not to flag that or create them 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 — a host captures, encodes and streams a session; a client decodes and presents it — and a glossary split four ways before it holds a single entry is just four empty files. ### Why AGENTS.md Neither `AGENTS.md` nor `CLAUDE.md` existed, so there was no house convention to follow. `AGENTS.md` is read by Claude Code and by the other tools too, and costs nothing extra here. ### Scope Four new files, 206 lines, all Markdown. No code, no build inputs, no CI surface touched. Generated by `/setup-matt-pocock-skills`; the three docs under `docs/agents/` are meant to be hand-edited from here on — re-running the skill is only for switching trackers or starting over.

enricobuehler added 1 commit 2026-08-18 19:32:32 +00:00

docs(agents): AGENTS.md — where the issues live, what the labels mean, which docs to read first

ci / bun-nix (pull_request) Successful in 36s

Details

ci / docs-site (pull_request) Successful in 1m25s

Details

ci / web (pull_request) Successful in 1m29s

Details

ci / rust-arm64 (pull_request) Successful in 2m18s

Details

ci / rust (pull_request) Successful in 8m53s

Details

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.

enricobuehler merged commit cfbde6aec7 into main

2026-08-18 19:33:39 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: unom/punktfunk#310