home-network-k3s/AGENTS.md

AGENTS.md — Rules of Engagement

This file governs how AI agents (and their human reviewers) work inside this repository. Read it fully before making any change. These rules override any conflicting default behavior.

Two governing constraints, above all others:

1. You may not change the specifications. The docs/ tree, the requirements, and accepted ADRs are human-owned and immutable to agents (R-TEST-06). You implement against them and prove conformance; you never edit them to fit your implementation. See §2 and §11.
2. Conformance is proven only by automated, reproducible behavior tests. "Done" means a green, requirement-tagged conformance test — never "merged," never a manual demo (R-TEST-01..05). See §7 and docs/14-testing-and-conformance.md.

1. This repository defines intent, not implementation (yet)

Today this repo contains specifications only. Implementation artifacts (Helm values, Flux Kustomizations, KubeVirt manifests, OpenTofu/Ansible IaC, etc.) will be added under an implementation/ tree only after the corresponding spec and ADRs are approved. Until then:

• Do not invent implementation details that contradict the specs or ADRs.
• Do not create the implementation/ tree until the roadmap phase that authorizes it is active (see roadmap/phases.md).
• When you implement, the spec is the acceptance criteria. If the spec is wrong, blocking, ambiguous, or missing, you may not fix it yourself — stop and escalate to the human operator/ architect (§2, §11). You may draft a proposal; you may not merge a spec change.

2. The source-of-truth hierarchy

When two documents conflict, the higher item wins:

1. docs/00-vision-and-scope.md — requirements (R-* IDs)
2. Approved ADRs in decisions/ — locked technology & pattern choices
3. Domain specs in docs/
4. roadmap/ and agents/ — sequencing and coordination
5. Implementation code (once it exists)

If you find a conflict, stop and escalate it to the human operator/architect — do not silently pick one interpretation, and do not resolve it by editing the specs yourself (you may not change them, §11). Wait for the human to amend the spec, then implement against the amended spec.

3. Do not re-litigate decisions

Every major choice (k3s, Cilium, Longhorn, KubeVirt, Flux, SOPS, cert-manager, etc.) is captured in an ADR with rationale and rejected alternatives. If new information genuinely invalidates a decision:

1. Draft a proposed superseding ADR and escalate to the human operator/architect — you may not merge it yourself (ADRs are specifications; §11 forbids agents changing them).
2. State what changed and why.
3. Only the human approves/accepts it. Implement against the new decision only after it is accepted.

Never edit an accepted ADR's decision in place. ADRs are an append-only, human-approved ledger.

4. Requirement traceability is mandatory

• Every requirement has a stable ID like R-NET-01.
• Every ADR lists the requirement IDs it serves.
• Every task-board item lists the requirement IDs it satisfies.
• Every implementation PR references the requirement IDs and the spec sections it fulfills.

If you cannot trace a piece of work to a requirement, either it is out of scope or a requirement is missing — surface it, don't proceed silently.

5. GitOps-first, click-ops-never

• The desired state of the cluster lives in git and is reconciled automatically.
• Manual changes to the running cluster are prohibited except where an ADR explicitly carves out an exception (e.g. a bootstrap step, an out-of-band edge-router config). Such exceptions must be documented and, where possible, later folded back into IaC.
• Secrets live in git encrypted (SOPS + age). Never commit plaintext secrets. Never print a decrypted secret into logs, PR descriptions, or agent output.

6. Two environments, one configuration

• Author configuration so dev/test and prod differ only by environment-scoped overrides (replica counts, node selectors, storage sizes, WAN endpoints, DNS zones).
• Never fork the base configuration per environment. Use overlays/variables.
• Never build directly on production. Prod hardware is a design target, not a development surface, until the roadmap declares it ready.

7. Acceptance gates — proven by automated, reproducible behavior tests (non-negotiable)

A change is not "done" until an automated, reproducible, behavior-based test (Given/When/Then, tagged with the requirement IDs it verifies) passes green in dev/test and is committed alongside the change. A manual demonstration, a screenshot, or "it reconciled" is not acceptance (R-TEST-01..04). The approach — reproducibility rules, layers, tooling, and the conformance suite — is specified in docs/14-testing-and-conformance.md and decisions/adr-0010-conformance-testing.md.

The behaviors each change must prove (each expressed as an automated test):

• No data loss on rebuild — destroy and recreate the workload; state survives (R-STATE-*).
• Default-deny holds — the workload cannot reach services it wasn't explicitly allowed to (R-NET-*).
• Correct egress path — internet-class services egress locally; VPN-class services egress only through the VPN, with a verified kill-switch (R-NET-*).
• Trusted TLS — the endpoint serves a valid, non-self-signed, auto-renewing certificate (R-TLS-*).
• Observed — metrics, logs, and at least one meaningful alert exist and fire correctly (R-OBS-*).
• Hands-off updates — the service advances to new stable versions automatically per policy, with no hand-authored change (R-UPD-*).

See agents/definition-of-done.md for the full checklist.

8. Coordination

• Claim work on agents/task-board.md before starting; respect declared dependencies (blocked-by).
• Follow agents/coordination-protocol.md for handoffs, interface contracts, and conflict resolution between agents/workstreams.
• Prefer small, reviewable, single-responsibility changes. One workstream should not silently change another workstream's interfaces — negotiate the contract change first.

9. Style & conventions

• Markdown for all specs. One concept per file. Link generously between documents.
• Use requirement IDs and ADR numbers in prose so references stay stable when files move.
• Be decisive in specs. Where a genuine open question remains, record it under an explicit Open Questions heading rather than burying ambiguity in the body.
• Keep the GLOSSARY.md authoritative — if you introduce a term, define it there.

10. What "you do not write code" means for the architect vs. what agents do

The architect authored the specs, ADRs, and this coordination structure — no code. The implementation agents who consume this repo do write code (implementation and the automated conformance tests that prove it), but only in service of an approved spec, only under the active roadmap phase, and only against the automated acceptance gates above. Agents write tests; agents do not write specs.

11. Specifications are immutable to agents (governance)

This is a hard boundary (R-TEST-06):

• You MUST NOT modify anything under docs/, the requirements, accepted ADRs in decisions/, the roadmap, or these coordination files. These are human-owned.
• You MAY and MUST create/modify: implementation code, automated conformance tests, the implementation repo, and the live coordination state the specs explicitly delegate to you — namely claiming/updating items on agents/task-board.md and recording proposals/escalations there. (The task board is a working surface; the rules around it are not.)
• When the spec is wrong, blocking, ambiguous, or missing: STOP. Do not proceed on a guess and do not edit the spec. Raise an escalation on the task board (and draft a proposal if useful) for the human operator/architect to decide. Resume only after the human amends the spec.
• Never make the implementation pass by weakening the spec, the requirement, or the test's intent. If reality can't meet the spec, that is an escalation, not a spec edit.

The point: the specification is the fixed target. Agents move the implementation and its tests toward the target; they never move the target.

12. Version-control workflow

Full detail in CONTRIBUTING.md. The rules that bind every change:

• No work on main. main holds only completed, reviewed work.
• Every change is a feature branch (feature/…, fix/…, docs/…, chore/…), merged into main when complete (and, for implementation, when its conformance tests pass).
• Local git for now; Gitea soon. There is no remote host on this network yet — the prior home-network Gitea is gone from this network. Gitea is one of the first services brought online on the cluster, after which repos, the GitOps source, and CI/CD move to Gitea (Gitea Actions running the Kyverno gate + Chainsaw conformance Job, with PRs as the enforced merge gate).
• Never commit plaintext secrets (SOPS-encrypted only, docs/07-security-and-secrets.md).