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
52 lines
2.4 KiB
Markdown
52 lines
2.4 KiB
Markdown
---
|
|
type: reference
|
|
title: Domain docs layout and consumer rules
|
|
description: Single-context domain documentation for dank/command-center — glossary and ADRs live inside the omp-docs knowledge base, not at the repo root.
|
|
tags:
|
|
- skills
|
|
- documentation
|
|
- okf
|
|
- agents
|
|
timestamp: 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
|
|
|
|
1. Read [the KB index](/index.md), 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.
|
|
2. 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.
|
|
3. Do not confuse the neighbours. [Research](/research/index.md) is decision
|
|
*support* and explicitly not fact. [log.md](/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.
|
|
4. 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](/system/index.md), agent
|
|
configuration in [core](/core/index.md), skill tiers in
|
|
[skills](/skills/index.md). 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.
|