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

fix(skills): correct source-of-truth — colibri, not clawdie-ai #226

Merged
clawdie merged 1 commit from fix/skills-canonical-home into main 2026-06-26 22:09:33 +02:00
Conversation 0 Commits 1 Files changed 11 +55 -284
11 changed files with 55 additions and 284 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
crates/colibri-skills/Cargo.toml
View file

@ -2,7 +2,7 @@
name = "colibri-skills"
version.workspace = true
edition = "2021"
description = "Colibri skills read consumer — indexes Clawdie-AI skill artifacts into SQLite"
description = "Colibri skills read consumer — indexes skill artifacts from .agent/skills/ into SQLite"
license = "MIT"
[dependencies]

22
crates/colibri-skills/src/lib.rs
View file

@ -1,13 +1,15 @@
//! Colibri Skills — read-only consumer for Clawdie-AI skill artifacts.
//! Colibri Skills — read-only consumer for skill artifacts.
//!
//! This crate indexes committed, reviewed skill artifacts from the Clawdie-AI
//! repository into SQLite. It does NOT author, edit, or store skill content —
//! that responsibility lives in Clawdie-AI.
//! This crate indexes committed, reviewed skill artifacts from this repo's
//! `.agent/skills/` directory into SQLite. It does NOT author, edit, or store
//! skill content — skills are authored and reviewed here, in Colibri's
//! `.agent/skills/` (the canonical home since the clawdie-ai retirement,
//! PR #146).
//!
//! ```text
//! Clawdie-AI repo (source of truth)
//! docs/astro-howto/
//! docs/forgejo-admin/
//! colibri/.agent/skills/ (source of truth)
//! astro-wiki-deploy/SKILL.md
//! git-*/SKILL.md
//! ...
//!
//! colibri-skills (read-only consumer)
@ -21,12 +23,12 @@ use serde::{Deserialize, Serialize};
// ── Core types ────────────────────────────────────────────────────────────
/// A read-only skill artifact indexed from Clawdie-AI.
/// A read-only skill artifact indexed from Colibri's `.agent/skills/`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Skill {
pub skill_id: String,
pub display_name: String,
/// Relative path within the Clawdie-AI repo (e.g. "docs/astro-howto").
/// Relative path within the Colibri repo (e.g. ".agent/skills/astro-howto").
pub source_path: String,
pub manifest: SkillManifest,
pub artifacts: Vec<SkillArtifact>,
@ -173,7 +175,7 @@ pub enum SkillStatus {
// ── Import summary ────────────────────────────────────────────────────────
/// Returned after indexing a Clawdie-AI checkout.
/// Returned after indexing the `.agent/skills/` checkout.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ImportSummary {
pub skills_found: usize,

232
docs/COLIBRI-SKILLS.md
View file

@ -1,232 +0,0 @@
# Colibri Skills Plan
**Status:** Phase 1 scaffolded — read-only split-brain consumer
**Crate:** `crates/colibri-skills`
## Purpose
`colibri-skills` is Colibri's read-only runtime consumer for reviewed skill
artifacts authored in the Clawdie-AI repo. It does not author, edit, or store
canonical skills. Clawdie-AI remains the source of truth; Colibri indexes and
serves typed/runtime views.
```text
Clawdie-AI repo (source of truth)
docs/astro-howto/
docs/forgejo-admin/
docs/vaultwarden-onboarding/
...
Colibri colibri-skills crate (read-only consumer)
reads committed skill artifacts
validates checksums
indexes Markdown/transcript chunks
exposes Skill, SkillArtifact, SkillChunk structs
serves CLI/TUI/search later
```
This keeps the split-brain model explicit:
- `system_skills`: committed built-in knowledge / manuals / reviewed skillpacks
- `system_brain`: user and agent memory
- `system_ops`: live runtime, task, service, and daemon state
## Seed artifact: Astro how-to
The first concrete skillpack is `docs/astro-howto/` in Clawdie-AI. It is useful
because it is not just prose; it includes transcript, generated how-to docs,
commands, screenshots, contact sheet, manifest, checksums, and scripts.
```json
{
"skill_id": "astro-howto",
"source": "local video-derived training artifact",
"inputs": [
"transcript_local.txt",
"screenshots/",
"contact-sheet/contact_sheet.jpg"
],
"outputs": [
"docs/HOWTO.md",
"docs/COMMANDS.md",
"docs/SCREENSHOTS.md",
"docs/SUMMARY.md"
],
"verification": "can user create and run an Astro project?",
"media": "screenshots/*.jpg (paths + hashes, not blobs)",
"manifest": "run_manifest.json",
"checksums": "artifacts.sha256"
}
```
Pipeline shape:
```text
video → local transcript → topic extraction → how-to/runbook
→ screenshots/contact sheet → commands → verification test
→ manifest + checksums → reviewed skill artifact → Colibri read-only index
```
## Ownership
| Layer | Role | Writes | Reads |
| ---------------- | ----------------- | ------------------------------------------------------------------------------ | ---------------------------------------------- |
| Clawdie-AI | Source of truth | Skill artifacts via PR | N/A |
| `colibri-skills` | Runtime consumer | Writes only to the runtime store; source repo remains read-only for the skills | Indexed skill structs from committed artifacts |
| Agents | Authors/reviewers | Candidate skill artifact PRs | Skill content for task routing |
| `system_brain` | Agent/user memory | Personal/user/agent context | Not canonical skill docs |
| `system_ops` | Runtime state | Live task/service state | Not skills |
## What `colibri-skills` does
- Read skill manifests from a configured Clawdie-AI checkout path
- Parse `run_manifest.json`
- Validate checksums against `artifacts.sha256`
- Classify artifacts as document, image, script, transcript, manifest, checksum,
report, contact sheet, or other
- Index Markdown/transcript chunks for search
- Expose stable typed structs for daemon/client/TUI callers
- Persist runtime index metadata in SQLite
## What `colibri-skills` does not do
- Author, edit, or create skills
- Store image blobs in SQLite; store paths and hashes only
- Replace `system_brain`
- Replace `system_ops`
- Own provider/API budget logic
- Require nonportable local source media paths at runtime
## Phase 1 delivered
The scaffold crate now provides:
- `Skill`
- `SkillManifest`
- `SkillArtifact`
- `SkillChunk`
- `ArtifactType`
- `SkillStatus`
- `ImportSummary`
- `SearchResult`
- unit tests for artifact classification and status/summary behavior
Phase 1 is intentionally scaffold-only: compile and type proof, no runtime
import behavior yet.
## SQLite schema target
```sql
CREATE TABLE system_skills (
skill_id TEXT PRIMARY KEY,
display_name TEXT NOT NULL,
source_path TEXT NOT NULL, -- relative within Clawdie-AI repo
manifest_hash TEXT, -- sha256 of run_manifest.json
created_at TEXT NOT NULL, -- ISO 8601
updated_at TEXT NOT NULL,
verification TEXT, -- natural-language verification test
status TEXT NOT NULL DEFAULT 'active' -- active, archived, superseded
);
CREATE TABLE system_skill_artifacts (
artifact_id INTEGER PRIMARY KEY AUTOINCREMENT,
skill_id TEXT NOT NULL REFERENCES system_skills(skill_id),
artifact_type TEXT NOT NULL,
relative_path TEXT NOT NULL, -- within the skill directory
file_name TEXT NOT NULL,
mime_type TEXT,
size_bytes INTEGER,
sha256_hash TEXT NOT NULL,
UNIQUE(skill_id, relative_path)
);
CREATE TABLE system_skill_chunks (
chunk_id INTEGER PRIMARY KEY AUTOINCREMENT,
skill_id TEXT NOT NULL REFERENCES system_skills(skill_id),
artifact_id INTEGER NOT NULL REFERENCES system_skill_artifacts(artifact_id),
chunk_type TEXT NOT NULL,
heading TEXT,
content TEXT NOT NULL,
line_start INTEGER,
line_end INTEGER,
tokens_estimate INTEGER
);
CREATE INDEX idx_skills_status ON system_skills(status);
CREATE INDEX idx_artifacts_skill ON system_skill_artifacts(skill_id);
CREATE INDEX idx_artifacts_type ON system_skill_artifacts(artifact_type);
CREATE INDEX idx_chunks_skill ON system_skill_chunks(skill_id);
CREATE INDEX idx_chunks_type ON system_skill_chunks(chunk_type);
CREATE VIRTUAL TABLE IF NOT EXISTS skill_fts USING fts5(
content,
heading,
skill_id,
chunk_type,
content=system_skill_chunks,
content_rowid=chunk_id
);
```
## Import flow target
1. Read Clawdie-AI checkout path from config/env.
2. Scan for directories containing `run_manifest.json`.
3. Parse manifest and derive skill metadata.
4. Read artifacts, compute SHA-256, and verify `artifacts.sha256` when present.
5. Chunk Markdown by heading and transcripts by timestamp/segment.
6. Upsert SQLite rows idempotently.
7. Return `ImportSummary` with skills found/indexed/skipped, artifacts, chunks,
checksum failures, and errors.
## CLI surface target
```sh
colibri list-skills
colibri show-skill <id>
colibri search-skills <query>
colibri index-skills
colibri verify-skill <id>
```
## Portability rules
- Store image paths and hashes, not blobs.
- Treat local provenance paths like `/home/samob/Videos/...` as metadata only.
- Verify checksums against committed artifacts, not local source paths.
- Store paths relative to the Clawdie-AI repo.
Normal tests run with only local SQLite and committed test fixtures; keep
PostgreSQL, remote Forgejo, and local media as optional integration
dependencies.
## Future skillpacks
```text
astro-howto
forgejo-admin
vaultwarden-onboarding
freebsd-update-reboot
colibri-iso-build
zed-on-freebsd
pi-headless-login
```
## Implementation phases
| Phase | What | Depends on |
| ----- | ---------------------------------------------------------- | ----------- |
| 1 | Scaffold crate + structs + schema plan | Nothing |
| 2 | Manifest parser (`run_manifest.json` → `SkillManifest`) | Phase 1 |
| 3 | Checksum validator (`artifacts.sha256` → verify) | Phase 2 |
| 4 | Markdown/transcript chunker | Phase 1 |
| 5 | SQLite storage + FTS5 search | Phases 3, 4 |
| 6 | CLI commands (`list`, `show`, `search`, `index`, `verify`) | Phase 5 |
| 7 | Daemon/client/TUI integration | Phase 6 |
## Related sources
- `clawdie-ai/docs/astro-howto/`
- `clawdie-ai/docs/VAULTWARDEN-SETUP.md`
- `clawdie-ai/bootstrap/skills-memory/artifact.sql`
- `clawdie-ai/src/split-brain-status.ts`

1
docs/README.md
View file

@ -8,7 +8,6 @@ A quick-reference guide to every document in this folder.
| [`CLAWDIE-STUDIO.md`](CLAWDIE-STUDIO.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.md`](COLIBRI-SKILLS.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 |
| [`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 |

2
docs/wiki/index.md
View file

@ -65,6 +65,6 @@ warning.
| [tui](./tui.md) | Terminal dashboard client (colibri-tui) vs the colibri-glasspane state machine |
| [terminal](./terminal.md) | Terminal capability decision (Kitty, extended-key reporting, tmux passthrough, SSH terminfo) |
| [runtime-inventory](./runtime-inventory.md) | Host runtime inventory + watchdog status reader; additive, read-only integrations |
| [skills-catalog](./skills-catalog.md) | Read-only runtime consumer for reviewed Clawdie-AI skill artifacts |
| [skills-catalog](./skills-catalog.md) | Read-only runtime consumer for reviewed skill artifacts |
| [vault-provision](./vault-provision.md) | Vaultwarden-driven env-file provisioning into jails after agent spawn |
| [deployment](./deployment.md) | Host installer (clawdie): ZFS layout, rc.d/systemd service, dry-run safety |

5
docs/wiki/layered-soul.md
View file

@ -23,7 +23,7 @@ table as `clawdie-iso/scripts/import-clawdie-skills.sh`; idempotent, safe to re-
The the Colibri adapter in layered-soul names a "Layered Memory Fabric" with
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.md`), so the importer intentionally does not target it.
([skills-catalog](./skills-catalog.md)), so the importer intentionally does not target it.
| Layered Soul source | Target (planned) | Status |
| ------------------------------- | ---------------- | ---------------------------------------------------------- |
@ -39,7 +39,8 @@ then re-import — runtime copies are ephemeral consumers.
## Closing the gap (future work)
1. Implement `system_brain` per `COLIBRI-SKILLS.md`, then extend the importer
1. Implement `system_brain` per the planned schema (see
[skills-catalog](./skills-catalog.md)), then extend the importer
to load curated memories.
2. Migrate the flat `skills` table to the planned `system_skills` schema.
3. Define and import `system_ops` task/job manifests.

42
docs/wiki/skills-catalog.md
View file

@ -2,46 +2,44 @@
← [index](./index.md)
`colibri-skills` is Colibri's read-only runtime consumer for Clawdie-AI skill
artifacts. Clawdie-AI authors and reviews the skillpacks; Colibri indexes
them, validates checksums, chunks searchable text, and exposes typed structs to
the daemon, CLI, and TUI. This crate does not author skills.
`colibri-skills` is Colibri's read-only runtime consumer for skill
artifacts. Skills are authored and reviewed in this repo's `.agent/skills/`
directory (the canonical home since the clawdie-ai retirement, PR #146);
Colibri indexes them, validates checksums, chunks searchable text, and exposes
typed structs to the daemon, CLI, and TUI. This crate does not author skills.
→ `crates/colibri-skills/src/lib.rs`
→ `docs/COLIBRI-SKILLS.md`
## Decisions
### Source of truth stays in Clawdie-AI
### Source of truth stays in Colibri
Skill artifacts live in the `clawdie-ai` repository, not in `colibri`. They are
committed reviewed directories containing prose, screenshots, transcripts,
scripts, a manifest, and a checksum file. `colibri-skills` imports these
artifacts into Colibri's SQLite store at runtime.
Skill artifacts live in this repository's `.agent/skills/`, not in a separate
repo. They are committed reviewed directories containing prose, screenshots,
transcripts, scripts, a manifest, and a checksum file. `colibri-skills` imports
these artifacts into Colibri's SQLite store at runtime.
This split preserves review discipline: a skill changes through a PR in its
home repo, then Colibri re-indexes the checkout.
This preserves review discipline: a skill changes through a PR in its home
repo, then Colibri re-indexes the checkout. (Skills were migrated here from the
now-retiring clawdie-ai repo in PR #146.)
### Read-only, not authoring
The crate deliberately lacks "create skill" or "edit skill" operations. Those
belong in Clawdie-AI where human review and media pipelines run. Putting
belong in `.agent/skills/` where human review and media pipelines run. Putting
authoring here would duplicate state and split review authority.
The import path is target for Phase 1: scan the configured Clawdie-AI checkout,
The import path is target for Phase 1: scan the `.agent/skills/` checkout,
parse manifests, verify checksums, and upsert into SQLite. The type scaffold
exists today; the importer, chunker, and FTS5 index are planned.
→ `docs/COLIBRI-SKILLS.md` (Phases 1-7)
### Manifest-driven identity
Each skill directory contains a run manifest file. From it the importer derives:
- `skill_id`
- `display_name`
- `source_path` within the Clawdie-AI checkout
- `source_path` within the Colibri repo
- pipeline stages and models used
- source media metadata
@ -63,7 +61,7 @@ artifact, but the manifest is the canonical identity document.
- anything else → Other
This heuristic keeps classification local and fast. Misclassified files can be
fixed by renaming within Clawdie-AI.
fixed by renaming within `.agent/skills/`.
→ `crates/colibri-skills/src/lib.rs` (`ArtifactType::from_path`)
@ -108,12 +106,12 @@ pgvector; until then, SQLite keeps the control-plane self-contained.
→ [store-schema](./store-schema.md)
→ `docs/COLIBRI-SKILLS.md` (SQLite schema target)
→ [store-schema](./store-schema.md)
### Status is a lifecycle marker, not a state machine
`SkillStatus` is `active`, `archived`, or `superseded`. There is no pending
review state because review happens in Clawdie-AI before import. Colibri simply
review state because review happens in `.agent/skills/` before import. Colibri simply
stops returning archived skills in default searches but keeps them in the store
for audit and explicit lookups.
@ -134,7 +132,7 @@ The CLI surface is planned as:
- `colibri verify-skill <id>`
`index-skills` refreshes the catalog from disk. The remaining commands query the
runtime store. None mutate the Clawdie-AI checkout.
runtime store. None mutate the `.agent/skills/` checkout.
→ [operator-cli](./operator-cli.md)

2
docs/wiki/sl/index.md
View file

@ -71,6 +71,6 @@ clippy.
| [tui](./tui.md) | Odjemalec terminalske nadzorne plošče (colibri-tui) proti avtomatu stanj colibri-glasspane |
| [terminal](./terminal.md) | Odločitev o terminalski zmožnosti (Kitty, razširjeno poročanje tipk, prehod tmux, SSH terminfo) |
| [runtime-inventory](./runtime-inventory.md) | Popis izvajalnega okolja gostitelja + bralnik statusa čuvaja; aditivne, bralne integracije |
| [skills-catalog](./skills-catalog.md) | Bralni izvajalni porabnik za pregledane artefakte veščin Clawdie-AI |
| [skills-catalog](./skills-catalog.md) | Bralni izvajalni porabnik za pregledane artefakte veščin |
| [vault-provision](./vault-provision.md) | Oskrba datotek env, gnana z Vaultwarden, v ječe po zagonu agenta |
| [deployment](./deployment.md) | Nameščevalnik gostitelja (clawdie): postavitev ZFS, storitev rc.d/systemd, varnost suhega teka |

7
docs/wiki/sl/layered-soul.md
View file

@ -27,8 +27,8 @@ idempotentno, varno za ponovni zagon.
Prilagoditveni vmesnik Colibri v layered-soul poimenuje "Plastovito
pomnilniško tkanino" s tremi shrambami — `system_skills`, `system_brain`,
`system_ops`. Na dan 2026-06-13 obstaja samo ena ploščata tabela `skills`;
ostalo je **samo načrt** (`docs/COLIBRI-SKILLS.md`), zato uvoznik
namenoma ne cilja nanje.
ostalo je **samo načrt**
([katalog-veščin](./skills-catalog.md)), zato uvoznik namenoma ne cilja nanje.
| Vir v layered-soul | Cilj (načrtovan) | Stanje |
| ---------------------------------- | ---------------- | ----------------------------------------------------------- |
@ -44,7 +44,8 @@ nato ponovno uvozite — izvajalne kopije so prehodni porabniki.
## Zapiranje vrzeli (prihodnje delo)
1. Implementiraj `system_brain` po `COLIBRI-SKILLS.md`, nato razširi
1. Implementiraj `system_brain` po načrtovani shemi (glej
[katalog-veščin](./skills-catalog.md)), nato razširi
uvoznika, da naloži urejene spomine.
2. Preseli ploščato tabelo `skills` v načrtovano shemo `system_skills`.
3. Definiraj in uvozi manifeste opravil `system_ops`.

20
docs/wiki/sl/skills-catalog.md
View file

@ -1,24 +1,26 @@
---
title: Katalog veščin
description: "Bralni izvajalni porabnik za pregledane artefakte veščin Clawdie-AI — uvozi SKILL.md v Colibrijevo tabelo skills."
description: "Bralni izvajalni porabnik za pregledane artefakte veščin — uvozi SKILL.md v Colibrijevo tabelo skills."
---
← [kazalo](./index.md)
Katalog veščin je Colibrijev bralni izvajalni porabnik za veščine,
pregledane v repozitoriju `clawdie-ai`. Veščine se uvozijo v tabelo
`skills` v shrambi SQLite, kjer jih agenti poizvedujejo med izvajanjem.
pregledane v tem repozitoriju (`.agent/skills/`). Veščine se uvozijo v
tabelo `skills` v shrambi SQLite, kjer jih agenti poizvedujejo med
izvajanjem.
→ `scripts/import-clawdie-skills.sh`
→ `.agent/skills/*/SKILL.md`
## Odločitve
### Bralni porabnik, ne vir resnice
Colibri bere veščine iz repozitorija `clawdie-ai` — ta je vir. Uvozna
skripta je idempotentna (`INSERT OR IGNORE`), zato je varno večkrat
zagnati. Spremembe veščin se zgodijo v izvornem repozitoriju, nato se
ponovno uvozijo.
Colibri bere veščine iz lastnega imenika `.agent/skills/` — ta je vir.
Uvozna skripta je idempotentna (`INSERT OR IGNORE`), zato je varno večkrat
zagnati. Spremembe veščin se zgodijo v tem repozitoriju, nato se
ponovno uvozijo. (Veščine so bile sem preseljene iz umikajočega se
repozitorija clawdie-ai v PR #146.)
→ [layered-soul](./layered-soul.md) (enaka smer)
@ -37,7 +39,7 @@ Veščine se uvozijo ob zagonu procesa v ozadju, ne med izvajanjem. Če operater
veščino, ponovno zažene procesa v ozadju (ali ročno zažene uvozno skripto). Nobena pot
izvajalne kode ne piše v tabelo `skills`.
→ `scripts/import-clawdie-skills.sh`
→ `crates/colibri-skills/src/lib.rs`
## Glej tudi

4
scripts/import-layered-soul.sh
View file

@ -8,7 +8,7 @@
# Scope note (see docs/INTEGRATION-LAYERED-SOUL.md): only skills are imported.
# Curated memory (`memories/curated/**/*.md`) is reported but NOT imported yet —
# Colibri has no `system_brain` store; `system_brain`/`system_ops` and the
# "Layered Memory Fabric" are planned (docs/COLIBRI-SKILLS-PLAN.md), not built.
# "Layered Memory Fabric" are planned (see docs/wiki/skills-catalog.md), not built.
#
# Usage:
# scripts/import-layered-soul.sh <layered-soul-dir> <colibri-sqlite-db>
@ -67,6 +67,6 @@ find "$SOUL/skills" -type f -name 'SKILL.md' 2>/dev/null | sort | {
mem_count=$(find "$SOUL/memories/curated" -type f -name '*.md' ! -iname 'README.md' 2>/dev/null | wc -l | tr -d ' ')
if [ "${mem_count:-0}" -gt 0 ]; then
echo " NOTE: $mem_count curated memory file(s) found — NOT imported."
echo " Colibri has no system_brain store yet (planned: docs/COLIBRI-SKILLS-PLAN.md);"
echo " Colibri has no system_brain store yet (planned: see docs/wiki/skills-catalog.md);"
echo " see docs/INTEGRATION-LAYERED-SOUL.md."
fi