colibri/AGENTS.md

Colibri Agent Guidelines (Sam & Hermes)

Project Identity

Colibri is the Clawdie control plane core — a small, cross-platform (FreeBSD 15

• Linux) Rust daemon. Developed and validated from an operator USB environment; deploys as the Clawdie service on bare metal. It unifies a coordination model (agents-as-teammates, task board, team skills) with a cache-first cost discipline (byte-stable prompt prefixes, cache-hit metering).

License: MIT (matches layered-soul). Version: 0.11.0, unified with clawdie-iso.

Design doc: doc/COLIBRI-CONTROLPLANE-PLAN.md in Clawdie-AI.

Architecture Roles

• zot — the agent (front door to the model). Go binary with built-in providers (DeepSeek + ~25 others), Telegram bot, JSON output mode, SKILL.md skills, subprocess extensions, and its own credential store ($ZOT_HOME/auth.json).
• Colibri — the control plane (supervisor). Watches agents via glasspane, runs the task board, holds the skills catalog, tracks cost. It spawns and observes zot/pi; it does not contain them.
• pi — kept as a spawnable backend, not the default. Glasspane treats pi and zot identically (AgentRuntime { Pi, Zot }).
• Clawdie — Colibri deployed as a service on bare FreeBSD hardware. Target spec: ZFS RAID1 mirror, PostgreSQL + pgvector, bhyve VMs, Bastille jails. The operator USB is the development/validation surface; the Clawdie service is the production deployment. (Product name = Colibri + zot running on a Clawdie host, not a separate binary.)
• clawdie-ai (TS) — being pruned; surviving features move to zot skills/extensions or Colibri.

Markdown Formatting Gate

Markdown is tool-formatted, not hand-formatted. Before pushing any commit that edits *.md, run:

./scripts/check-format.sh

If it fails, format only the touched files and rerun:

npx --yes prettier@3 --write path/to/file.md

.prettierrc uses proseWrap: preserve (prose line breaks stay intentional) and embeddedLanguageFormatting: off for *.md (fenced code — JSON, mermaid, shell — is left exactly as written). Use npx prettier --write for all markdown formatting; preserve intentional prose line breaks and fenced code.

Target Platform

Target deployment: bare-metal FreeBSD host. Colibri runs as the clawdie rc.d service on a ZFS RAID1 mirror with PostgreSQL + pgvector, bhyve VMs, and Bastille jails. The operator USB image is the development, validation, and recovery surface — the bare-metal install is the production target.

Target: x86_64-unknown-freebsd (Rust Tier-2). TLS uses rustls for clean static linking on FreeBSD (no openssl-sys dependency).

Agent Identity

Identity	Platform	Capabilities	Restrictions
Claude (domedog)	Linux, domedog	cargo build, cargo test, code edits	Delegate FreeBSD 15 runtime proof to the FreeBSD agent; push artifacts for validation
Hermes (debby)	Debian 13, debby	cargo build, cargo test, code edits	Delegate FreeBSD 15 runtime proof to the FreeBSD agent; push artifacts for validation
Codex / Aider (FreeBSD)	FreeBSD 15 host	cargo test on real FreeBSD, integration	Receives handoff docs; validates Linux-built artifacts
Operator (Sam)	FreeBSD 15 host + Linux	Final review, merge, deploy	Human — all deployment decisions require approval

Workspace — current crates

Crate	Role
colibri-contracts	Manifest/capability/event schema (golden tests)
colibri-deepseek	DeepSeek cache-hit probe, prefix metering
colibri-runtime	Host status ingestion, runtime inventory
colibri-glasspane	Agent state machine + event ingestion
colibri-daemon	Always-on socket server, session/agent lifecycle, jail spawner
colibri-client	Typed Unix-socket client + operator CLI tools
colibri-glasspane-tui	ratatui dashboard — live pane supervision
colibri-store	Embedded SQLite coordination (task board, agents, skills)
colibri-skills	Skills catalog (read-only consumer of reviewed skill artifacts)
colibri-mcp	MCP bridge for editor integration + external MCP host (jailed)
clawdie	Host installer/deployer: ZFS layout + clawdie service (FreeBSD/Linux)
colibri (root)	Workspace root + probe binaries

The table lists the workspace members plus the root colibri package. Always derive the crate count from Cargo.toml members + the root — it is the source of truth and stays accurate.

Gate status should be rechecked from source instead of relying on a fixed test count:

cargo fmt --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo build --workspace --release

Mandatory before every merge to main: run the full gate via

./scripts/ci-checks.sh   # fmt --check, clippy -D warnings, test, markdown gate, wiki-lint --strict

A git push to main also runs this gate through the pre-push hook (activate once: ./scripts/install-hooks.sh). The hook rejects the push if any gate fails; bypass only in emergencies with --no-verify.

.forgejo/workflows/ci.yml encodes the same checks, but no Actions runner is currently registered, so nothing enforces them server-side. Until a runner is active, ci-checks.sh passing locally is the only gate — a green run is a prerequisite for merging. (A compile break reached main once because this step was skipped; do not skip it.)

ISO Takeover Gates

Gate	Target	Status
1 — Passive service	rc.d boot, status/snapshot/tasks, SQLite writable	open
2 — Agent observation	Real zot/pi spawned, glasspane states match lifecycle	open
3 — Read source of truth	CLI/TUI covers daily debugging; external clients read Colibri	open
4 — Write takeover	Colibri owns scheduling and dispatch	open
5 — TS retirement	One ISO candidate with Colibri as sole control service	open

Current sprint priorities: docs/MULTI-AGENT-HOST-PLAN.md.

Jail Confinement

Agent spawning supports FreeBSD jail confinement via JailConfig in colibri-daemon/src/spawner.rs. The spawn-agent socket command accepts a jail field. External MCP servers can also be jailed (see docs/COLIBRI-EXTERNAL-MCP-PROTOTYPE.md).

Design doc: docs/COLIBRI-JAILED-AGENT-SPAWN-DESIGN.md

Skills & External MCP

colibri-skills provides a read-only skills catalog backed by SQLite. colibri-mcp exposes Colibri tools to editors (Zed, Claude Code) via stdio MCP and can also act as a host for external MCP servers registered in /usr/local/etc/colibri/external-mcp.json. External tool calls are gated by COLIBRI_MCP_EXTERNAL_CALL=1; write tools by COLIBRI_MCP_WRITE=1.

See docs/COLIBRI-EXTERNAL-MCP-PROTOTYPE.md and docs/CLAWDIE-STUDIO-PROPOSAL.md.

Multiagent Workflow

• Handoff doc: docs/<FEATURE>-HANDOFF.md — always update before handing off
• Active handoffs:
  • docs/FREEBSD-BUILD-LANE-HANDOFF.md — FreeBSD agent (Codex): build the Colibri and zot binaries, run the clawdie-iso build, boot, and run the acceptance runbook plus the Hermes rc.d checks (ISO Gate 1 runtime proof for Priority 1).
  • docs/CLAWDIE-INSTALLER-HANDOFF.md — FreeBSD agent (Codex): clawdie ZFS layout + service install validation.
• External MCP smoke: see docs/COLIBRI-EXTERNAL-MCP-PROTOTYPE.md

Linux Agent Constraints

Linux agents (Claude on domedog / Hermes on debby) MUST:

• Run cargo build, cargo test, cargo clippy from their Colibri checkout
• Push to Forgejo for FreeBSD 15 validation
• Create handoff docs for FreeBSD-specific tasks

Linux agents MUST NOT:

• Assume cargo test on Linux produces identical results to FreeBSD 15
• Run FreeBSD 15-specific commands (pkg, service, jls, kldload)
• Claim runtime correctness without FreeBSD 15 validation
• Install packages via apt, cargo install, rustup without operator approval

FreeBSD 15 Agent Constraints

The FreeBSD 15 agent MUST:

• Run cargo test on real FreeBSD 15 before claiming any test pass
• Read and follow any active docs/*-HANDOFF.md files on startup
• Report exact cargo test output, compiler version (rustc --version), and FreeBSD version (freebsd-version) in validation reports
• Not delete handoff docs until ALL deletion criteria are met

Cross-Repo Coordination

Colibri is part of the Clawdie project alongside:

Repo	Purpose	Remote
clawdie-ai	Agent runtime, control plane, channels	git@code.smilepowered.org:clawdie/clawdie-ai.git
clawdie-iso	ISO builder, firstboot wizard, installer	git@code.smilepowered.org:clawdie/clawdie-iso.git
Colibri	Cross-platform Rust control plane core	git@code.smilepowered.org:clawdie/colibri.git

See Clawdie-AI/AGENTS.md for the full handoff protocol and attribution conventions.

Build

cargo build --release

Test

cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings

Golden tests in crates/colibri-contracts/tests/golden.rs validate manifest output against reference fixtures. These fixtures are cross-platform — if a Linux-produced manifest differs from FreeBSD 15, investigate and document the cross-platform difference before proceeding.

Post-Build Cleanup (mandatory, all agents)

After finishing a coding session AND before handoff/end-of-day:

cargo clean                                    # frees 6-8 GB of build artifacts
rm -rf /tmp/colibri-daemon-socket-test-*       # stale test temp dirs
rm -rf /tmp/colibri-scheduler-test-*
rm -rf /tmp/colibri-live-smoke-*

Why: cargo clean reclaims 6-8 GB. Stale /tmp test dirs accumulate 34+ directories per session (socket/integration tests create UUID-named temp dirs that tests don't always clean up, especially on panic). Disk was at 91% before cleanup. Leaving build artifacts for the next agent is disrespectful and wastes shared disk space.

Platform notes: Commands are identical on Linux and FreeBSD. On FreeBSD live USB, /tmp is tmpfs and auto-clears on reboot, but cargo clean is still needed to reclaim the target directory.

When to skip: Continuing work in the same tmux session within minutes — the build cache speeds up iteration. Clean before handoff, end-of-day, or if you won't rebuild within the hour.

Forgejo (Primary)

• Remote: git@code.smilepowered.org:clawdie/colibri.git (port 2222 SSH)
• SSH key: claude-code-clawdie (configured on debby)
• Codeberg is the public mirror; Forgejo is the source of truth.
• Push small, reviewable commits with test/build status in commit messages.