Files

T

Frank 6f1f55345a 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

2026-10-20 16:13:44 -07:00

8.9 KiB

Raw Blame History

AGENTS.md — ~/.omp command center

System-configuration command center for Frank's fleet: agent config, knowledge base, small system utilities, and (soon) dotfiles. You — the reader — are probably an agent running on one of Frank's workstations with this repo as your working directory. Read omp-docs/index.md before you touch anything. This file is the operating contract; omp-docs/ is the knowledge base (OKF v0.1 format: directory of markdown files with YAML frontmatter, spec at omp-docs/references/okf-spec.md).

What this repo is

The live agent-config directory AND a git repo pushed to Gitea (dank/command-center on the Dankclaw instance). There is no staging copy: the checkout is the deployment. Branch switches swap live config files out from under the running agent — keep feature branches short-lived, and never end a work session checked out on anything but main.
Contents that belong here: AGENTS.md, omp-docs/ (knowledge base), scripts/ (small system utilities), agent/ + plugins/ (harness config and plugin manifests). Everything else under this directory is runtime state and is gitignored on principle — see .gitignore. History must mean "the configuration changed", not "the agent breathed".

Trunk-based SDLC (since 2026-10-18; replaces the old git-flow regime)

main is the only long-lived branch. Frank is the only dev; develop and the release-branch ceremony are retired — no develop, no back-merges, no release/X.Y.Z branches.
Before every work item: fetch and branch off the freshest origin/main. If main moves under you, merge it into your branch (never rebase — Frank dislikes the history rewrite).
Work item = Gitea issue on dank/command-center (Gitea at 192.168.0.143:3000, owner dank). Small fixes may go straight to a branch; anything with more than one moving part gets an issue first.
Branch naming: <type>/<issue#>-<slug>, type ∈ feat|fix|docs|chore.
Pull requests target main directly. Merge with --no-ff so feature arcs stay visible in history. Never merge a PR without an explicit OK from Frank.
The moment a PR is open, open it in Frank's browser — xdg-open <PR-URL> lands a tab in his Firefox; never make him hunt for it in Gitea.
Attribution footer (issues and PRs) — every issue or PR body you open ends with a --- line, then cwd: <working directory> · session: <omp session id> (session id from /status; cwd is that session's own working directory — not the build checkout, when they differ). Machine-made artifacts stay attributable to the box and session that spawned them.
Releases: tag vX.Y.Z straight on main after verifying; tags are the deploy markers every other machine pulls to. Hotfixes are ordinary branches off the tag you are fixing forward from.
Trash convention: never rm anything user-authored — move it to .AGENTTRASH/ (gitignored). Deletion is a pruning session with Frank present.

Commit hygiene (mirrors dank/serverAppConfigs)

The law is imported from the serverAppConfigs repo — checkout on the dev box at ~/Projects/serverAppConfig, see its AGENTS.md § Git Workflow and § Testing ("All edits flow through git", "tests are mandatory before commit"). Applied here:

git pull before starting new work; start from a clean tree. The checkout IS the deployment here — a dirty tracked file is a half-deployed config serving the live agent.
Commit atomically and early: one commit = one complete functional unit, never a pile of half-edited files; docs land in the same commit as the change they document.
bats tests/ green + the pre-commit secret gate = the commit precondition; the full suite runs at pre-push.
Push to the local Gitea as soon as a unit is green — every other workstation pulls from there. git * --no-verify is forbidden (the secret gate is the point of the hook).
Messages: imperative mood, what + why, Refs #N when a Gitea issue exists.

Live-sync tiers (the machine is a committer too — Refs #11)

The checkout is the deployment, so several tracked files are live state written continuously through symlinks by the harness, auto-learn, and desktop GUIs. "Dirty tree" is judged by the writer:

Tier	Paths	Commit law
Human/agent prose	`AGENTS.md`, `omp-docs/`, `scripts/`, `plugins/`, `agent/skills/`	branch → PR → Frank OK (unchanged)
Machine live	`agent/memories/`, `agent/managed-skills/`, `agent/config.yml`, `agent/models.yml`	`scripts/live-sync.sh` heartbeat
Desktop live	`dotfiles/`	same heartbeat

The heartbeat (systemd user timer, hourly) stages ONLY allowlisted tiers, commits with hooks armed — the secret gate included — merges origin/main, pushes, and reaps wt/* worktrees older than 7 days. Non-allowlist dirt is never committed, only surfaced. Conflicts abort and alert (ntfy); it never force-pushes, auto-resolves, or uses --no-verify. Details: omp-docs/tools/live-sync.md.

Agent skills

The engineering skills (triage, to-tickets, to-spec, research, implement, …) read their per-repo configuration from three pages in the knowledge base. Those pages own their facts; this is only the pointer.

Issue tracker

Work items are Gitea issues on dank/command-center (Dankclaw, 192.168.0.143:3000) — no gh, no tea. See omp-docs/skills/issue-tracker.md.

Triage labels

The five canonical roles, each label string equal to its name. See omp-docs/skills/triage-labels.md.

Domain docs

Single-context, inside the existing knowledge base: omp-docs/glossary.md and omp-docs/decisions/. See omp-docs/skills/domain-docs.md.

Secret gate (HARD rule)

The pre-commit hook (.githooks/pre-commit, enabled via git config core.hooksPath .githooks) scans every staged diff for live-secret shapes (sk-…, ghp_…, github_pat_…, glpat-…, xox…, AKIA…, PEM headers, JWTs) and blocks the commit. Quarantine list — never tracked, ever: auth.json, .env, trust.json, *.pem, *.key, identity*. Deliberate override: ALLOW_SECRETS=1 git commit …. Remember why: a secret in a tracked file is a secret in every agent's context window on every machine that pulls this repo.

Machine facts (verify before trusting)

box	role	GPU	notes
Dev workstation (`blankpad`)	client box, never runs inference	Lenovo laptop, AMD Ryzen 5 PRO 5650U / Cezanne APU (unified memory, s2idle sleep only, no dGPU)	this repo lives here at `~/.omp`; the earlier "iGPU + dGPU / `~/GitPackages/llama.cpp`" description belonged to the sold `dankware` box
Dankclaw	bench target, secondary models + service stack	Strix Halo APU (unified memory) + RTX 3090 (moved over from Dankserver 2026-09)	prod services `frank-dragoon` (halogen-flash-server, :7770, iGPU) and `frank-zealot` (llama.cpp PrismML fork, :7771, 3090); runbooks in the serverAppConfigs vault (`~/Projects/serverAppConfig/serverAppConfigs-docs/LLM/`); ssh: `ssh dankclaw`
Dankserver	main-model box	2× Radeon AI PRO R9700 — non-unified (was RTX 3090 until 2026-09)	runs `frank-archon` (radiance, TP=2, :7770) — this repo's operator session runs on it; ssh: `ssh dankserver`

Environment gotchas

Gitea API needs a token: GITEA_TOKEN env (gitignored .env). No tea CLI installed anywhere. Remote URLs carry NO embedded token (2026-10-09 credential-store cutover) — git and the API both read ~/.config/secrets/gitea (store --file, URL-line format; see omp-docs/tools/gitea/client-access.md). That file is never pushed; it is not a substitute for the secret gate.
Passwordless sudo (sudo -n) works on Dankclaw and Dankserver for systemctl verbs only; user units need no sudo at all.
SSH into both servers is BatchMode-capable from here: ssh -o BatchMode=yes dankclaw '<read-only command>' — read-only probes are always allowed; state changes on remote boxes are not, without a per-run OK.
frank-archon (Dankserver), frank-dragoon, and frank-zealot (Dankclaw) are production services shared with this repo's operator: never stop, mask, or restart them (or any production service on any box) without an explicit, current, per-run OK from Frank.

File-organization doctrine (why this repo stays readable)

One concept, one file; directories get an index.md listing their contents — that's the OKF contract, and it is also the anti-rot mechanism: nothing may appear in a directory that its index.md doesn't list.
Root of the repo is capped: config, docs, scripts, harness dirs. A new top-level entry requires a commit message that justifies itself.
Runtime state (dbs, logs, caches, sessions) is gitignored on principle — if you feel the urge to commit one of those, stop and reread this section.

8.9 KiB Raw Blame History Unescape Escape