d5ef629a54
Architecture, overview, homelab build plan, agent handbook, ADRs, and agent operating rules. All sensitive operational details sanitized (real IPs, hostnames, client names replaced with generic placeholders). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
152 lines
4.8 KiB
Markdown
152 lines
4.8 KiB
Markdown
# 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
|