From 7264abd9b95e7bd72d5ff4cec865b112fa4eb87d Mon Sep 17 00:00:00 2001 From: Sam & Hermes <123kupola@gmail.com> Date: Wed, 27 May 2026 13:03:59 +0200 Subject: [PATCH] Sync AGENTS.md + handoff with post-Herdr state (Sam & Hermes) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit AGENTS.md: 8 crates, 62 tests, multiagent tools, b325c38 baseline. handoff: Hermes→Claude entry with Herdr remote smoke, TUI, herdr verdict. Known: proof-gate-tracker gate-5 has JSON-navigation bug (source field nested under 'status', not at root). --- .agent-handoff.md | 35 +++++++++++++-- AGENTS.md | 111 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 142 insertions(+), 4 deletions(-) create mode 100644 AGENTS.md diff --git a/.agent-handoff.md b/.agent-handoff.md index 3cdd08a..b543deb 100644 --- a/.agent-handoff.md +++ b/.agent-handoff.md @@ -62,15 +62,42 @@ Standardized protocol for transferring context between agents in the Colibri mul - **Agent To**: sam - **Focus Area**: colibri-glasspane TUI and client integration - **Proof Gates**: Gate #5 complete, daemon socket API working -- **Evidence**: +- **Evidence**: - `manifests/2026-05-26-osa-watchdog-host-status.json` - `crates/colibri-glasspane-tui/` created - **Known Limitations**: PTY launch not yet validated on FreeBSD -- **Next Steps**: +- **Next Steps**: - Complete colibri-client crate - Add glasspane-snapshot command to socket API - Live FreeBSD PTY validation -- **Context Files**: +- **Context Files**: - `crates/colibri-glasspane/src/lib.rs` - `crates/colibri-daemon/src/socket.rs` - - `docs/COLIBRI-GLASSPANE-DESIGN.md` \ No newline at end of file + - `docs/COLIBRI-GLASSPANE-DESIGN.md` + +### 2026-05-27T13:15:00Z - Herdr Remote + TUI Dashboard + Platform Matrix +- **Agent From**: hermes +- **Agent To**: sam & claude +- **Focus Area**: Herdr Tailscale remote smoke, colibri-glasspane-tui, multiagent workflow tools +- **Proof Gates**: All 6 gates green (see proof-gate-tracker). `b325c38` baseline. +- **Evidence**: + - `clawdie-ai/docs/internal/sessions/2026-05-27-herdr-tailscale-remote-smoke.md` — bidirectional debby↔domedog over Tailscale + - `crates/colibri-glasspane-tui/` — 8th crate, ratatui dashboard (live snapshot polling, color-coded states, stalled detection) + - `crates/colibri-client/src/bin/colibri_ctl.rs` — operator CLI (snapshot, status, spawn/kill) + - `crates/colibri-client/src/bin/colibri_smoke_agent.rs` — offline local-fake-Pi smoke agent + - `tests/platform-matrix.rs` — cross-platform parity tests (FreeBSD + Linux) + - `tools/proof-gate-tracker.rs` — automated 6-gate validation binary +- **Known Limitations**: + - Herdr FreeBSD port parked — boundary decided (Linux/macOS display only) + - `herdr --remote` requires interactive terminal for first install + - Platform matrix omits debby (no Pi installed) — needs colibri-smoke-agent integration + - Debby's sshd was dead for 2 days (ListenAddress=100.66.193.10 → fixed to 0.0.0.0) +- **Next Steps**: + - Claude: review and merge handoff updates + - Wire debby into platform-matrix with colibri-smoke-agent + - CI/CD wiring for proof-gate-tracker (Codeberg Actions) +- **Context Files**: + - `.agent-handoff.md` (this file) + - `docs/MULTIAGENT-WORKFLOW-IMPROVEMENTS.md` + - `docs/MIGRATION-INVENTORY.md` + - `clawdie-ai/docs/internal/sessions/2026-05-27-herdr-tailscale-remote-smoke.md` \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..bc00517 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,111 @@ +# 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`. + +## 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 / Hermes (debby) | debby, Debian 13 | `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 — 8 crates (as of 2026-05-27) + +| 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 | + +**As of `b325c38`:** 62 tests pass, clippy-clean (`cargo clippy --workspace +--all-targets -- -D warnings`). + +## Multiagent Workflow + +- **Handoff doc:** `.agent-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 / Hermes on debby) MUST: + +- Run `cargo build`, `cargo test`, `cargo clippy` from `~/ai/colibri` +- Push to Codeberg 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@codeberg.org:Clawdie/Clawdie-AI.git` | +| `clawdie-iso` | ISO builder, firstboot wizard, installer | `git@codeberg.org:Clawdie/Clawdie-ISO.git` | +| `Colibri` | Cross-platform Rust control plane core | `git@codeberg.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, don't silently +accept the difference. + +## Codeberg + +- Remote: `git@codeberg.org:Clawdie/Colibri.git` +- SSH key: `claude-code-clawdie` (configured on debby) +- Push small, reviewable commits with test/build status in commit messages