# Agent Handbook

Defines the shared operating protocol for all agents working in this repo.

This handbook is the common layer beneath agent-specific overlays (CLAUDE.md, GEMINI.md, Codex baseline). It governs startup behavior, source-of-truth discipline, read/write boundaries, environment assumptions, first-run onboarding, cross-agent compatibility, and closeout behavior.

---

## Authority Order

When instructions differ, use this order:

1. `AGENTS.md`
2. `LLM-ENTRYPOINT.md`
3. Authoritative state docs: `docs/priorities.md`, `docs/open-loops.md`, `vps/CURRENT-STATE.md`
4. This handbook
5. Agent-specific overlays

Agent-specific overlays must not contradict higher-authority documents.

---

## Mandatory Startup

Before doing any task work, every agent must read the mandatory startup chain defined in `AGENTS.md` and `LLM-ENTRYPOINT.md`.

If any required file is missing or unreadable, stop and report it. Do not begin planning, editing, or execution on assumptions.

When a task depends on live state that may have changed during the session, agents must re-read the relevant state files rather than rely on stale context.

---

## Source Of Truth Rules

Agents must:

- use repo files as the primary source of truth
- distinguish verified facts from inference
- use `Known / Reasoned / Action` when the task is analytical or state-sensitive
- avoid memory-only answers when current repo state is relevant
- never claim a repo-local instruction or config file exists unless verified

---

## Read / Write Rules

Agents may read repo files and run allowed read-only commands without asking.

Agents must state intent and wait for explicit operator approval before:

- editing any file
- creating any file
- running commands that the repo marks as approval-required
- taking any action that could affect shared agent systems

No opportunistic cleanup. No "while I'm here" side edits. No silent growth of agent-local docs or config in arbitrary locations.

---

## Environment Requirements

### Docker / Devcontainer

Agents must know:

- the repo operates inside a devcontainer
- Docker Compose lifecycle actions require operator approval
- named volumes persist agent config across rebuilds
- bind mounts and container-local filesystem are not equivalent

Agents must not assume host files are writable or visible from the container unless the repo explicitly documents that.

### Git

Agents must know:

- git is part of the system's durable memory substrate
- `git status` is normal session hygiene
- commit, push, and branch operations require approval where repo rules say so

Agents must not invent their own branch model.

### Documentation

Agents must know:

- authoritative state docs are part of runtime operations, not optional reading
- new durable docs must follow the documentation structure standard
- legacy docs are not silently normalized during unrelated work
- every repo must have a human-readable `README.md`

---

## First-Run Onboarding For New Agents

When a new agent or model is installed or rebooted into the repo for the first time, it must:

1. Read the mandatory startup chain
2. Read this handbook
3. Read the existing agent-specific overlays for the other agents
4. Inspect its own native structure, config, memory, hook, and instruction mechanisms
5. Compare those mechanisms against the repo's shared rules
6. Produce a non-destructive compatibility report
7. Ask for approval before creating or editing any integration file

---

## Agent Self-Integration Rule

A new agent may propose its own overlay file, config reference doc, and hook/config skeleton, and shared-doc updates needed for compatibility.

A new agent may not create or edit those files without explicit approval.

Agent-local integration must be additive, minimal, and compatible with the rest of the system.

---

## Cross-Agent Compatibility

Agent-specific files must not:

- weaken shared safety boundaries
- redefine write permissions
- invent conflicting closeout behavior
- silently override shared startup requirements
- create undocumented config or docs in arbitrary locations

Shared rules win over local preferences.

---

## Current Agent Inventory

| Agent / Runtime | Status | Notes |
|---|---|---|
| Claude | Active | Repo-specific hook system present |
| Codex | Active | Config baseline, approval/sandbox settings, and instruction-size limits matter |
| Gemini | Active | Overlay active |
| Local private model | Planned | Host-local inference path not yet finalized |

---

## Verification Standard

An agent is not considered correctly onboarded until it demonstrates that it can:

- follow the startup chain
- identify the current priority from repo docs
- respect write approval boundaries
- identify its own local overlay/config files accurately
- follow the shared closeout workflow
- avoid inventing missing files or unsupported features