> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enagrams.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Coordination Model

> How Enagrams keeps agents from working at cross-purposes

## The Core Problem

When two developers use AI coding agents in parallel, those agents have no awareness of each other. They make independent decisions, edit the same files simultaneously, and contradict each other's architecture — all without knowing it. The conflict surfaces at merge time.

## The Three Layers

Enagrams solves this with three layers. Most teams never interact with layers 2 and 3 directly — the hooks do the work.

### 1. Automatic coordination (hooks)

IDE hooks fire on every relevant event. No manual MCP calls needed.

```
New conversation
  → sessionStart hook fires
  → Agent receives briefing: "Agent B is editing src/auth/, owns login.ts:validateToken"
  → Agent knows what's in-flight and which conventions apply

User's agent writes a file
  → preToolUse (Write) hook fires
  → Enagrams checks: is this file/symbol reserved? Does any must-tier convention match?
  → If yes: write is denied with context ("Owned by Agent B — 'Build JWT auth'")
  → If no: write proceeds

After successful write
  → postToolUse hook fires
  → Reservation refreshed, symbol graph re-extracted

Conversation ends
  → sessionEnd hook fires
  → All reservations released
```

### 2. Explicit context (MCP tools)

Agents call [26 MCP tools](/mcp/overview) when they need richer context or want to record something: [`sync`](/mcp/sync), [`decide`](/mcp/decide), [`search`](/mcp/search), [`ask`](/mcp/ask), [`learn`](/mcp/learn), plus workstream, task, convention, negotiation, and test-gate tools.

### 3. Auto-sync (`enagrams watch`)

Once a change clears the [test gate](/concepts/test-gate) on a workstream branch, `enagrams watch` on other developers' machines fetches and applies it automatically. Nobody manually pulls a teammate's in-progress branch.

## What an agent knows at session start

A briefing like this is injected automatically:

```
Active agents:
  - Developer B's Cursor  [workstream: auth-refactor]
    task: "Build JWT auth flow"
    editing: src/auth/login.ts · symbol: validateToken

Reservations relevant to you:
  - src/auth/login.ts::validateToken  (B, 8 min remaining)
  - src/auth/middleware.ts            (B, 8 min remaining)

Recent decisions (3):
  - "Use JWT for auth" (B, 12 min ago) — stateless, edge-friendly

Applicable conventions:
  - must: "All API routes return { ok, data, error }" (affects src/api/**)
  - should: "Prefer zod over manual validation"

Your task (from claimed work package):
  - Build user registration  (files: src/users/register.ts, src/users/validate.ts)
```

The agent does not need to ask for this — `sessionStart` provides it.

## Conflict detection

Beyond file/symbol locking, `sync` returns advisory signals:

| Signal                                                          | Type     | Description                                            |
| --------------------------------------------------------------- | -------- | ------------------------------------------------------ |
| Same file/symbol reserved by another session                    | Conflict | Hard block via `preToolUse`                            |
| Another agent working in same directory                         | Warning  | Soft warning in sync                                   |
| File recently edited by another agent on a different workstream | Warning  | Soft warning in sync                                   |
| Stale decision covering files you're editing                    | Warning  | Surfaced via [`decisions_stale`](/mcp/decisions-stale) |

When a hard block occurs, the affected agent can open a [negotiation](/concepts/negotiation) instead of silently backing off.

## Session model

Sessions are keyed by `conversation_id` (Cursor) or `session_id` (Claude Code/Codex), so:

* Multiple Cursor tabs → independent sessions, even when sharing one MCP process
* Sessions auto-expire after 5 minutes of inactivity (no hook events)
* Sessions appear in the dashboard with agent type, current task, workstream, and touched files/symbols