ckb/docs/decisions/0001-opt-in-file-based-kb-modules.md
Michał Kopeć 7863115b74 Template 1.10.0: slim skills, review fixes, docs/, tests, retrieval script
- Skills: descriptions cut to routing-hint length (1925w -> 840w), Trigger
  phrases removed, Purpose collapsed, Edge cases moved to references/.
- Rule B names the decisions-log exception; "Sync the wiki" trigger dropped;
  reserved sections "Four" -> "Three"; directory contract adds ckb.yaml,
  docs/, tests/.
- MANUAL/CHANGELOG/OPENSPEC (EN+PL) moved to docs/; template ADRs D-0001 and
  D-0002 restored from 0c06cb6 into docs/decisions/; referrers repointed.
- ckb-retrieve: rank fusion moved into scripts/retrieve_candidates.py;
  Purpose states the one write it owns (query-gaps).
- tests/: fixture KB, golden JSON, smoke.sh.
- Scaffold: overview.md describes content not schema; graph/index.md names
  base skills only; query-gaps.md loses its self-rotting freshness window.
- README/MANUAL/OPENSPEC/CHANGELOG ghost-writer pass in both languages.
- VERSION 1.9.0 -> 1.10.0.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-24 20:45:09 +02:00

78 lines
3.5 KiB
Markdown

---
type: decision
tldr: Optional KB capabilities ship as file-based modules under `.agents/modules/<name>/`, installed into the KB on request, rather than as native Claude Code plugins.
status: accepted
decided_on: 2026-09-20
decided_by: Michał Kopeć
affects: AGENTS.md, .agents/modules/
confidence: 0.9
quality: 0.8
last_updated: 2026-09-20
freshness_window_days: 365
retention: high
---
# D-0001 — Optional KB capabilities ship as file-based modules, not native plugins
**Status:** Accepted · **Decided:** 2026-09-20 · **Deciders:** Michał Kopeć
## Context
The base KB ships fourteen `ckb-*` skills, all always loaded. Some capabilities
are only useful to *some* knowledge bases — the first concrete case being a KB
that documents software the user is building (see
[[D-0002]] / [D-0002](/docs/decisions/0002-software-module-design.md)). Adding
those skills unconditionally would grow the always-loaded skill-description
budget for every KB, including ones that will never need them.
Three mechanisms were on the table for making a capability opt-in. The KB is
deliberately agent-agnostic: `AGENTS.md` is the source of truth and `CLAUDE.md`
is a symlink to it (git mode `120000`), as is `.claude/skills` → `.agents/skills`.
That symlink arrangement is a confirmed preference, and it means anything written
to `.agents/skills/` is visible to Claude Code for free.
## Decision
Optional capabilities are packaged as **file-based modules** stored in
`.agents/modules/<name>/` and installed into the KB on explicit request. A
module may contribute skills (into `.agents/skills/`), directory scaffold, a
routing block appended to `AGENTS.md`, and `.gitignore` rules. Installation is
recorded in a root manifest listing the installed modules and their config;
uninstalling reverses it.
## Rationale
A module is a property of *the knowledge base*, not of the machine or the agent
reading it. File-based modules travel with a clone, so a cloned KB stays
self-describing, and they work for any agent that reads `AGENTS.md` — not only
Claude Code. Shipping module content outside `.agents/skills/` until install
keeps the always-loaded skill budget flat for KBs that don't opt in.
## Consequences
- A `ckb-module`-style install/uninstall path is needed.
- `ckb-init` should offer modules at bootstrap; `ckb-upgrade` must not delete
module-installed skills it doesn't recognise upstream, and must also upgrade
`.agents/modules/`.
- `ckb-lint` gains validation of the module manifest.
- Module skills are authored so they could *also* be published as a native
Claude Code plugin later without a rewrite — this decision doesn't foreclose
that, it just declines to make it the primary mechanism.
- Because `.claude/skills` is a symlink, an installer writes `.agents/skills/`
only; no duplicate copy to keep in sync.
## Alternatives considered
- **Always-shipped skills that self-gate on a flag** — no install step and
trivially upgradeable, but every skill description stays in context for every
KB regardless of relevance. Rejected: that budget degrades quietly.
- **Native Claude Code plugin** (`.claude-plugin/plugin.json` + marketplace) —
real enable/disable and no file copying, but serves only Claude Code, breaking
the dual-headed `AGENTS.md`/`CLAUDE.md` contract, and installs per-machine
rather than per-KB. Rejected as the primary mechanism, not ruled out as an
additional distribution channel.
## Sources
Chat conversation, 2026-09-20 — design evaluation of a source-code/software KB
mode. See `workload/2026-09-20_summary.md`.