Sam & Claude
524ccbff40
Remove genuinely-stale docs (decision/evidence now elsewhere): - TRUSS-SPAWN-ANALYSIS.md — debug trace of a jail-spawn bug that was fixed - PLAN-MOTHER-MCP-VAULT-KEYS.md — planned a vaultwarden-pubkey exchange; the shipped mother MCP is seed-based (wiki/mother-hive + MOTHER-SETUP) - PRIORITY-HANDOFF-ISO-SPAWN-COST.md — self-superseded by MULTI-AGENT-HOST-PLAN Repointed referrers (README, AGENTS, FREEBSD-BUILD-LANE-HANDOFF, docs/README) to MULTI-AGENT-HOST-PLAN. Fixed the wiki ADR note (the stale 'referenced in stage-colibri-iso.sh' claim — those refs were already cleaned up). KEPT the two design docs (COLIBRI-JAILED-AGENT-SPAWN-DESIGN, COLIBRI-EXTERNAL-MCP-PROTOTYPE): on closer look they hold how-it-works detail the wiki only summarizes + links, so folding would lose detail or bloat the wiki. Gates: wiki-lint --strict (131) + markdown format clean.
251 lines
12 KiB
Markdown
251 lines
12 KiB
Markdown
# 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.
|