155 lines
6.6 KiB
Markdown
155 lines
6.6 KiB
Markdown
---
|
|
name: ckb-module
|
|
description: Install, list, or uninstall an optional Cascade KB module from .agents/modules/<name>/. Use for "install the <name> module", "what modules are available", "which modules are installed", "uninstall the <name> module", or a request for a capability the base KB lacks, such as handling source code.
|
|
---
|
|
|
|
# Module skill
|
|
|
|
## Purpose
|
|
|
|
Modules are present in the repo but inert, so their skill descriptions cost
|
|
no context in a KB that never needs them. See
|
|
[D-0001](/docs/decisions/0001-opt-in-file-based-kb-modules.md) for why they
|
|
are files in the repo rather than an agent plugin: a module is a property of
|
|
the knowledge base, so it must travel with a clone and work for any agent
|
|
that reads `AGENTS.md`.
|
|
|
|
## The manifest
|
|
|
|
Installed modules are recorded in `ckb.yaml` at the repo root:
|
|
|
|
```yaml
|
|
template: # written by ckb-init, read and updated by ckb-upgrade
|
|
repo: https://git.wierzbowa.cloud/michal/ckb.git
|
|
branch: main # main | test | experimental, or any branch of a fork
|
|
|
|
kb_modules:
|
|
- name: software
|
|
version: 1.0.0
|
|
installed_on: 2026-09-20
|
|
config:
|
|
src_repos: []
|
|
```
|
|
|
|
`ckb.yaml` holds repo-level configuration — what's installed, what it's
|
|
configured with. It is **not** the wiki's content contract: `kb_schema_version`
|
|
stays in `wiki/index.md` where it has always been. Two different things, two
|
|
different homes.
|
|
|
|
The `template:` block records which upstream repo and **branch** this KB takes
|
|
its tooling from. It belongs to `ckb-init` (writes it) and `ckb-upgrade` (reads
|
|
it as the default source, updates it when the user switches channel). This
|
|
skill must **never** drop or rewrite it: a module install that silently reset a
|
|
KB from the `experimental` channel back to `main` would change what its next
|
|
upgrade pulls, which is not a module's business. Read `ckb.yaml`, edit the
|
|
`kb_modules:` list, write it back with everything else intact.
|
|
|
|
If `ckb.yaml` doesn't exist, no modules are installed and no template source is
|
|
recorded; create it on first install, carrying forward any `template:` block
|
|
that a later `ckb-upgrade` may add.
|
|
|
|
## Installing
|
|
|
|
### Step 1 — Resolve and read the module
|
|
|
|
Find `.agents/modules/<name>/module.yaml`. If the name doesn't match, list what's
|
|
actually in `.agents/modules/` rather than guessing at a near-miss.
|
|
|
|
Read the manifest: `skills`, `scaffold`, `agents_fragment`, `gitignore_fragment`,
|
|
`schema_additions`, `depends_on`, `requires_kb_schema`.
|
|
|
|
### Step 2 — Check preconditions, and report them before writing anything
|
|
|
|
- **Already installed?** If `ckb.yaml` lists it, say so and offer to reinstall
|
|
(refresh the files) or stop. Don't silently re-copy.
|
|
- **Schema.** If `requires_kb_schema` is above `wiki/index.md`'s
|
|
`kb_schema_version`, the bump is part of this install (Step 4) — additive only.
|
|
If the module needs a *major* version above the KB's, stop and hand it to
|
|
`ckb-upgrade`.
|
|
- **Dependencies.** Run each `check`. A failing **optional** dependency is a
|
|
warning, not a blocker — report it plainly and continue. A failing required one
|
|
stops the install.
|
|
- **Collisions.** If a skill name in `skills:` already exists in
|
|
`.agents/skills/`, or a scaffold path exists with unrelated content, stop and
|
|
ask. Never overwrite a skill the user may have edited.
|
|
|
|
Report all findings **before** the first write, then proceed (or ask, if anything
|
|
needs a decision). A half-installed module is worse than an uninstalled one.
|
|
|
|
### Step 3 — Copy the payload
|
|
|
|
```bash
|
|
cp -r .agents/modules/<name>/skills/<skill> .agents/skills/<skill>
|
|
```
|
|
|
|
`.claude/skills` is a symlink to `.agents/skills` (git mode `120000`), so the
|
|
skills appear under `.claude/` automatically. **Do not create a second copy
|
|
there** — that symlink is a deliberate choice, and duplicating it creates two
|
|
things to keep in sync.
|
|
|
|
Create each `scaffold` path, copying any `from` template to its `as` destination.
|
|
Never overwrite an existing scaffold file — skip it and note the skip.
|
|
|
|
### Step 4 — Patch the shared files
|
|
|
|
Both patches are wrapped in markers so uninstall is exact:
|
|
|
|
```
|
|
<!-- ckb-module:<name> START -->
|
|
...fragment...
|
|
<!-- ckb-module:<name> END -->
|
|
```
|
|
|
|
- **`AGENTS.md`** — append `agents_fragment` at the end of the file, inside
|
|
markers. `CLAUDE.md` is a symlink to `AGENTS.md`, so it updates for free;
|
|
never write `CLAUDE.md` directly.
|
|
- **`.gitignore`** — append `gitignore_fragment`, inside markers (`#`-commented).
|
|
- **`wiki/index.md`** — bump `kb_schema_version` to `requires_kb_schema` if the
|
|
module's additions raise it. Additive only, per `ckb-upgrade`'s versioning
|
|
policy.
|
|
|
|
### Step 5 — Record, log, report
|
|
|
|
- Add the module to `ckb.yaml` with its version and today's date.
|
|
- Log to `wiki/log.md` per Rule B **only** for the `wiki/index.md` change — the
|
|
rest is template layer, not wiki content.
|
|
- Append to `workload/YYYY-MM-DD_<author>_summary.md` per Rule D.
|
|
- Report: skills now available and what they do, directories created, files
|
|
patched, dependency warnings, schema bump if any. Then the standard reminder —
|
|
on disk, not committed.
|
|
|
|
Offer to record a decision (`ckb-decide`) if installing the module was a real
|
|
choice for this KB rather than following a prior one.
|
|
|
|
## Uninstalling
|
|
|
|
Reverse Step 3 and 4, in this order, and be conservative about data:
|
|
|
|
1. Remove `.agents/skills/<skill>` for each skill the manifest lists — **but
|
|
first diff it against `.agents/modules/<name>/skills/<skill>`.** If the
|
|
installed copy was edited, show the diff and ask before deleting. Offer to
|
|
copy the edits back into the module folder so they survive.
|
|
2. Strip the marked blocks from `AGENTS.md` and `.gitignore`.
|
|
3. Remove the module's entry from `ckb.yaml`.
|
|
|
|
**Never remove scaffold directories or any content under them.** `src/` may hold
|
|
the user's clones, `openspec/` their specs. Say explicitly what was left behind
|
|
and why, so nothing looks like an oversight.
|
|
|
|
**Never remove wiki pages the module's skills created**, and never lower
|
|
`kb_schema_version`. Those pages are knowledge; the module produced them but does
|
|
not own them, and they must stay readable without it. Say which page types
|
|
(`repository`, `component`, `spec`) will now have no skill maintaining them.
|
|
|
|
## Listing
|
|
|
|
On "what modules are available": list `.agents/modules/*/module.yaml` with each
|
|
`title` and `summary`, marking which are installed per `ckb.yaml`. Keep it short
|
|
— name, one line, installed or not.
|
|
|
|
## Edge cases
|
|
|
|
Unusual situations — an empty target, a partial run, a conflicting state,
|
|
a missing dependency — are catalogued in
|
|
[`references/edge-cases.md`](references/edge-cases.md). Read that file when a
|
|
run hits something the steps above don't cover; don't load it otherwise.
|