portfolio/agentlab/agent-handbook.md

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