From 7eec5a2533b0ef6c233db782eb43ca80da102d7f Mon Sep 17 00:00:00 2001 From: Sam & Claude Date: Sat, 13 Jun 2026 22:28:03 +0200 Subject: [PATCH] docs: sync AGENTS.md + stale doc references to current codebase (Sam & Claude) 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 --- AGENTS.md | 58 +++++++++++++----------- docs/CLAWDIE-STUDIO-PROPOSAL.md | 26 +++++------ docs/INTEGRATION-LAYERED-SOUL.md | 8 ++-- docs/ISO-INTEGRATION-PLAN.md | 8 ++-- docs/MULTIAGENT-WORKFLOW-IMPROVEMENTS.md | 8 ++-- docs/T1.4-PROMPT-DISCIPLINE-PLAN.md | 2 +- 6 files changed, 57 insertions(+), 53 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e835244..70bbfc8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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/-HANDOFF.md` — always update before handing off +- **Handoff doc:** `docs/-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 diff --git a/docs/CLAWDIE-STUDIO-PROPOSAL.md b/docs/CLAWDIE-STUDIO-PROPOSAL.md index 358e0bc..fdb37bc 100644 --- a/docs/CLAWDIE-STUDIO-PROPOSAL.md +++ b/docs/CLAWDIE-STUDIO-PROPOSAL.md @@ -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 diff --git a/docs/INTEGRATION-LAYERED-SOUL.md b/docs/INTEGRATION-LAYERED-SOUL.md index a70dc4f..bc446da 100644 --- a/docs/INTEGRATION-LAYERED-SOUL.md +++ b/docs/INTEGRATION-LAYERED-SOUL.md @@ -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) diff --git a/docs/ISO-INTEGRATION-PLAN.md b/docs/ISO-INTEGRATION-PLAN.md index ba31a2b..33543c7 100644 --- a/docs/ISO-INTEGRATION-PLAN.md +++ b/docs/ISO-INTEGRATION-PLAN.md @@ -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 diff --git a/docs/MULTIAGENT-WORKFLOW-IMPROVEMENTS.md b/docs/MULTIAGENT-WORKFLOW-IMPROVEMENTS.md index b961f4e..c7fd83a 100644 --- a/docs/MULTIAGENT-WORKFLOW-IMPROVEMENTS.md +++ b/docs/MULTIAGENT-WORKFLOW-IMPROVEMENTS.md @@ -10,7 +10,7 @@ The Colibri project uses a multiagent development model where different AI agent ## 1. Agent Handoff Protocol -**File**: `doc/-HANDOFF.md` +**File**: `docs/-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/-HANDOFF.md` with handoff details +3. Update `docs/-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/-HANDOFF.md` platform matrix +3. Update `docs/-HANDOFF.md` platform matrix 4. Commit manifests to `manifests/` directory ### Updating Handoff Protocol -1. Modify `doc/-HANDOFF.md` template +1. Modify `docs/-HANDOFF.md` template 2. Update handoff history format 3. Communicate changes to all agents diff --git a/docs/T1.4-PROMPT-DISCIPLINE-PLAN.md b/docs/T1.4-PROMPT-DISCIPLINE-PLAN.md index e2c64a0..fb4054b 100644 --- a/docs/T1.4-PROMPT-DISCIPLINE-PLAN.md +++ b/docs/T1.4-PROMPT-DISCIPLINE-PLAN.md @@ -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