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. 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).

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

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). Do not hand-align tables or reflow prose.

Target Platform

Destination runtime: FreeBSD 15. Development happens on Linux (debby — Debian 13, this machine) but final validation must pass on FreeBSD 15.

Target: x86_64-unknown-freebsd (Rust Tier-2). TLS is rustls to avoid openssl-sys linking on FreeBSD.

Agent Identity

Identity	Platform	Capabilities	Restrictions
Claude (domedog)	Linux, domedog	cargo build, cargo test, code edits	Cannot claim FreeBSD 15 runtime proof; push for validation
Hermes (debby)	Debian 13, debby	cargo build, cargo test, code edits	Cannot claim FreeBSD 15 runtime proof; push 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
colibri-client	Typed Unix-socket client + operator CLI tools
colibri-glasspane-tui	ratatui dashboard — live pane supervision
colibri (root)	Workspace root + probe binaries

The workspace currently has 8 crates. colibri-skills is planned as the next split-brain crate and would become the ninth crate when scaffolded.

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

Next planned crate

The next split-brain lane is documented first, not scaffolded blindly:

• docs/COLIBRI-SKILLS-PLAN.md

This is the planned Rust read path for Clawdie's built-in handbook / manuals lane:

• DB: system_skills
• source of truth: committed built-in knowledge artifact
• scope: read-only consumer first

It is intentionally separate from:

• system_brain user/agent memory
• system_ops runtime state

Multiagent Workflow

• Handoff doc: doc/<FEATURE>-HANDOFF.md — always update before handing off
• Proof gate tracker: cargo run --bin proof-gate-tracker
• Platform matrix: cargo test --test platform-matrix
• Herdr remote smoke: clawdie-ai/docs/internal/sessions/2026-05-27-herdr-tailscale-remote-smoke.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 doc/*-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, don't silently accept the difference.

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.