Problem
The current AGENTS.md contains a contradiction in domain model ownership that breaks the closed-loop architecture principle (SA designs → SE builds → SA reviews).
In the Roles section, it states:
System Architect (SA) — Owns docs/domain-model.md, docs/system.md, and docs/adr/ADR-*.md.
And in Step 1 — SCOPE / Stage 1 — Discovery:
PO reads domain-model.md but never writes to it — entity suggestions go in discovery.md for SA formalization at Step 2
However, there is no explicit rule preventing the Software Engineer (SE) from modifying domain-model.md during implementation. In practice, if the SE writes domain stubs during Step 3, it opens the door to inadvertently editing the domain model — violating SA ownership. The domain model is an architecture artifact, not an implementation artifact.
Expected Behavior
The domain-model.md file should be exclusively owned by the System Architect, with the following rules enforced:
- SA creates and updates
domain-model.md during Step 2 (ARCH).
- SE reads
domain-model.md for implementation guidance but never modifies it.
- PO reads
domain-model.md during discovery but never modifies it.
- If the SE discovers a domain inconsistency during implementation, they escalate to the SA (via
WORK.md or a new ADR), rather than editing the domain model directly.
This aligns with:
- The closed-loop principle: the same mind that designed the architecture verifies it.
- ISO/IEC/IEEE 42010:2022: architecture descriptions are first-class artifacts owned by architects.
- Decision-centric architecture: domain knowledge decays when ownership is blurred.
Suggested Fix
Update AGENTS.md to explicitly state:
- In the SE role description: "SE reads
docs/domain-model.md for implementation guidance but never modifies it. Domain inconsistencies are escalated to the SA."
- In the Step 2 description: Clarify that "write domain stubs" means the SA writes the initial
.py stub files (or the SE writes them under SA direction), but the domain-model.md itself remains SA-owned.
- Optionally, add a Domain Model Chain of Responsibility table similar to the
.feature file chain of responsibility.
References
AGENTS.md, lines 52, 119, 165
- Closed-loop principle:
AGENTS.md, line 42
Problem
The current
AGENTS.mdcontains a contradiction in domain model ownership that breaks the closed-loop architecture principle (SA designs → SE builds → SA reviews).In the Roles section, it states:
And in Step 1 — SCOPE / Stage 1 — Discovery:
However, there is no explicit rule preventing the Software Engineer (SE) from modifying
domain-model.mdduring implementation. In practice, if the SE writes domain stubs during Step 3, it opens the door to inadvertently editing the domain model — violating SA ownership. The domain model is an architecture artifact, not an implementation artifact.Expected Behavior
The
domain-model.mdfile should be exclusively owned by the System Architect, with the following rules enforced:domain-model.mdduring Step 2 (ARCH).domain-model.mdfor implementation guidance but never modifies it.domain-model.mdduring discovery but never modifies it.WORK.mdor a new ADR), rather than editing the domain model directly.This aligns with:
Suggested Fix
Update
AGENTS.mdto explicitly state:docs/domain-model.mdfor implementation guidance but never modifies it. Domain inconsistencies are escalated to the SA.".pystub files (or the SE writes them under SA direction), but thedomain-model.mditself remains SA-owned..featurefile chain of responsibility.References
AGENTS.md, lines 52, 119, 165AGENTS.md, line 42