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

3.5 KiB

type tldr status decided_on decided_by affects confidence quality last_updated freshness_window_days retention
decision 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. accepted 2026-09-20 Michał Kopeć AGENTS.md, .agents/modules/ 0.9 0.8 2026-09-20 365 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). 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.