vfkb — ViloForge KnowledgeBase

vfkb-claude-plugin

The Claude Code plugin for vfkb (ViloForge KnowledgeBase) — the primary distribution path for vfkb's Claude Code harness face, per ADR-0045 (accepts RFC-021 in vilosource/vfkb).

Why this is a separate repo

vfkb's own dev repo has a src/, test/, scenarios/, and its own internal .vfkb/ design brain — none of which should ship to a plugin consumer. RFC-021's Phase 0 research found that a same-repo, subdirectory-scoped plugin source is not sufficient to prevent that: a real GitHub-sourced claude plugin marketplace add performs a full, unscoped git clone before any plugin-level scoping applies. This repo exists to make that structurally impossible rather than dependent on every consumer remembering a --sparse flag — it contains only what the plugin needs, deliberately kept separate from vfkb's dev repo.

Install

See SETUP_GUIDE.md for a new project, or MIGRATION_GUIDE.md if the project already uses the old vfkb init mechanism.

[!IMPORTANT] Delivery is unproven: this plugin's install and upgrade path has never been verified end-to-end by a sandboxed proof. Per-capability L4s load the plugin from a source tree and therefore prove the capability, not its delivery.

Delivery and upgrade are capabilities in their own right, distinct from the capabilities they carry. Releases may ship with this gap open (ADR-0051, the operator's Reading B ruling) — but the gap must be named, and this disclosure is enforced by scenarios/release-gate.mjs in CI rather than left to prose. It is removed automatically, and only, when scenarios/records/install-path.json lands DEMONSTRATED.

Machine-readable status: DELIVERY-STATUS.json.

Status

Phase 1 (ADR-0045) is built and verified: the plugin manifest, a human-facing skill, hooks, and a bundled MCP server declaration, all resolving vendored copies of vfkb's engine bundles. Verified via a contrast-based, multi-trial scenario (scenarios/plugin-parity.md) and dogfooded read-only against a real consumer (okf-skill) — see that scenario file and ADR-0045 for the full record. Being dogfooded internally next, starting with vilosource/vfkb itself.

v0.4.0 adds session-start continuity end-to-end (vfkb ADR-0049): the vendored engine pins the newest handoff/next-tagged entry (## Last handoff) at the top of the injected session-start context — deterministic, no model — and ships /vfkb:brief, an opt-in enriched briefing (handoff → git delta → GitHub queue → discrepancies) that runs entirely on a Haiku-pinned agent (agents/briefer.md) so invoking it stays cheap on any billing model. Both arms verified live via --plugin-dir sandboxes: wired brief named the seeded next-step exactly; a handoff-less contrast reported UNKNOWN rather than inventing one.

Relationship to vfkb

This repo tracks its own development using vfkb (dogfooding, same pattern as okf-skill) — see AGENTS.md for how work here is recorded. The actual vfkb engine this plugin will bundle lives in vilosource/vfkb; this repo only ever vendors its built, harness-agnostic bundles (dist/bundles/vfkb.mjs, vfkb-mcp.mjs) — never its source.