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; the implementation has its own repository

This repo contains specifications only. Implementation artifacts (Helm values, Flux Kustomizations, KubeVirt manifests, Ansible IaC, the merge gate, the conformance tests) live in the implementation repo, whose CLAUDE.md governs how work lands there.

• Do not invent implementation details that contradict the specs or ADRs.
• Do not add implementation artifacts to this repo.
• 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/ System 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

If you find a conflict, stop and escalate it to the human operator/System 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/System 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 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. One environment, one configuration

• Production is the one live environment (ADR-0017).
• Author configuration as a shared base plus an environment-scoped overlay (replica counts, node selectors, storage sizes, WAN endpoints, DNS zones), so any future environment needs overrides only.
• Never fork the base configuration per environment. Use overlays/variables.
• Changes reach production only through the PR gate and Flux (R-ENV-03). Production is not a surface to experiment on by hand.

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 (offline for L0/L1, against the live cluster for L2/L3) 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

• Implementation work is taken up through issues on the implementation repo; each unit of work records a dated handoff entry in that repo's decisions/.
• Requirement status is derived from the repository (./conformance/run.sh --status in the implementation repo), not from a hand-maintained board. agents/task-board.md is a frozen historical seed; nobody edits it.
• 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 System Architect vs. what agents do

The System 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 and the implementation repo, including its handoff log. Nothing in this repo is a working surface for agents: any commit moves the spec HEAD away from the commit the implementation has pinned.
• 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 as an issue on the implementation repo or directly to the operator (and draft a proposal if useful) for the human operator/System Architect to decide. Resume only after the human amends the spec.
• Every spec advance is adopted explicitly by the implementation (CONTRIBUTING.md, "Adopting a spec change in the implementation").
• 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 work.
• Every change is a branch and a pull request. A spec change is merged only by the human operator. An implementation change merges on the green merge gate, the approver, with a non-author review on sensitive paths (ADR-0024).
• Agents never push to main, never merge their own PR, and never post the administrator override to clear their own work.
• Both repos are hosted on the platform's own Gitea, which is also the GitOps source; Gitea Actions runs the merge gate.
• Never commit plaintext secrets (SOPS-encrypted only, docs/07-security-and-secrets.md).