dtoro
5c5016b3c7
Problem: runbooks are agent-executable procedures but lived at the repo root, separate from the other agent instruction now under .agents/. Change: - Move runbooks/<name>.md -> .agents/skills/<name>/SKILL.md (folder per skill, matching the wiki-hq skills layout). Frontmatter (name, risk_class, inputs, verification, docs_update_checklist, transition) preserved. - Rewrite links (inbound from plans; between-skill siblings) via the move map. - Update prose references in AGENTS.md, HERMES.md, .agents/OIKOS.md, and the operations schema; fix a pre-existing stale link to operations/commands.md. No code consumed runbooks/ by path, so nothing else changes. Verification: all SKILL.md frontmatter parses with valid risk_class; every lifecycle transition resolves to an oikos/ontology.yaml state; broken-link count 127 -> 126 (fixed one, introduced none). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2.2 KiB
Operations domain — schema
The operations domain holds the procedural and time-stamped documentation: runbooks (repeatable procedures), investigations (incident evidence), and plans (design docs for non-trivial work). It follows writing-style; runbooks and plans use the imperative voice exception.
Plans always live in plans/
Any plan or design doc for the Homelab is written into the repo plans/ folder as
plans/YYYY-MM-DD-slug.md — never a scratch path, an agent-private plan location, or a chat
message. An agent drafting a plan:
- Writes the file under
plans/using the plan template in page-templates.md. - Lists it in
plans/index.md. - On completion, moves it to
plans/done/and updates the index status.
This is the single source for homelab design intent; keeping it in-repo means the plan is
versioned, reviewable, and reachable by MCP get_page/search_docs like any other doc.
Runbooks
Repeatable procedures are skills — one folder per skill at .agents/skills/<name>/SKILL.md, with
YAML front-matter that the Oikos policy and lifecycle machinery reads:
---
name: <name>
risk_class: read_only | reversible_low | config_mutation | destructive
inputs: [<param>, ...]
verification: "<shell expression that proves success>"
docs_update_checklist: [<doc artifacts to update>]
transition: "<from> -> <to>" # only for lifecycle runbooks
---
risk_class values and the lifecycle transition states must match
oikos/policy.yaml and oikos/ontology.yaml.
Investigations
Incident records live in investigations/YYYY-MM-DD-slug.md and are evidence sources — written
once at incident time, then linked from the changelogs of the nodes they implicate. Sections:
## Summary, ## Timeline, ## Root cause, ## Mitigations applied, ## Open questions. Resolved
incidents move to investigations/archive/.
The operations log
plans/log.md and investigations/log.md are append-only records of documentation operations on
those areas (## [YYYY-MM-DD] <op> | <summary>), distinct from the Oikos change ledger.