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:

```sh
./scripts/check-format.sh
```

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

```sh
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:

```sh
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

```sh
./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

```sh
cargo build --release
```

## Test

```sh
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:

```sh
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.