clawdie/colibri
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 15

docs: tidy formatting, add docs index, and refresh README status line #63

Merged
clawdie merged 1 commit from docs/polish-formatting-index-status into main 2026-06-14 13:36:48 +02:00
Conversation 0 Commits 1 Files changed 3 +55 -27
3 changed files with 55 additions and 27 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
README.md
View file

@ -4,7 +4,7 @@ The Clawdie control plane core — a small, cross-platform (FreeBSD + Linux) Rus
daemon that unifies coordination (task board, agent registry, skills catalog)
with cache-first cost discipline (byte-stable prompt prefixes, cache-hit metering).
**Status:** workspace gates are expected to be fmt/clippy/test/release green. Avoid fixed crate/test counts here — see the crate table below and run the gate commands for the current state. Phase 3 (coordination core) is in progress.
**Status:** workspace gates are fmt/clippy/test/release green. Round 2 audit is closed. Current priorities: ISO staging wiring, Pi spawn end-to-end, and cost-mode enforcement (see [`docs/PRIORITY-HANDOFF-ISO-SPAWN-COST.md`](docs/PRIORITY-HANDOFF-ISO-SPAWN-COST.md)). Avoid fixed crate/test counts here — see the crate table below and run the gate commands for the current state.
Next ISO integration plan: `docs/ISO-INTEGRATION-PLAN.md`.
ISO acceptance runbook: `docs/ISO-ACCEPTANCE-RUNBOOK.md`.

56
docs/PRIORITY-HANDOFF-ISO-SPAWN-COST.md
View file

@ -26,13 +26,13 @@ blocks Gate 1 (passive service) entirely.
### What exists
| Artifact | Location | Status |
| -------- | --------- | ------ |
| staging script | `scripts/stage-colibri-iso.sh` | done — copies `colibri-daemon`, `colibri`, `colibri-smoke-agent`, rc.d, newsyslog, creates dirs |
| rc.d script | `packaging/freebsd/colibri_daemon.in` | done — `start_precmd`, pidfile, daemon(8) wrapper, `COLIBRI_COST_MODE` propagation |
| newsyslog config | `packaging/freebsd/newsyslog-colibri.conf` | done |
| rc.conf.sample | generated by staging script | done |
| acceptance runbook | `docs/ISO-ACCEPTANCE-RUNBOOK.md` | done |
| Artifact | Location | Status |
| ------------------ | ------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| staging script | `scripts/stage-colibri-iso.sh` | done — copies `colibri-daemon`, `colibri`, `colibri-smoke-agent`, rc.d, newsyslog, creates dirs |
| rc.d script | `packaging/freebsd/colibri_daemon.in` | done — `start_precmd`, pidfile, daemon(8) wrapper, `COLIBRI_COST_MODE` propagation |
| newsyslog config | `packaging/freebsd/newsyslog-colibri.conf` | done |
| rc.conf.sample | generated by staging script | done |
| acceptance runbook | `docs/ISO-ACCEPTANCE-RUNBOOK.md` | done |
### What's missing
@ -110,14 +110,14 @@ JSONL events flow through to state transitions.
### What exists
| Capability | Location | Status |
| ---------- | -------- | ------ |
| `Spawner::spawn()` | `crates/colibri-daemon/src/spawner.rs:585` | done — provider routing, jail wrap, retry/backoff |
| `AgentHandle` | `crates/colibri-daemon/src/spawner.rs:465` | done — tracks child, stdout for glasspane, kill, poll_exit |
| `take_stdout()` | `crates/colibri-daemon/src/spawner.rs:500` | done — hands stdout to glasspane supervision |
| Jail confinement | `crates/colibri-daemon/src/spawner.rs:332` | done — named/ephemeral, staged env payload, priv modes |
| `fake-pi-agent.py` | `scripts/fake-pi-agent.py` | exists — emits JSONL events for testing |
| Glasspane ingestion | `crates/colibri-glasspane/` | done — ingests JSONL, tracks pane state |
| Capability | Location | Status |
| ------------------- | ------------------------------------------ | ---------------------------------------------------------- |
| `Spawner::spawn()` | `crates/colibri-daemon/src/spawner.rs:585` | done — provider routing, jail wrap, retry/backoff |
| `AgentHandle` | `crates/colibri-daemon/src/spawner.rs:465` | done — tracks child, stdout for glasspane, kill, poll_exit |
| `take_stdout()` | `crates/colibri-daemon/src/spawner.rs:500` | done — hands stdout to glasspane supervision |
| Jail confinement | `crates/colibri-daemon/src/spawner.rs:332` | done — named/ephemeral, staged env payload, priv modes |
| `fake-pi-agent.py` | `scripts/fake-pi-agent.py` | exists — emits JSONL events for testing |
| Glasspane ingestion | `crates/colibri-glasspane/` | done — ingests JSONL, tracks pane state |
### What's missing
@ -141,9 +141,11 @@ JSONL events flow through to state transitions.
3. **`spawn-local` socket command (if not present).**
An operator CLI path to manually spawn a local binary for debugging:
```sh
colibri spawn-local /path/to/pi --session-id test-1
```
This may already exist as a socket command — check `socket.rs` for
`SpawnLocal` or `Spawn` command variants.
@ -176,7 +178,7 @@ Cost modes (`Fast`/`Smart`/`Max`) are the core design promise of Colibri —
escalation, compaction, trimming) but **they are not connected**. Right now
changing the cost mode does nothing to actual session behavior.
This is the most subtle gap because the code *looks* like it's wired up — the
This is the most subtle gap because the code _looks_ like it's wired up — the
functions exist and have tests — but the call sites are missing or duplicated.
### The disconnection (detailed)
@ -186,6 +188,7 @@ There are **two compaction paths** that use different sources of truth:
**Path A — per-append (session.rs):**
`session.rs:397-398` in `maybe_compact_or_rollover()`:
```rust
let needs_compaction = byte_count > self.config.session_max_bytes
|| turn_count > self.config.max_uncompacted_turns;
@ -200,6 +203,7 @@ values) regardless of the cost mode string.
**Path B — background rotation (daemon.rs):**
`daemon.rs:242-261` in `session_rotation()`:
```rust
let cost_mode = crate::cost::CostMode::parse(&state.config.cost_mode).unwrap_or_default();
let max_bytes = cost_mode.session_max_bytes();
@ -216,12 +220,12 @@ loop catches up.
### What's never called
| Function | Location | Problem |
| -------- | -------- | ------- |
| `auto_escalate()` | `cost.rs:131` | Tested but **never called** from daemon loop or session code |
| `compact_tool_result()` | `cost.rs:165` | Tested but **never called** when appending `ToolResult` entries |
| Function | Location | Problem |
| ---------------------------------- | ---------------- | --------------------------------------------------------------------------------------- |
| `auto_escalate()` | `cost.rs:131` | Tested but **never called** from daemon loop or session code |
| `compact_tool_result()` | `cost.rs:165` | Tested but **never called** when appending `ToolResult` entries |
| `PromptAssembly::trim_to_budget()` | `session.rs:117` | Tested but **never called** from `build_prompt_assembly()` or `build_prompt_messages()` |
| `EscalationTrigger` | `cost.rs:117` | Type exists, tested, never constructed in production code |
| `EscalationTrigger` | `cost.rs:117` | Type exists, tested, never constructed in production code |
### What `set-cost-mode` does
@ -280,11 +284,11 @@ wiring, no platform-specific behavior.
## Summary table
| # | Item | Blocks | Linux-doable | Effort |
| - | ---- | ------ | ------------ | ------ |
| 1 | ISO staging wiring | Gate 1 | partially (needs FreeBSD binaries) | medium |
| 2 | Pi spawn end-to-end | Gate 2 | yes (with fake-pi-agent.py) | medium |
| 3 | Cost mode enforcement | core design promise | yes (pure logic) | medium |
| # | Item | Blocks | Linux-doable | Effort |
| --- | --------------------- | ------------------- | ---------------------------------- | ------ |
| 1 | ISO staging wiring | Gate 1 | partially (needs FreeBSD binaries) | medium |
| 2 | Pi spawn end-to-end | Gate 2 | yes (with fake-pi-agent.py) | medium |
| 3 | Cost mode enforcement | core design promise | yes (pure logic) | medium |
All three are medium effort and can be worked in parallel. None require
FreeBSD to implement — only to validate the final result.

24
docs/README.md Normal file
View file

@ -0,0 +1,24 @@
# Colibri Docs Index
A quick-reference guide to every document in this folder.
| Document | One-liner | Audience |
| ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- | --------------- |
| [`ADR-agent-harness-consolidation.md`](ADR-agent-harness-consolidation.md) | zot = agent, Colibri = control plane — accepted ADR | All agents |
| [`CLAWDIE-INSTALLER-HANDOFF.md`](CLAWDIE-INSTALLER-HANDOFF.md) | FreeBSD validation handoff for the `clawdie` installer | Codex (FreeBSD) |
| [`CLAWDIE-STUDIO-PROPOSAL.md`](CLAWDIE-STUDIO-PROPOSAL.md) | Zed/Claude Code + control plane integration proposal | Sam & agents |
| [`COLIBRI-DAEMON-GLASSPANE-INTEGRATION.md`](COLIBRI-DAEMON-GLASSPANE-INTEGRATION.md) | Binding contract between `colibri-daemon` and `colibri-glasspane` | Rust agents |
| [`COLIBRI-EXTERNAL-MCP-PROTOTYPE.md`](COLIBRI-EXTERNAL-MCP-PROTOTYPE.md) | Prototype for Colibri acting as an MCP host for external servers | Agents |
| [`COLIBRI-GLASSPANE-DESIGN.md`](COLIBRI-GLASSPANE-DESIGN.md) | Agent supervision (sessions/panes/state) design rationale | All agents |
| [`COLIBRI-JAILED-AGENT-SPAWN-DESIGN.md`](COLIBRI-JAILED-AGENT-SPAWN-DESIGN.md) | FreeBSD jail confinement for spawned agents — accepted & implemented | Rust agents |
| [`COLIBRI-SKILLS-PLAN.md`](COLIBRI-SKILLS-PLAN.md) | Skills catalog roadmap: read-only Phase 1, write-gated Phase 2+ | Agents |
| [`COLIBRI-TOKENOMICS-TRIFECTA.md`](COLIBRI-TOKENOMICS-TRIFECTA.md) | Strategic vision: useful tokens, cost-per-intelligence, measurement | All |
| [`HEADROOM-SIDECAR.md`](HEADROOM-SIDECAR.md) | Optional `headroom-ai` tool-result compression sidecar | Agents |
| [`HERDR-VS-COLIBRI-GRAPH.md`](HERDR-VS-COLIBRI-GRAPH.md) | Capability comparison + drop map for Herdr → Colibri migration | All |
| [`INTEGRATION-LAYERED-SOUL.md`](INTEGRATION-LAYERED-SOUL.md) | How Colibri consumes `layered-soul` reviewed context today vs planned | Agents |
| [`ISO-ACCEPTANCE-RUNBOOK.md`](ISO-ACCEPTANCE-RUNBOOK.md) | Post-boot acceptance commands after staging Colibri into an ISO | Codex (FreeBSD) |
| [`ISO-INTEGRATION-PLAN.md`](ISO-INTEGRATION-PLAN.md) | Full plan to replace the TypeScript control path with Rust in the ISO | All |
| [`ISO-SERVICE-LAYOUT.md`](ISO-SERVICE-LAYOUT.md) | `rc.conf` service layout for the ISO image | All |
| [`MULTIAGENT-WORKFLOW-IMPROVEMENTS.md`](MULTIAGENT-WORKFLOW-IMPROVEMENTS.md) | Tracking gates, proof-gate-tracker, platform-matrix tests | All agents |
| [`PRIORITY-HANDOFF-ISO-SPAWN-COST.md`](PRIORITY-HANDOFF-ISO-SPAWN-COST.md) | **Current sprint**: ISO staging wiring, Pi spawn path, cost mode enforcement | All agents |
| [`T1.4-PROMPT-DISCIPLINE-PLAN.md`](T1.4-PROMPT-DISCIPLINE-PLAN.md) | Cache-first prompt assembly: byte-stable prefixes + hit metering | Rust agents |