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

docs: sync AGENTS.md + stale doc references to current codebase (Sam & Claude)
Some checks failed
CI / rust (pull_request) Has been cancelled
Details
CI / markdown (pull_request) Has been cancelled
Details

Browse source 
AGENTS.md:
- Crate table: add colibri-store, colibri-skills, colibri-mcp (was 8, now 11)
- Remove stale 'Next planned crate' section (skills + mcp both scaffolded)
- Add Jail Confinement + Skills/External MCP sections
- Fix doc/ -> docs/ paths
- Replace stale Herdr remote smoke ref with external MCP doc

ISO-INTEGRATION-PLAN.md:
- Jail status: MISSING -> READY (shipped PRs #35/#37/#39)
- Pi jail workers: 'design only' -> 'shipped'

CLAWDIE-STUDIO-PROPOSAL.md:
- colibri-harness -> colibri-glasspane-tui (correct crate name)
- colibri-mcp: remove 'NEW' marker (exists + has external host)
- colibri-skills: remove 'future' marker

T1.4-PROMPT-DISCIPLINE-PLAN.md:
- colibri-skills: 'parked on feature branch' -> 'scaffolded workspace member'

MULTIAGENT-WORKFLOW-IMPROVEMENTS.md:
- Fix doc/ -> docs/ paths
This commit is contained in:
Sam & Claude 2026-06-13 22:28:03 +02:00
parent 23aef71fc9
commit 7eec5a2533
6 changed files with 57 additions and 53 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

58
AGENTS.md
View file

@ -48,19 +48,21 @@ Target: `x86_64-unknown-freebsd` (Rust Tier-2). TLS is `rustls` to avoid
## 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 |
| `colibri-client` | Typed Unix-socket client + operator CLI tools |
| `colibri-glasspane-tui` | ratatui dashboard — live pane supervision |
| `colibri` (root) | Workspace root + probe binaries |
| 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) |
| `colibri` (root) | Workspace root + probe binaries |
The workspace currently has 8 crates. `colibri-skills` is planned as the next
split-brain crate and would become the ninth crate when scaffolded.
The workspace currently has 11 crates (10 members + root).
Gate status should be rechecked from source instead of relying on a fixed test
count:
@ -72,30 +74,32 @@ cargo test --workspace
cargo build --workspace --release
```
## Next planned crate
## Jail Confinement
The next split-brain lane is documented first, not scaffolded blindly:
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`).
- `docs/COLIBRI-SKILLS-PLAN.md`
Design doc: `docs/COLIBRI-JAILED-AGENT-SPAWN-DESIGN.md`
This is the planned Rust read path for Clawdie's built-in handbook / manuals
lane:
## Skills & External MCP
- DB: `system_skills`
- source of truth: committed built-in knowledge artifact
- scope: read-only consumer first
`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`.
It is intentionally separate from:
- `system_brain` user/agent memory
- `system_ops` runtime state
See `docs/COLIBRI-EXTERNAL-MCP-PROTOTYPE.md` and
`docs/CLAWDIE-STUDIO-PROPOSAL.md`.
## Multiagent Workflow
- **Handoff doc:** `doc/<FEATURE>-HANDOFF.md` — always update before handing off
- **Handoff doc:** `docs/<FEATURE>-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`
- **External MCP smoke:** see `docs/COLIBRI-EXTERNAL-MCP-PROTOTYPE.md`
## Linux Agent Constraints
@ -117,7 +121,7 @@ Linux agents MUST NOT:
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
- 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

26
docs/CLAWDIE-STUDIO-PROPOSAL.md
View file

@ -24,7 +24,7 @@ plane. Specifically:
can consume it trivially.
- **`colibri-client` crate** is a typed Rust client — a Zed extension or
MCP bridge can depend on it directly.
- **`colibri-harness` (TUI)** already proves "visual dashboard over
- **`colibri-glasspane-tui` (TUI)** already proves "visual dashboard over
socket" works end-to-end.
- **`colibri` CLI** already covers task/agent/status operations.
@ -39,7 +39,7 @@ clawdie-studio (the user experience)
├── colibri-daemon rc.d service, always-on, headless-safe
├── colibri-mcp MCP bridge for Zed assistant integration
├── colibri CLI operator tool
├── colibri-harness TUI fallback / SSH dashboard
├── colibri-tui TUI fallback / SSH dashboard
└── Zed editor + task panel via extension
```
@ -118,7 +118,7 @@ clawdie-studio (the package)
├── /usr/local/bin/colibri-daemon (the service)
├── /usr/local/bin/colibri (the CLI)
├── /usr/local/bin/colibri-mcp (the MCP bridge)
├── /usr/local/bin/colibri-harness (the TUI)
├── /usr/local/bin/colibri-tui (the TUI)
├── /usr/local/bin/colibri-studio (the launcher)
└── Zed extension: colibri-sidebar (the visual panel)
```
@ -165,13 +165,13 @@ COLIBRI_MCP_SPAWN_ALLOWLIST=/usr/local/bin/pi,/usr/local/bin/colibri-smoke-agent
Phase 2 MCP tools (after basics proven):
| Tool | Description |
| ------------------------- | --------------------------------------------------- |
| `colibri_spawn_agent` | Spawn an agent with provider/model config |
| `colibri_kill_agent` | Kill a running agent |
| `colibri_session_summary` | Summarize an active session |
| `colibri_schedule_job` | Add a cron/interval/one-shot job |
| `colibri_search_skills` | Search built-in knowledge (future `colibri-skills`) |
| Tool | Description |
| ------------------------- | ------------------------------------------------ |
| `colibri_spawn_agent` | Spawn an agent with provider/model config |
| `colibri_kill_agent` | Kill a running agent |
| `colibri_session_summary` | Summarize an active session |
| `colibri_schedule_job` | Add a cron/interval/one-shot job |
| `colibri_search_skills` | Search built-in knowledge (via `colibri-skills`) |
## Relationship to Existing Colibri Crates
@ -180,8 +180,8 @@ colibri-daemon ← already exists, socket API serves all clients
colibri-client ← already exists, typed Rust client
colibri-contracts ← already exists, shared wire types
colibri-glasspane ← already exists, agent supervision state
colibri-harness ← already exists, TUI dashboard
colibri-mcp ← NEW: thin MCP bridge using colibri-client
colibri-glasspane-tui ← already exists, TUI dashboard
colibri-mcp ← already exists, MCP bridge + external MCP host (PR #36)
colibri-studio ← NEW: launcher binary (thin wrapper)
```
@ -239,7 +239,7 @@ This is sufficient for the next ISO if Zed is present but the integration bridge
## Prior Art
- **Herdr** already does "visual dashboard over socket" for Linux/macOS
- **colibri-harness** already does this for TUI
- **colibri-glasspane-tui** already does this for TUI
- **Zed + MCP** is a proven integration path (Zed's assistant is MCP-native)
- **VS Code + Language Server Protocol** proved the "thin bridge over
socket" pattern works at scale

8
docs/INTEGRATION-LAYERED-SOUL.md
View file

@ -23,11 +23,11 @@ three stores — `system_skills`, `system_brain`, `system_ops`. As of 2026-06-13
only a single flat `skills` table exists; the rest is **design only**
(`docs/COLIBRI-SKILLS-PLAN.md`), so the importer intentionally does not target it.
| Layered Soul source | Target (planned) | Status |
| ---------------------------- | ---------------- | -------------------------------------------------------- |
| `skills/**/*.md` | `system_skills` | imported into the flat `skills` table today |
| Layered Soul source | Target (planned) | Status |
| ---------------------------- | ---------------- | ---------------------------------------------------------- |
| `skills/**/*.md` | `system_skills` | imported into the flat `skills` table today |
| `memories/curated/**/*.md` | `system_brain` | NOT imported — no store yet (the importer reports a count) |
| converted task/job manifests | `system_ops` | NOT implemented |
| converted task/job manifests | `system_ops` | NOT implemented |
## Direction (one-way)

8
docs/ISO-INTEGRATION-PLAN.md
View file

@ -17,7 +17,7 @@ rc.conf
-> session/prompt/cache discipline
-> glasspane supervision state
-> Pi agent/process spawning
-> future jail-backed Pi workers
-> jail-backed Pi workers (implemented — JailConfig + jail_wrap)
operator/display
-> colibri CLI
@ -146,7 +146,7 @@ DEFER intentionally out of next ISO scope
| Pi JSONL event ingestion | `colibri-glasspane` | READY | Validate against actual Pi binary in daemon spawn path. |
| local agent spawning | `Provider::Local` | READY | Keep as deterministic smoke path. |
| actual Pi spawning | local executable through daemon | PARTIAL | Prove `spawn-local /path/to/pi` with JSONL mode or add explicit Pi provider. |
| jail Pi execution | future `Provider::Jail` | MISSING | Start with static pre-created jail design/command path. |
| jail Pi execution | `JailConfig` + `jail_wrap` in spawner.rs | READY | Shipped in PRs #35/#37/#39. Static/ephemeral/named jail modes tested. |
| terminal/tmux supervision | glasspane/TUI | PARTIAL | Improve dashboard/operator UX; no tmux scrape dependency. |
| Herdr display | Linux/macOS Herdr only | DEFER | Optional remote display plane; not on ISO FreeBSD path. |
| watchdog/host safety | existing watchdog/hostd remains authoritative | PARTIAL | Colibri can observe, but must not replace safety before explicit gate. |
@ -166,7 +166,7 @@ DEFER intentionally out of next ISO scope
| Operator | status output needs enough ISO triage data | mostly addressed | Confirm status includes paths, cost, scheduler, pane/task counts | Rust/validation |
| Operator | service-level self-check command | optional | Defer unless ISO debugging proves it necessary | Rust |
| Pi | actual Pi binary spawning path not proven in Colibri daemon | open | Run `colibri spawn-local /path/to/pi --session-id ...` in JSONL mode | Rust/FreeBSD |
| Pi | jail-backed Pi workers | design only | Add provider design stub, then static pre-created jail execution | Rust |
| Pi | jail-backed Pi workers | shipped | `JailConfig` + `jail_wrap` implemented; external MCP servers can also be jailed | Rust |
| Dashboard | native FreeBSD dashboard not final UX | open | Keep `colibri-tui`/glasspane responsive; show status/cost/tasks | Rust/UI |
| Cutover | TS control plane still load-bearing | expected | Retire only after parity/takeover gates | Coordination |
| Desktop | live USB Zed/GPU acceptance not rerun | deferred | Run once Hermes no longer needs test machine | Final acceptance |
@ -354,7 +354,7 @@ Implementation-heavy tasks suitable for Hermes:
3. Wire cost mode thresholds into actual session rotation/compaction decisions if not already fully connected.
4. Harden rc.d script against reboot/tmpfs `/var/run` behavior.
5. Add image-root staging script or packaging notes for binaries + rc.d + directories.
6. Start `Provider::Jail` design stub and type-level wiring without committing to full jail lifecycle yet.
6. ~~Start `Provider::Jail` design stub and type-level wiring~~ — **done** (PRs #35/#37/#39, `JailConfig` + `jail_wrap` shipped).
## Planning/documentation task queue

8
docs/MULTIAGENT-WORKFLOW-IMPROVEMENTS.md
View file

@ -10,7 +10,7 @@ The Colibri project uses a multiagent development model where different AI agent
## 1. Agent Handoff Protocol
**File**: `doc/<FEATURE>-HANDOFF.md`
**File**: `docs/<FEATURE>-HANDOFF.md`
### Purpose
@ -249,7 +249,7 @@ When an agent completes work:
1. Run `proof-gate-tracker` and verify all critical gates pass
2. Run `cargo test --workspace` and verify all tests pass
3. Update `doc/<FEATURE>-HANDOFF.md` with handoff details
3. Update `docs/<FEATURE>-HANDOFF.md` with handoff details
4. Commit and push with clear handoff message
---
@ -267,12 +267,12 @@ When an agent completes work:
1. Add platform to `PlatformMatrix` tests in `tests/platform-matrix.rs`
2. Add validation criteria
3. Update `doc/<FEATURE>-HANDOFF.md` platform matrix
3. Update `docs/<FEATURE>-HANDOFF.md` platform matrix
4. Commit manifests to `manifests/` directory
### Updating Handoff Protocol
1. Modify `doc/<FEATURE>-HANDOFF.md` template
1. Modify `docs/<FEATURE>-HANDOFF.md` template
2. Update handoff history format
3. Communicate changes to all agents

2
docs/T1.4-PROMPT-DISCIPLINE-PLAN.md
View file

@ -240,7 +240,7 @@ echo '{"cmd":"status"}' | nc -U /tmp/colibri-daemon.sock
## What NOT to change
- `PiJsonlIngestor` in glasspane — unrelated
- `colibri-skills` crate — unrelated (parked on feature branch)
- `colibri-skills` crate — unrelated (scaffolded workspace member)
- `zot-runtime-event-adapter` — unrelated (parked on feature branch)
- `colibri-contracts` — ProviderSmokeResult/RunManifest types are stable
- `colibri-store` — SQLite schema unchanged