Frank
6f1f55345a
The Matt Pocock engineering skills (triage, to-tickets, to-spec, research, implement) assume per-repo config for three things: where work items live, what the triage label vocabulary is, and where domain docs sit. Nothing here declared any of them, so every skill run re-guessed. Frank's decisions, 2026-10-20: Gitea on Dankclaw as the tracker (no gh, no tea on any box, so it is recorded as prose — auth via a 600 curl config, the endpoint table, the 404-on-empty-token / form-encoded-merge / empty-200-on-merge traps, and the AGENTS.md laws a skill must not renegotiate); the canonical triage label vocabulary kept as-is, with the five labels created on the tracker (the repo had zero, so nothing collides); single-context domain docs. The configuration moved out of the skill's default docs/agents/ and into the one knowledge base this repo allows: three pages under omp-docs/skills/, an empty omp-docs/decisions/ carrying the ADR format rule, an "## Agent skills" pointer block in AGENTS.md, index entries, and a log entry. The glossary is deliberately not created — every candidate term already has an owner in system/, core/ or skills/, and a term list that paraphrases them is a second owner of facts already written down. Known cost: re-running setup-matt-pocock-skills will not recognise omp-docs/skills/* and will offer to recreate docs/agents/; the AGENTS.md pointer is what stops that. Also closes a verification gap found on the way: kb-lint.bats only ever points the linter at fixtures, so a page with no frontmatter or an index that stops listing a file passes the suite silently. Two tests now run the linter and the coverage checker against the shipped omp-docs/ tree. Refs #18
2.4 KiB
2.4 KiB
type, title, description, tags, timestamp
| type | title | description | tags | timestamp | ||||
|---|---|---|---|---|---|---|---|---|
| reference | Domain docs layout and consumer rules | Single-context domain documentation for dank/command-center — glossary and ADRs live inside the omp-docs knowledge base, not at the repo root. |
|
2026-10-20 |
Domain docs: single-context, inside the KB
One domain, one glossary, one ADR folder — and all of it inside the existing
knowledge base, because this repo caps its root at "config, docs, scripts,
harness dirs" and omp-docs/ is the one knowledge base. A docs/ tree at the
repo root would be a second KB with a second set of index rules, which is exactly
how documentation starts disagreeing with itself.
| Kind | Path | Status |
|---|---|---|
| Glossary | omp-docs/glossary.md |
deliberately not created yet |
| ADRs | omp-docs/decisions/NNN-<slug>.md, listed by its index.md |
directory exists, empty |
| Facts | the rest of omp-docs/ |
existing concept pages own them |
Consumer rules
- Read the KB index, then the relevant directory's
index.md, then the concept page. That is AGENTS.md's existing discipline; the engineering skills follow it instead of inventing a second entry point. - Read the ADRs that govern an area before changing that area, and write one the moment a decision stops being reversible. An ADR records the choice, the reasons, and what was rejected — the part that stops a later agent from re-litigating it.
- Do not confuse the neighbours. Research is decision support and explicitly not fact. log.md is chronology, where incident lessons land before settling into concept pages. An ADR is neither: it is the decision itself, dated, and it stays true after the code moves on.
- One fact, one owner. If a glossary term or an ADR sentence restates a concept page, the concept page wins and the duplicate is deleted.
Why the glossary is withheld
A glossary earns its bytes when it holds terms no other page owns. The obvious
candidates already have owners: host roles in system, agent
configuration in core, skill tiers in
skills. A term list that paraphrases those is a second owner
of facts already written down, and the first thing to go stale. Create
omp-docs/glossary.md when a real term has nowhere else to live, and list it in
the KB index the same commit you create it.