jakman85andClaude Opus 4.8
e8c555cfeb
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]>
57 lines
4.2 KiB
Markdown
57 lines
4.2 KiB
Markdown
# Agent Roles
|
|
|
|
Each role owns a workstream ([`../roadmap/workstreams.md`](../roadmap/workstreams.md)) and is
|
|
accountable for that workstream's requirement IDs and acceptance gates. Roles are responsibilities,
|
|
not people — one agent may hold several early on; split as work scales.
|
|
|
|
## Coordination roles
|
|
|
|
### Platform Architect (steward of this spec repo)
|
|
- Guards the source-of-truth hierarchy ([`../AGENTS.md` §2](../AGENTS.md)); approves/records ADRs.
|
|
- Resolves cross-workstream interface conflicts; keeps requirement traceability honest.
|
|
- Does **not** write implementation code; owns specs, ADRs, roadmap, and this coordination layer.
|
|
|
|
### Integration/Release Lead
|
|
- Owns the implementation repo structure, CI gates, and Flux bootstrap health.
|
|
- Runs phase entry/exit reviews against the **automated conformance suite**; keeps the task board
|
|
truthful.
|
|
|
|
### QA/Conformance Engineer (WS-TEST)
|
|
- Owns the conformance testing capability ([14](../docs/14-testing-and-conformance.md),
|
|
[ADR-0010](../decisions/adr-0010-conformance-testing.md)): the harness, the reproducibility
|
|
contract, the requirement-coverage report, and the CI/phase gates.
|
|
- Does **not** own writing every test in isolation — **each workstream authors the behavior tests
|
|
for its own requirements**; WS-TEST provides the framework, patterns, fault-injection harness, and
|
|
gate, and guards that tests assert real behavior and are never weakened to pass (R-TEST-05/06).
|
|
- Accountable for: every `R-*` requirement having a passing, reproducible, tagged test.
|
|
|
|
## Implementation roles (one per workstream)
|
|
|
|
| Role | Workstream | Primary specs | Accountable for (gates) |
|
|
|---|---|---|---|
|
|
| **Infra/Cluster Engineer** | WS-INFRA | [02](../docs/02-environments-and-provisioning.md) | Reproducible node provisioning; k3s HA + Cilium; node rebuild w/o data loss |
|
|
| **GitOps/Platform Engineer** | WS-GITOPS | [05](../docs/05-gitops-and-delivery.md), [13](../docs/13-service-catalog.md) | Reconcile-from-git; drift correction; ServiceDefinition renderer; CI |
|
|
| **Network Engineer** | WS-NET | [03](../docs/03-networking-isolation-and-egress.md), [09](../docs/09-dns-and-ingress.md) | Default-deny; explicit allows; egress classes; VPN kill-switch; ingress/DNS |
|
|
| **Storage Engineer** | WS-STORAGE | [04](../docs/04-storage-and-state.md) | Replicated Longhorn; bulk tier; backups; **tested restore/DR** |
|
|
| **Security Engineer** | WS-SEC | [07](../docs/07-security-and-secrets.md), [08](../docs/08-tls-and-certificates.md) | SOPS secrets; trusted auto-TLS; least-privilege; auditability proofs |
|
|
| **Observability Engineer** | WS-OBS | [10](../docs/10-observability-and-alerting.md) | Metrics/logs; email alerts; dashboards; platform-health alerts |
|
|
| **Automation Engineer** | WS-UPDATE | [11](../docs/11-automated-updates.md) | Hands-off stable updates; health-gate + auto-rollback; pin |
|
|
| **Virtualization Engineer** | WS-VM | [06](../docs/06-vm-workloads-kubevirt.md) | KubeVirt IaaS via same K8s surface; VM rebuild w/o data loss |
|
|
| **Application Onboarding Engineer** | WS-APPS | [13](../docs/13-service-catalog.md) | Each service wired from its ServiceDefinition; deps correct; nothing undeclared |
|
|
| **C2/UX Engineer** | WS-C2 | [12](../docs/12-command-center-ui.md) | Root C2 UI; live catalog + health; safe, audited actions |
|
|
|
|
## Standing expectations for every role
|
|
- Trace all work to requirement IDs; reference specs/ADRs by ID (stable across file moves).
|
|
- **Author an automated, reproducible behavior test** for every requirement you implement; "done" is
|
|
a green, tagged test, not "merged" ([definition-of-done.md](definition-of-done.md),
|
|
[14](../docs/14-testing-and-conformance.md)).
|
|
- **Never modify the specifications** (`docs/`, requirements, accepted ADRs, roadmap) — they are
|
|
human-owned (R-TEST-06). A spec you can't meet is an **escalation**, not an edit. Never weaken a
|
|
test/requirement to get green.
|
|
- Never re-litigate an accepted ADR; **draft + escalate** a superseding ADR for human approval
|
|
([`../decisions/README.md`](../decisions/README.md)).
|
|
- Negotiate interface changes before breaking another workstream's contract
|
|
([coordination-protocol.md](coordination-protocol.md)).
|
|
- Never build on prod hardware before Phase 7 is opened.
|
|
- Never emit plaintext secrets.
|