Document planned colibri-skills split-brain lane (Sam & Codex)
This commit is contained in:
parent
dd55533b5d
commit
c2655d1d41
3 changed files with 204 additions and 0 deletions
18
AGENTS.md
18
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
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
181
docs/COLIBRI-SKILLS-PLAN.md
Normal file
181
docs/COLIBRI-SKILLS-PLAN.md
Normal file
|
|
@ -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`
|
||||
Loading…
Add table
Reference in a new issue