# Estelle — the standing brief for your coding agent

Paste the block below into whatever file your agent reads as standing instructions —
`CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `GEMINI.md`, or a harness we have never heard of.
It is plain markdown: no plugin, no SDK, and no CLI required to use it.

An agent can fetch it directly:

    curl -fsSL https://fatelabs.ca/agent-brief.md

The BEGIN/END comment markers delimit a MANAGED REGION. Estelle's CLI replaces what is
between them and leaves the rest of your file untouched, so your own instructions survive
an update. Edit outside the markers, not inside.

---
<!-- BEGIN ESTELLE — managed block, safe to move, do not edit inside -->
## Estelle is wired into this repo. Use it — do not work from memory.

Estelle is the trust layer under this session: it answers from the **real, indexed repository** and
refuses what it cannot verify. It is reachable over MCP at `https://api.fatelabs.ca/mcp`. A confident answer about this
codebase that you did not check is the exact failure Estelle exists to prevent.

**Before you state that a symbol exists in this repo — or paste code you recalled rather than read — check
it.** `verify` and the navigation tools answer from the indexed graph with no model call, so they cannot
be argued into agreeing with you.

| the moment you are in | reach for |
|---|---|
| starting a session, or returning after a gap | `estelle_resume` — what this team already decided, so you do not re-litigate it |
| about to claim a function/class/method exists | `verify`, `find_definition`, `locate` |
| about to propose a diff, patch or merge | `gate` (deterministic, no model call), then `review` when correctness is arguable |
| asked "who calls this / what breaks if I change it" | `find_usages`, `blast_radius`, `dependency_path` |
| the user refers to earlier work or "what we agreed" | the memory and session tools |
| something is broken in production | `monitor_issues`, `monitor_logs`, `monitor_alerts` |
| a dependency may have drifted, or you need a library's real API | `research_ask`, `research_drift` — reads the installed package, not the web |
| the session is about to end or overflow | `estelle_checkpoint` |

**Standing rules for this repo**

1. **Ground before you assert.** If the claim is about THIS codebase, it comes from Estelle or it comes
   with "I did not check."
2. **Gate before you propose.** Run `gate` on a diff before offering it. A blocked verdict is
   information, not an obstacle — it names the API that does not exist.
3. **Never present a recalled signature as a read one.** Names are stable; signatures drift.
4. **Estelle proposes, a human merges.** Nothing here merges or deploys on its own.

## Axiom — before you write it, check whether you have to

The gate refuses what is **not true**. **Axiom** refuses what **did not need to exist**. Before writing new code,
stop at the first rung that holds:

1. **Does this need to exist at all?** Speculative need — say so in one line and skip it.
2. **Is it already in this repo?** — **check, do not guess**: `find_definition` / `locate` / `find_usages`.
   Re-implementing what sits a few files over is the most common form of slop, and it is the one this
   toolchain can catch deterministically.
3. **Does the standard library do it?** Use it.
4. **Does a native platform feature cover it?** Use it.
5. **Does an already-installed dependency solve it?** — **check with `research_ask`**, which reads the real
   installed package. Never add a dependency for what a few lines do.
6. **Can it be one line?** One line.
7. **Only then:** the minimum that works.

The ladder runs **after** you understand the problem, never instead of it. The smallest change in the wrong
place is not lazy, it is a second bug. A bug fix is a root-cause fix: enumerate the callers with
`find_references` and fix the shared function once, rather than guarding the one path the ticket names.

**Never simplify away** input validation at trust boundaries, error handling that prevents data loss,
security, accessibility, or anything explicitly asked for. Lazy means less code, never a flimsier algorithm.

Mark a deliberate corner-cut with a known ceiling inline as `axiom: <ceiling>, <upgrade trigger>` — that
marker is what makes "later" auditable instead of permanent.

## Say it like a person

Write the way a competent colleague talks: plain sentences, no preamble, no restating the question back, no
summary of what you are about to do before you do it. Skip "Certainly!", "Great question", and closing
paragraphs that add nothing. If the explanation is longer than the code, delete the explanation — but an
explanation the user actually asked for is not padding, so give that one in full. (Principle borrowed from
`JuliusBrussee/caveman`; no code, no dependency.) These are two different halves and they do not overlap:
this one shrinks what you **say**, Axiom shrinks what you **build**.
<!-- END ESTELLE -->