Michał Kopeć
0c06cb64ab
Commit all in-flight work — ckb-module and ckb-reset skills, the .agents/modules/ scaffold, OPENSPEC docs, decision records D-0001 and D-0002, graph edges and workload summaries — so the reset that follows is fully recoverable. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
78 lines
3.5 KiB
Markdown
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: /wiki/index.md
|
|
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](/wiki/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`.
|