From c2655d1d418262bc9ef5fdfcf5f665b4e8569a0a Mon Sep 17 00:00:00 2001 From: Sam & Claude Date: Wed, 27 May 2026 14:00:44 +0200 Subject: [PATCH] Document planned colibri-skills split-brain lane (Sam & Codex) --- AGENTS.md | 18 ++++ README.md | 5 + docs/COLIBRI-SKILLS-PLAN.md | 181 ++++++++++++++++++++++++++++++++++++ 3 files changed, 204 insertions(+) create mode 100644 docs/COLIBRI-SKILLS-PLAN.md diff --git a/AGENTS.md b/AGENTS.md index bc00517..9e4b9c3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -41,6 +41,24 @@ Target: `x86_64-unknown-freebsd` (Rust Tier-2). TLS is `rustls` to avoid **As of `b325c38`:** 62 tests pass, clippy-clean (`cargo clippy --workspace --all-targets -- -D warnings`). +## Next planned crate + +The next split-brain lane is documented first, not scaffolded blindly: + +- `docs/COLIBRI-SKILLS-PLAN.md` + +This is the planned Rust read path for Clawdie's built-in handbook / manuals +lane: + +- DB: `system_skills` +- source of truth: committed built-in knowledge artifact +- scope: read-only consumer first + +It is intentionally separate from: + +- `system_brain` user/agent memory +- `system_ops` runtime state + ## Multiagent Workflow - **Handoff doc:** `.agent-handoff.md` — always update before handing off diff --git a/README.md b/README.md index 49bf9ab..b7a102b 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,11 @@ and Postgres. Design + implementation path: see `doc/COLIBRI-CONTROLPLANE-PLAN.md` in `clawdie-ai`. +Planned next split-brain slice: + +- `docs/COLIBRI-SKILLS-PLAN.md` — read-only Rust access layer for the + "manuals already included" / `system_skills` lane + ## Phase 1 — `colibri-probe` A falsifiable first build that proves three things at once: diff --git a/docs/COLIBRI-SKILLS-PLAN.md b/docs/COLIBRI-SKILLS-PLAN.md new file mode 100644 index 0000000..609bd2a --- /dev/null +++ b/docs/COLIBRI-SKILLS-PLAN.md @@ -0,0 +1,181 @@ +# Colibri Skills Plan + +**Date:** 27.maj.2026 +**Status:** PLANNED — docs first, no crate scaffold yet + +## Purpose + +Define the next Colibri slice for Clawdie's split-brain model: + +- **built-in knowledge** stays separate from +- **user/agent memory** and +- **operational state** + +The product explanation is simple: + +> Think of it like the machine already ships with its handbook inside. + +In Clawdie terms, that handbook is the **committed built-in knowledge +artifact** imported into `system_skills`. + +This plan names the Rust-side consumer for that lane: + +- **crate name:** `colibri-skills` + +It is a **read path first**, not a new generator, not a new database, and not a +memory replacement. + +## Background + +The current split-brain design already exists in `clawdie-ai`: + +- `system_skills` + - built-in knowledge / manuals already included + - sourced from `bootstrap/skills-memory/artifact.sql` +- `system_brain` + - dynamic user/agent memory +- `system_ops` + - runtime and operational state + +Colibri should reflect that boundary explicitly instead of flattening all +knowledge into one vague "brain." + +## What `colibri-skills` should own + +`colibri-skills` should own the Rust-side access layer for **built-in +knowledge only**. + +Phase-1 responsibilities: + +- connect to the `system_skills` database +- report artifact/import status +- expose stable typed results for built-in knowledge lookup +- support text search over committed handbook content +- return structured summaries that other Colibri crates can consume + +Good callers later: + +- `colibri-daemon` +- `colibri-client` +- `colibri-glasspane-tui` + +## What `colibri-skills` must not own + +It should **not** own: + +- user memory retrieval from `system_brain` +- task/session/runtime state from `system_ops` +- artifact generation or embedding refresh +- OpenRouter or embedding-provider budget logic +- ISO build-time content packing + +Those already belong elsewhere. + +## Why a separate crate + +This wants its own crate because it is a separate architectural lane: + +- distinct data source +- distinct lifecycle +- distinct operator story +- distinct proof gates + +It is not just a helper module inside `colibri-daemon`. + +That keeps the split-brain boundary visible in code: + +- `colibri-runtime` = host/runtime facts +- `colibri-skills` = built-in handbook facts +- future memory lane = user/agent memory, if needed later + +## Phase 1 — read-only consumer + +The first implementation should stay intentionally small. + +Deliverables: + +1. New crate scaffold: + - `crates/colibri-skills` +2. DB-facing types for: + - artifact metadata + - documents + - chunks + - text search results +3. Read-only API for: + - artifact/import status + - list current artifact version + - search built-in knowledge by text +4. Unit tests with fixture rows or golden snapshots + +Phase 1 goal: + +> prove Colibri can read the "manuals already included" lane cleanly, without +> touching memory or generator code. + +## Phase 2 — daemon integration + +After Phase 1 is proven, wire it into Colibri surfaces: + +- `colibri-daemon` + - expose a query path for built-in handbook lookups +- `colibri-client` + - typed client method +- `colibri-glasspane-tui` + - optional "manuals included" / artifact-status pane + +This should still remain read-only. + +## Phase 3 — optional deeper work + +Only after the read path is stable should we consider: + +- vector similarity for built-in knowledge +- richer ranking/grounding +- parity checks against the TypeScript retrieval layer +- eventual Rust ownership of artifact generation + +That is explicitly **not** phase 1. + +## Contracts and proof + +The proof for `colibri-skills` should be simple: + +1. On Linux and FreeBSD, Colibri can connect to `system_skills`. +2. It can report whether the committed artifact is imported. +3. It can query known built-in handbook content by text. +4. Results are typed and stable enough for daemon/client use. + +This is narrower than the daemon proof gates and should stay that way. + +## Naming + +Why `colibri-skills`: + +- it matches the existing `system_skills` boundary +- it stays concrete +- it maps to the "manuals already included" story without pretending it owns + all knowledge + +Rejected names for now: + +- `colibri-brain` + - too vague; collides with user memory +- `colibri-knowledge` + - broader than the actual lane +- `colibri-manuals` + - good product language, but weaker alignment with existing technical names + +## Non-goals + +- no new repo +- no crate inside `clawdie-iso` +- no merge of `system_skills` with `system_brain` +- no rewrite of `bootstrap/skills-memory/artifact.sql` generation yet +- no embedding refresh port to Rust yet + +## Related sources + +- `clawdie-ai/docs/internal/SKILLS-ARTIFACT-V1-PLAN.md` +- `clawdie-ai/html/docs-clawdie-si/docs/split-brain.html` +- `clawdie-ai/setup/skills-memory.ts` +- `clawdie-ai/src/split-brain-status.ts`