Initial baseline: home platform (k3s + Longhorn) specification repository

Greenfield spec set for a GitOps-driven PaaS+IaaS home platform: vision & requirements (R-* IDs), architecture, 14 domain specs, 11 ADRs, roadmap (phases + workstreams), and AI-agent coordination (roles, protocol, definition-of-done, task board). Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
2026-08-15 22:37:56 -05:00
commit e8c555cfeb
@@ -0,0 +1,69 @@
+# Coordination Protocol
+
+How agents work together without stepping on each other. Read alongside [`roles.md`](roles.md),
+[`../roadmap/workstreams.md`](../roadmap/workstreams.md), and [`../AGENTS.md`](../AGENTS.md).
+
+## 1. Claim before you build
+- Take an item from [`task-board.md`](task-board.md), set its owner and status to `in-progress`.
+- Respect `blocked-by`. Do not start blocked work; help unblock it instead.
+- Keep items small and single-responsibility.
+
+## 2. Contracts are sacred
+Workstreams communicate through **interfaces** (listed in [`../roadmap/workstreams.md`](../roadmap/workstreams.md)):
+the ServiceDefinition schema, StorageClasses, the network policy/egress rendering, TLS issuer +
+Gateway, the observability contract, the update-policy contract.
+
+- **Consume** a contract freely.
+- **Change** a contract only by: (1) proposing the change on the task board with the affected
+  workstreams tagged, (2) getting the owning role's sign-off, (3) updating the spec that defines the
+  contract in the *same* change. Never silently break a downstream consumer.
+- The **ServiceDefinition schema** is the highest-traffic contract; treat schema changes as
+  platform-wide events.
+
+## 3. Decisions vs. discussion — and the no-spec-change rule
+- **You may not modify the specifications** (`docs/`, requirements, accepted ADRs, roadmap) — they
+  are human-owned and immutable to agents (R-TEST-06, [`../AGENTS.md` §11](../AGENTS.md)).
+- Anything that changes a locked choice ⇒ **draft** a superseding ADR and **escalate to the human**
+  ([`../decisions/README.md`](../decisions/README.md)); do not self-approve or merge it.
+- Genuine unknowns, or a spec that is wrong/blocking/ambiguous ⇒ **stop and escalate** on the task
+  board as an **Open Question (OQ-n)** for the human to resolve in the spec; don't bury ambiguity in
+  an implementation and don't patch the spec yourself.
+
+## 4. Definition of done
+Nothing is "done" until its **automated, reproducible behavior test passes green** in **dev/test**,
+committed with the change and tagged to its requirement IDs ([`definition-of-done.md`](definition-of-done.md),
+[`../docs/14-testing-and-conformance.md`](../docs/14-testing-and-conformance.md)). "Merged" ≠ "done";
+"demonstrated manually" ≠ "done". You write the test as well as the implementation.
+
+## 5. Phase discipline
+- Only work items in the **active phase(s)** ([`../roadmap/phases.md`](../roadmap/phases.md)) unless
+  explicitly parallelizable.
+- Respect entry gates; don't start a phase whose predecessor's exit criteria aren't demonstrated.
+- **Prod (Phase 7) is closed** until the operator opens it.
+
+## 6. Handoffs
+When your output feeds another workstream:
+- State the interface you're delivering and where it's documented.
+- Provide the demonstrable proof (the gate you passed) so the consumer can trust it.
+- If you changed a shared contract, announce it on the board with consumers tagged.
+
+## 7. Conflict resolution
+1. Re-read the source-of-truth hierarchy ([`../AGENTS.md` §2](../AGENTS.md)); the higher document
+   wins.
+2. If specs genuinely conflict or are silent, escalate to the **Platform Architect** to amend the
+   spec/ADR — fix the documents first, then build.
+3. Never resolve a conflict by silently picking an interpretation in code.
+
+## 8. Safety rails that never bend
+- Default-deny + VPN kill-switch are **fail-closed** — if unsure, deny/close.
+- Secrets stay encrypted; never printed.
+- Nothing that risks data ships without a tested backup/restore behind it.
+- No click-ops except ADR-sanctioned bootstrap steps.
+- **Specs are immutable to you**; a spec you can't meet is an escalation, never an edit.
+- **Never weaken a test or a requirement to get green** — that's a defect, not progress.
+
+## 9. Communication artifacts
+- **task-board.md** — the live who's-doing-what + status + blockers.
+- **specs/ADRs** — durable decisions and contracts.
+- **PR descriptions** — reference requirement IDs, specs, ADRs, and the gate demonstrated.
+Keep these three in sync; they are how independent agents stay coherent.