jakman85andClaude Opus 5.5
250fb54154
The operator ruled the implementation repo's main (50c8719) the latest and accepted state. Sync the spec to it. Accepted changes are reflected: one bare-metal environment, TrueNAS bulk storage, R2 off-cluster backup, CloudNativePG, single-node VPN gateway with Cilium fail-closed, inbound WireGuard, per-app auth sidecars, Renovate, the CI gate as approver, and the pm-agent. New ADR-0017..0025; ADR-0016 corrected and accepted; R-* IDs unchanged, eight amended. Where the implementation has simply not met a requirement, the requirement stands and the shortfall is recorded in docs/16-known-gaps.md. Co-Authored-By: Claude Opus 5.5 <[email protected]>
4.7 KiB
4.7 KiB
Agent Roles
Each role owns a workstream (../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
System Architect (steward of this spec repo)
- Guards the source-of-truth hierarchy (
../AGENTS.md§2); 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 handoff log and the derived requirement status truthful.
Program Manager
- Decides what should happen about implementation work: starts, revises, or declines it, and briefs workers. Lives in the implementation repo; delegates code and debugging rather than doing them.
- Does not hold the System Architect role: work that needs a spec change is escalated. The in-cluster pm-agent (ADR-0025) is an automated instance of this role.
QA/Conformance Engineer (WS-TEST)
- Owns the conformance testing capability (14, ADR-0010): 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 | Reproducible node provisioning; k3s HA + Cilium; node rebuild w/o data loss |
| GitOps/Platform Engineer | WS-GITOPS | 05, 13 | Reconcile-from-git; drift correction; ServiceDefinition renderer; CI |
| Network Engineer | WS-NET | 03, 09 | Default-deny; explicit allows; egress classes; VPN kill-switch; ingress/DNS |
| Storage Engineer | WS-STORAGE | 04 | Replicated Longhorn; bulk tier; backups; tested restore/DR |
| Security Engineer | WS-SEC | 07, 08 | SOPS secrets; trusted auto-TLS; least-privilege; auditability proofs |
| Observability Engineer | WS-OBS | 10 | Metrics/logs; email alerts; dashboards; platform-health alerts |
| Automation Engineer | WS-UPDATE | 11 | Hands-off stable updates; health-gate + auto-rollback; pin |
| Virtualization Engineer | WS-VM | 06 | KubeVirt IaaS via same K8s surface; VM rebuild w/o data loss |
| Application Onboarding Engineer | WS-APPS | 13 | Each service wired from its ServiceDefinition; deps correct; nothing undeclared |
| C2/UX Engineer | WS-C2 | 12 | 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, 14).
- 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). - Negotiate interface changes before breaking another workstream's contract (coordination-protocol.md).
- Reach production only through the PR gate and Flux (R-ENV-03).
- Never emit plaintext secrets.