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]>
73 lines
4.3 KiB
Markdown
73 lines
4.3 KiB
Markdown
# 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. Take work from an issue, in your own workspace
|
|
- Implementation work is taken up through issues on the implementation repo, on a branch of its own.
|
|
- Do not start work that depends on something unfinished; 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 in an implementation-repo issue 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** in an
|
|
implementation-repo issue or directly to the operator, 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**,
|
|
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)** was opened by the operator's declaration; production is the one live environment
|
|
and changes reach it only through the PR gate and Flux.
|
|
|
|
## 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, say so in your handoff entry and PR, 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 **System 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
|
|
- **Implementation-repo issues** — work intake and escalations.
|
|
- **Implementation handoff log** (`decisions/` there) — what changed, what was verified, what was not.
|
|
- **`./conformance/run.sh --status`** (implementation repo) — the live requirement status.
|
|
- **specs/ADRs** — durable decisions and contracts.
|
|
- **PR descriptions** — reference requirement IDs, specs, ADRs, and the gate demonstrated.
|
|
Keep these in sync; they are how independent agents stay coherent.
|