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]>
64 lines
4.7 KiB
Markdown
64 lines
4.7 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
|
|
|
|
### System 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 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](../decisions/adr-0025-in-cluster-ai-program-manager.md)) is an
|
|
automated instance of this role.
|
|
|
|
### 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)).
|
|
- Reach production only through the PR gate and Flux (R-ENV-03).
|
|
- Never emit plaintext secrets.
|