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]>

README.md

@@ -0,0 +1,105 @@
+# Home Platform — k3s + Longhorn Onboarding Platform
+
+> **This repository is a specification, not an implementation.** It defines *what* to build
+> and *how the work is organized* so that teams of AI agents (and their human reviewers) can
+> implement a self-service onboarding platform for home infrastructure at both the **PaaS**
+> (containerized apps) and **IaaS** (virtual machines) level.
+
+## What we are building
+
+A single, GitOps-driven platform, running on a **k3s** Kubernetes cluster backed by **Longhorn**
+distributed storage, that lets an operator onboard, run, update, and tear down services — both
+**containers** and **virtual machines** — through one consistent Kubernetes API, CLI, and YAML
+configuration surface.
+
+The platform must provide:
+
+- **PaaS**: containerized workloads onboarded via GitOps.
+- **IaaS**: virtual machines managed through the *same* Kubernetes API/CLI/YAML (via KubeVirt),
+  for workloads that cannot be containerized.
+- **Network isolation**: default-deny east-west traffic; explicit, port-level allow rules between
+  services (firewall-like).
+- **Multi-WAN egress**: some services egress the normal internet; others are routed through a
+  custom VPN connection. Egress path is a declarative property of a service.
+- **Stateful durability**: any service can be destroyed and rebuilt on a whim without losing data.
+- **Hands-off updates**: services update to latest stable versions on a schedule — no human,
+  no AI, no hand-written GitOps change required.
+- **Trusted TLS**: every service gets an auto-issued, auto-renewed, non-self-signed certificate.
+- **Observability**: services are monitored; issues are reported by email and on dashboards.
+- **A command & control center**: the root of `home.keithjackson.dev` is a UI that surfaces and
+  controls everything running in the cluster.
+- **Provable conformance**: every requirement is verified by an automated, reproducible, behavior-
+  based test — and the specifications themselves are human-owned and immutable to the implementing
+  agents.
+
+## Two environments
+
+| Environment | Substrate | Purpose | Status |
+|---|---|---|---|
+| **dev/test** | Local KVM virtual machines on a workstation, provisioned by IaC | Prove the platform end-to-end before hardware exists | **Active development target** |
+| **prod** | 3× mini-PC bare-metal k3s cluster, each with local storage | The real deployment | **Not ready — design for it, do not build on it yet** |
+
+The dev/test environment is the proving ground. Everything must be authored so that the *same*
+GitOps configuration promotes to production with only environment-scoped overrides.
+
+## How to use this repository (start here)
+
+1. **Read [`AGENTS.md`](AGENTS.md)** — the rules of engagement for every AI agent working here.
+2. **Read [`docs/00-vision-and-scope.md`](docs/00-vision-and-scope.md)** — the north star and the
+   non-negotiable requirements (with stable requirement IDs).
+3. **Read [`docs/01-architecture-overview.md`](docs/01-architecture-overview.md)** — the chosen
+   stack and how the pieces fit.
+4. **Consult [`decisions/`](decisions/)** — the Architecture Decision Records (ADRs) that lock in
+   every major technology choice and *why*. Do not re-litigate a decision; if you disagree, open a
+   superseding ADR per the process in [`decisions/README.md`](decisions/README.md).
+5. **Pick up work from [`roadmap/`](roadmap/) and [`agents/task-board.md`](agents/task-board.md)** —
+   phased delivery plan, workstreams, dependencies, and the live task board.
+
+## Repository map
+
+```
+home-network-k3s/
+├── README.md                     ← you are here
+├── AGENTS.md                     ← rules of engagement for AI agents
+├── GLOSSARY.md                   ← shared vocabulary (read to avoid ambiguity)
+├── docs/                         ← the specification, by domain
+│   ├── 00-vision-and-scope.md
+│   ├── 01-architecture-overview.md
+│   ├── 02-environments-and-provisioning.md
+│   ├── 03-networking-isolation-and-egress.md
+│   ├── 04-storage-and-state.md
+│   ├── 05-gitops-and-delivery.md
+│   ├── 06-vm-workloads-kubevirt.md
+│   ├── 07-security-and-secrets.md
+│   ├── 08-tls-and-certificates.md
+│   ├── 09-dns-and-ingress.md
+│   ├── 10-observability-and-alerting.md
+│   ├── 11-automated-updates.md
+│   ├── 12-command-center-ui.md
+│   ├── 13-service-catalog.md
+│   └── 14-testing-and-conformance.md
+├── decisions/                    ← ADRs (one decision per file) + index/template
+├── roadmap/                      ← phases.md, workstreams.md
+└── agents/                       ← roles, coordination protocol, DoD, task board
+```
+
+## Requirement traceability
+
+Every hard requirement has a stable ID (e.g. `R-NET-01`) defined in
+[`docs/00-vision-and-scope.md`](docs/00-vision-and-scope.md). Implementation work, ADRs, and
+task-board items must reference the requirement IDs they satisfy. This is how we prove the built
+system meets the spec.
+
+## Ground rules (the short version — full detail in `AGENTS.md`)
+
+- **Specs are the source of truth — and are immutable to agents.** Code and tests serve the spec.
+  AI agents **may not change** the `docs/`, requirements, or accepted ADRs; a spec that is wrong or
+  can't be met is an **escalation to the human**, never an edit (R-TEST-06).
+- **Done means a green, reproducible, behavior-based test.** Every requirement is verified by an
+  automated, requirement-tagged conformance test ([`docs/14-testing-and-conformance.md`](docs/14-testing-and-conformance.md),
+  [ADR-0010](decisions/adr-0010-conformance-testing.md)); a manual demo or "it merged" is not
+  acceptance.
+- **Everything is GitOps.** No click-ops in the cluster except where an ADR explicitly allows it.
+- **Nothing is self-signed, nothing is manual, nothing loses data.** These three properties are
+  acceptance gates, not aspirations — and each is proven by a test.
+- **Design once, deploy to two environments.** dev/test and prod differ only by scoped overrides.