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]>
4.0 KiB
4.0 KiB
Coordination Protocol
How agents work together without stepping on each other. Read alongside roles.md,
../roadmap/workstreams.md, and ../AGENTS.md.
1. Claim before you build
- Take an item from
task-board.md, set its owner and status toin-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):
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). - Anything that changes a locked choice ⇒ draft a superseding ADR and escalate to the human
(
../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,
../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) 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
- Re-read the source-of-truth hierarchy (
../AGENTS.md§2); the higher document wins. - If specs genuinely conflict or are silent, escalate to the Platform Architect to amend the spec/ADR — fix the documents first, then build.
- 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.