Start here#

What this is for: getting one repo set up in about fifteen minutes.

1. Install#

git clone https://github.com/mutaaf/estate-agent ~/.estate-agent
export PATH="$HOME/.estate-agent/bin:$PATH"   # add to your shell profile
estate version

Nothing else. No package manager, no dependencies, no account.

2. Look before you leap#

cd ~/work/your-repo
estate doctor

doctor changes nothing. It tells you what stack it thinks this is, what context files already exist, and what is missing. Read it before going on.

3. Set the repo up#

estate init

This writes .agent/estate.yaml — the deed, the one file you maintain — and generates the five assistant files from it. If you already had a CLAUDE.md, its commands and rules are folded into the deed and the rest is kept verbatim; a copy of the original is saved next to it.

4. Check the deed#

Open .agent/estate.yaml. Three things are worth thirty seconds each:

The commands. Run them. A wrong test command is worse than none, because the agent will trust it.
The tier. 1 = read only, 2 = pull requests with review, 3 = may merge on green CI. See tiers.
never_do. What would you tell a competent new joiner not to touch?

Then:

estate sync    # regenerate after any edit
git add .agent CLAUDE.md AGENTS.md GEMINI.md .cursor .github .claude
git commit -m "Set up Estate Agent"

5. Map the estate#

If your repos live side by side in one directory:

estate scan ~/work

You get ESTATE.md — a readable register of every service, what it exposes, and who calls it — and the ability to ask the question that matters:

estate impact payments-api /v2/charge

6. Keep it honest#

Add this to CI so the generated files can never drift from the deed:

- run: estate check --quiet

And once in a while, or when something feels stale:

estate upkeep

The five commands, in one table#

Command	What it does	Changes files?
`estate doctor`	what is set up here, what is missing	no
`estate init`	set this repo up	yes
`estate sync`	regenerate the assistant files from the deed	yes
`estate check`	fail if anything has drifted — for CI	no
`estate upkeep`	find what has gone stale, repair what is safe	yes
`estate scan`	map every repo in a workspace	yes
`estate impact`	what breaks if you change this	no
`estate vault`	write the estate as linked markdown notes	yes

7. Optional: a vault of linked notes#

If you want the estate as a browsable knowledge base rather than a report:

estate vault ~/work

You get one note per service, per shared cluster, and per endpoint something calls — wikilinked, with YAML frontmatter. Open it in Obsidian for the graph view, read it on GitHub, or point an agent at the folder. It also scaffolds Investigations/, Decisions/ and Runbooks/ for the things only a person can write. Everything under Generated/ is overwritten on each run; the human trees never are.

What next#

Not sure how far you have got? The five levels has a four-question self-check.
Adding a repo? Repeat steps 2–4. It gets faster.
Curious how the map works? The estate map
Worried about safety? What data goes where
Need a word defined? Glossary