The Estate Agent specification#
Version 0.1.0. Anchors on this page are permanent. Later versions add sections; they do not renumber or rename existing ones, so a link or a citation to any heading here keeps working.
1. The deed#
Each repository has exactly one source of truth at .agent/estate.yaml. All assistant-specific context files are generated from it and are never edited directly. A conforming implementation MUST fail a check when a generated file differs from what the deed would produce.
2. Generated context files#
From one deed, an implementation generates CLAUDE.md, AGENTS.md, GEMINI.md, .github/copilot-instructions.md, and .cursor/rules/00-estate.mdc. Each carries a stamp recording the hash of the content generated, which allows a hand edit to be distinguished from a stale file.
3. Tiers#
A repository declares one of three tiers.
| Tier | Name | The agent may | The agent may not |
|---|---|---|---|
| 1 | Restricted | read, explain, propose | write, open pull requests, mutate state |
| 2 | Reviewed | edit, open pull requests | merge |
| 3 | Autonomous | edit, open pull requests, merge on green CI | bypass CI, edit another repo's deed |
Legacy systems default to tier 1. An implementation MUST NOT raise a tier automatically.
4. The resolution ladder#
A connection between two repositories is established by exactly one method, and the method is recorded on the connection.
| Rank | Method | Basis | Confidence |
|---|---|---|---|
| 1 | declared | the source names the service outright | 0.95 |
| 2 | dependency | a generated client for the service is a dependency | 0.90 |
| 3 | env | a configured variable names the service | 0.75 |
| 4 | host | a URL hostname matches the service | 0.70 |
| 5 | path | the called path matches exactly one service's endpoint | 0.60 |
5. Evidence#
Every connection MUST cite a file path and line number. A connection without evidence MUST NOT appear on the map.
6. Ambiguity#
Where a signal matches more than one service equally well, an implementation MUST NOT choose. The signal is recorded for human confirmation, with its candidates listed.
7. External dependencies#
A signal that matches no service in the estate is external, not ambiguous. It MUST be recorded separately from items awaiting confirmation.
8. Ship cost and landing order#
Repositories are classified by how reversibly they deploy. Client applications (mobile, TV, installed desktop) cannot be rolled forward, so where the affected set contains one, an implementation MUST produce an expand-and-contract landing order: add the new shape, migrate services, ship clients, and only then remove the old shape.
9. Self-healing#
An implementation repairs staleness automatically, subject to four constraints:
- It MUST NOT overwrite a file that has been edited by hand.
- It MUST NOT relax a safety rule without human action.
- It MUST NOT modify source code.
- It MUST migrate deeds written by earlier versions.
10. The correction protocol#
Generated context files instruct the agent that when reality contradicts them, the agent corrects the deed — not the generated file — within the same unit of work, and notes the correction in the pull request.
11. Data flow#
Levels 1 and 2 of a conforming implementation MUST NOT make network calls of any kind, including telemetry.