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]>
70 lines
4.0 KiB
Markdown
70 lines
4.0 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. Claim before you build
|
|
- Take an item from [`task-board.md`](task-board.md), set its owner and status to `in-progress`.
|
|
- Respect `blocked-by`. Do not start blocked work; 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 on the task board 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** on the task
|
|
board as an **Open Question (OQ-n)** 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** in **dev/test**,
|
|
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) is closed** until the operator opens it.
|
|
|
|
## 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, announce it on the board 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 **Platform 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
|
|
- **task-board.md** — the live who's-doing-what + status + blockers.
|
|
- **specs/ADRs** — durable decisions and contracts.
|
|
- **PR descriptions** — reference requirement IDs, specs, ADRs, and the gate demonstrated.
|
|
Keep these three in sync; they are how independent agents stay coherent.
|