Files

dtoro bb5c0717a1 docs: adopt wiki-hq conventions + separate agent instructions (phases 1-2)

Problem: the narrative docs lacked an enforceable style standard, and
agent-facing instruction (OIKOS/CAVEMAN/CONTRIBUTING) was interleaved with
human content at the repo root.

Change:
- Add .agents/shared/{writing-style,llm-wiki}.md — a lint-checkable prose
  standard (with an imperative-voice exception for runbooks/recipes) and the
  sources/wiki/index/log layer model.
- Move CAVEMAN.md -> .agents/shared/caveman.md,
  CONTRIBUTING.md -> .agents/shared/page-templates.md,
  OIKOS.md -> .agents/OIKOS.md; leave thin root stubs so old links resolve.
- Add .agents/domains/{knowledge,operations}/schema.md; operations schema
  codifies "plans always live in plans/".
- Repoint live references (AGENTS, README, GLOSSARY, OIKOS) and fix OIKOS.md's
  internal relative links for its new depth.

Risk: none to the operational substrate — inventory.yaml, hosts/*.yaml,
oikos/, mcp/, secrets/, bin/ untouched (verified via git status).

Verification: relative-link check across .agents/ clean; substrate churn empty.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-07-06 14:22:09 +02:00

2.1 KiB

Raw Blame History

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 live in runbooks/<name>.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.

2.1 KiB Raw Blame History