Configure the engineering skills against this repo and this KB
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
This commit is contained in:
1 parent
6af3714bd0
commit
6f1f55345a
9 files changed
+254
No files matched your search
@@ -0,0 +1,51 @@
|
||||
---
|
||||
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.
|
||||
Reference in new issue
Block a user