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

chore(docs): prettier-fix pre-existing markdown drift #110

Merged
clawdie merged 1 commit from fix/markdown-format-drift into main 2026-06-20 17:49:43 +02:00
Conversation 0 Commits 1 Files changed 2 +49 -47
2 changed files with 49 additions and 47 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

68
docs/MULTI-AGENT-HOST-PLAN.md
View file

@ -46,14 +46,14 @@ The multi-host stack lives **outside the Rust daemon**:
### Socket command inventory (17 commands, all Unix-socket)
| Category | Commands |
|----------|----------|
| Daemon | `status`, `glasspane-snapshot`, `set-cost-mode` |
| Session | `list-sessions`, `get-session`, `compact-session` |
| Agent process | `spawn-agent`, `kill-agent` |
| Board | `list-tasks`, `create-task`, `transition-task`, `claim-task`, `intake-task` |
| Agent registry | `register-agent`, `list-agents` |
| Skills | `list-skills`, `register-skill` |
| Category | Commands |
| -------------- | --------------------------------------------------------------------------- |
| Daemon | `status`, `glasspane-snapshot`, `set-cost-mode` |
| Session | `list-sessions`, `get-session`, `compact-session` |
| Agent process | `spawn-agent`, `kill-agent` |
| Board | `list-tasks`, `create-task`, `transition-task`, `claim-task`, `intake-task` |
| Agent registry | `register-agent`, `list-agents` |
| Skills | `list-skills`, `register-skill` |
### CLI surface (10 of 17 commands exposed)
@ -79,15 +79,15 @@ socket calls.
### What is NOT tested
| # | Gap | Severity | Linux-doable? |
|---|-----|----------|---------------|
| 1 | **Multi-agent task-board contention** — `pick_agent` only tested with 0-1 agents; no capability-based multi-agent assignment test; no same-agent-multiple-tasks test | High | Yes |
| 2 | **CLI surface gaps** — `claim-task`, `transition-task`, `register-agent`, `list-agents` have no CLI; remote agents forced to use raw Python | Medium | Yes |
| 3 | **Agent presence model** — no `host` column, no `last_seen`, no heartbeat/lease; cannot detect stale remote agents | High | Yes (schema change) |
| 4 | **Remote-safe task claim** — `claim_task` is a blind UPDATE, no concurrency safety, no lease/TTL | Medium | Yes |
| 5 | **Python polling scripts** — `colibri_poll.py` and `colibri_task_done.py` have zero test coverage | Medium | Yes |
| 6 | **TCP bridge round-trip** — socat bridge untested end-to-end | Medium | Partial (needs socat or FreeBSD) |
| 7 | **Cross-host coordination** — no test simulates a remote agent claiming/transitioning a task over the bridge | High | FreeBSD only |
| # | Gap | Severity | Linux-doable? |
| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------- |
| 1 | **Multi-agent task-board contention** — `pick_agent` only tested with 0-1 agents; no capability-based multi-agent assignment test; no same-agent-multiple-tasks test | High | Yes |
| 2 | **CLI surface gaps** — `claim-task`, `transition-task`, `register-agent`, `list-agents` have no CLI; remote agents forced to use raw Python | Medium | Yes |
| 3 | **Agent presence model** — no `host` column, no `last_seen`, no heartbeat/lease; cannot detect stale remote agents | High | Yes (schema change) |
| 4 | **Remote-safe task claim** — `claim_task` is a blind UPDATE, no concurrency safety, no lease/TTL | Medium | Yes |
| 5 | **Python polling scripts** — `colibri_poll.py` and `colibri_task_done.py` have zero test coverage | Medium | Yes |
| 6 | **TCP bridge round-trip** — socat bridge untested end-to-end | Medium | Partial (needs socat or FreeBSD) |
| 7 | **Cross-host coordination** — no test simulates a remote agent claiming/transitioning a task over the bridge | High | FreeBSD only |
---
@ -100,12 +100,12 @@ socket calls.
Existing tests cover: best match (2 agents, different caps), offline exclusion,
no-match, empty-required. Add:
| Test | What it proves |
|------|---------------|
| Test | What it proves |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `test_pick_agent_partial_match_wins_over_no_match` | Agent with `["rust","freebsd"]` beats agent with `["python"]` for required `["freebsd"]` |
| `test_pick_agent_tie_breaking` | Two agents with same score — verify deterministic tie-break (later name wins) |
| `test_pick_agent_multiple_required_capabilities` | Required `["rust","freebsd"]` — agent with both beats agent with one |
| `test_pick_agent_active_status_eligible` | `status: "active"` is treated same as `"idle"` (both eligible) |
| `test_pick_agent_tie_breaking` | Two agents with same score — verify deterministic tie-break (later name wins) |
| `test_pick_agent_multiple_required_capabilities` | Required `["rust","freebsd"]` — agent with both beats agent with one |
| `test_pick_agent_active_status_eligible` | `status: "active"` is treated same as `"idle"` (both eligible) |
#### 1b. Multi-agent board integration test — new file `crates/colibri-daemon/tests/multi_agent_board.rs`
@ -150,6 +150,7 @@ tasks.
#### 2a. Merge `feat/cli-register-agent` (existing branch, 64 lines, client-only)
The branch is clean and ready:
- `Command::RegisterAgent { name, capabilities }` + `Command::ListAgents`
- `parse_capabilities()` helper (reuses `--capability`/`--capabilities` pattern)
- `DaemonClient::register_agent()` + `DaemonClient::list_agents()`
@ -170,6 +171,7 @@ colibri transition-task --task-id <UUID> --status done|failed
```
Implementation:
- Add `Command::ClaimTask { task_id, agent_id }` and
`Command::TransitionTask { task_id, status }` variants
- Add `DaemonClient::claim_task()` and `DaemonClient::transition_task()`
@ -209,17 +211,17 @@ mesh.**
## Summary
| Phase | What | Files | Linux? | Status |
|-------|------|-------|--------|--------|
| 1a | `pick_agent` unit tests | `scheduler.rs` tests | Yes | Ready |
| 1b | Multi-agent board integration test | `tests/multi_agent_board.rs` (new) | Yes | Ready |
| 1c | Same-capability multi-task test | Same file | Yes | Ready |
| 2a | Merge `feat/cli-register-agent` | `colibri.rs` + `lib.rs` | Yes | Branch exists |
| 2b | Add `claim-task` + `transition-task` CLI | `colibri.rs` + `lib.rs` | Yes | Ready |
| 2c | CLI parse tests | `colibri.rs` tests | Yes | Ready |
| 3 | Agent presence schema | `schema.rs` + `lib.rs` + `socket.rs` | Yes | Deferred |
| 4 | Polling workflow test | `tests/` | Yes | Deferred (needs Phase 2) |
| 5 | TCP bridge validation | FreeBSD host | No | FreeBSD lane |
| Phase | What | Files | Linux? | Status |
| ----- | ---------------------------------------- | ------------------------------------ | ------ | ------------------------ |
| 1a | `pick_agent` unit tests | `scheduler.rs` tests | Yes | Ready |
| 1b | Multi-agent board integration test | `tests/multi_agent_board.rs` (new) | Yes | Ready |
| 1c | Same-capability multi-task test | Same file | Yes | Ready |
| 2a | Merge `feat/cli-register-agent` | `colibri.rs` + `lib.rs` | Yes | Branch exists |
| 2b | Add `claim-task` + `transition-task` CLI | `colibri.rs` + `lib.rs` | Yes | Ready |
| 2c | CLI parse tests | `colibri.rs` tests | Yes | Ready |
| 3 | Agent presence schema | `schema.rs` + `lib.rs` + `socket.rs` | Yes | Deferred |
| 4 | Polling workflow test | `tests/` | Yes | Deferred (needs Phase 2) |
| 5 | TCP bridge validation | FreeBSD host | No | FreeBSD lane |
**Immediate scope:** Phases 1-2. All testable on Linux with `cargo test` +
`cargo clippy` gate. No FreeBSD dependency for implementation.

28
docs/README.md
View file

@ -2,17 +2,17 @@
A quick-reference guide to every document in this folder.
| Document | One-liner | Audience |
| ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- | --------------- |
| [`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 (bare-metal deployment option) | Sam & agents |
| [`COLIBRI-EXTERNAL-MCP-PROTOTYPE.md`](COLIBRI-EXTERNAL-MCP-PROTOTYPE.md) | Colibri as MCP host for external stdio servers (jailed, 3-tier trust) | 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 |
| [`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-SERVICE-LAYOUT.md`](ISO-SERVICE-LAYOUT.md) | `rc.conf` service layout for the ISO image | All |
| [`MULTI-AGENT-HOST-PLAN.md`](MULTI-AGENT-HOST-PLAN.md) | **Current sprint**: multi-agent task-board tests + CLI surface gaps | All agents |
| [`PRIORITY-HANDOFF-ISO-SPAWN-COST.md`](PRIORITY-HANDOFF-ISO-SPAWN-COST.md) | ISO boot validation, Pi spawn path, cost mode enforcement (P2/P3 done) | All agents |
| Document | One-liner | Audience |
| ------------------------------------------------------------------------------ | -------------------------------------------------------------------------- | --------------- |
| [`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 (bare-metal deployment option) | Sam & agents |
| [`COLIBRI-EXTERNAL-MCP-PROTOTYPE.md`](COLIBRI-EXTERNAL-MCP-PROTOTYPE.md) | Colibri as MCP host for external stdio servers (jailed, 3-tier trust) | 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 |
| [`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-SERVICE-LAYOUT.md`](ISO-SERVICE-LAYOUT.md) | `rc.conf` service layout for the ISO image | All |
| [`MULTI-AGENT-HOST-PLAN.md`](MULTI-AGENT-HOST-PLAN.md) | **Current sprint**: multi-agent task-board tests + CLI surface gaps | All agents |
| [`PRIORITY-HANDOFF-ISO-SPAWN-COST.md`](PRIORITY-HANDOFF-ISO-SPAWN-COST.md) | ISO boot validation, Pi spawn path, cost mode enforcement (P2/P3 done) | All agents |