juliusbrussee__cavekit/CHANGELOG.md

CHANGELOG

v4.1.0 — the full loop

Additive. Backward compatible with v4.0.0 — the three-command core is unchanged; §R is optional; existing SPEC.md files still parse. Every change below traces to a documented pain point or a research finding, not a hunch.

added — four reach-for verbs

The core loop stays spec → build → check. Four new verbs join it, each opt-in and right-sized — you reach for them only when the change earns it:

• /ck:grill — calibrated interrogation of a fuzzy idea into a sharp §G/§C, one question at a time, before a spec exists.
• /ck:research — external knowledge into the new §R log; every finding cites a source, unverified ones flagged, never written as fact.
• /ck:review — adversarial senior review of the spec before build: refutes rather than rubber-stamps, hardens §V, ends in a go/no-go gate.
• /ck:deepen — spare-budget design pass. Picks the one shallowest module, proposes a deeper shape, holds behavior constant (tests green before and after).

added — format

• §R RESEARCH — optional pipe-table log of external knowledge (id|topic|finding|src).
• Sectioned ownership — each verb writes only the sections it owns; no verb rewrites a foreign section. spec remains the sole general mutator.
• Right-size rule — ceremony scales to blast radius, never to ego.

changed

• build now names the exact test that proves each §V it touches (a verification contract) instead of "add tests" — "do TDD" alone backfires.
• build reads §R so it grounds in researched facts, not re-derivation.
• check reframed as the drift detector: run after each build, before each ship.
• skill descriptions kept ultra-tight — nine descriptions cost ~1.1k context, 16× lighter than spec-kit's 18.6k.

why — pain points → changes (sourced)

pain point (source)	change
Token / context tax — spec-kit loads ~18.6k tokens every session (spec-kit #1401); BMAD burns 80–100k/step (#1188)	caveman descriptions keep cavekit's whole nine-skill set at ~1.1k context — 16× lighter
Specs drift silently with no detector (OpenSpec #1212; spec-kit #1686)	check reframed as the drift detector, run every build
Ceremony overkill — 10–15× overhead, "sledgehammer for a nut" (BMAD #2003; HN 45610996)	right-size rule; core stays 3 commands; verbs are opt-in
Agents ignore the spec / mark done without doing (spec-kit #230; BMAD #446)	build verification contract names which test proves each §V
"Process without library context = organized hallucinations" (Tessl)	/research + durable §R external-knowledge log
No tool adversarially reviews the plan before build (competitor scan)	/review — separate skeptic anchored to an external oracle
Tools overwrite/delete spec files (Kiro #5239; Conductor)	sectioned ownership — no verb rewrites a section it does not own

why — research backing

• Spec as durable external memory across context resets — Anthropic, Effective Context Engineering (2025); the core justification for SDD.
• Plan in a separate phase — ADaPT (NAACL 2024).
• Verification contract names which tests, not "do TDD" — TDAD (2026).
• Critique must be external + adversarial, not introspective — LLMs cannot self-correct alone (Huang et al., ICLR 2024); separate-critic debate works (Du et al., ICML 2024).
• Gate effort by difficulty — Self-Critique Paradox (Snorkel, 2025); right-size follows directly.
• Deep modules — Ousterhout, A Philosophy of Software Design (/deepen).

---

v4.0.0 — the rewrite

Full rewrite. Not backward compatible with v3.x. Different shape, same name.

philosophy

Kept only what earned its tokens:

• SPEC.md — durable, addressable, caveman-encoded
• three commands — /ck:spec, /ck:build, /ck:check
• two skills — caveman encoding, backprop protocol

added

• single SPEC.md format with six addressable sections (§G §C §I §V §T §B)
• pipe-table encoding for §T (tasks) and §B (bugs)
• caveman symbol set (→ ∴ ∀ ∃ ! ? ⊥ ≠ ∈ ∉ ≤ ≥ & |) as default for spec writes
• bug → §B → §V backprop reflex wired into /ck:build failure path
• /ck:spec from-code — distill spec from existing codebase
• /ck:check — read-only drift report (replaces five v3 review flavors)
• npx skills add JuliusBrussee/cavekit one-line install path (commands + skills)

removed (relative to v3.1.0)

• 13 of 16 commands (sketch/map/make/ship/review/revise/status/init/config/resume/help/design/research/team/make-parallel)
• all 12 named sub-agents
• 19 of 21 skills
• Go binary and source (cmd/, internal/, bin/, cavekit executable)
• shell hooks (hooks/, scripts/cavekit-launch-session.sh, stop-hook state machine)
• TS tooling (scripts/cavekit-picker.ts, scripts/cavekit-router.cjs)
• Codex peer-review bridge (.codex-plugin/)
• context/kits/, context/plans/, context/impl/, context/refs/ directories
• autonomous loop, per-task budgets, model-tier routing
• design-system DESIGN.md workflow
• knowledge-graph graphify-out/ integration
• parallel wave execution and team mode
• install.sh (216 lines → 0)

changed

• caveman was opt-in for inter-agent chatter in v3; default for spec writes in v4
• version: 3.1.0 → 4.0.0 (major rewrite, semver respected)
• README, plugin metadata, marketplace entry

migration

See UPGRADE.md. No automated migrator — the v3 kit shape does not map cleanly to v4's single file. Recommended path: run /ck:spec from-code on your existing v3 project to distill a v4 spec from your built code.

v3 reachability

v3 is frozen at tag v3.1.0. Stays installable and documented. Fixes only for critical bugs; no new features.

---

v3.1.0 and prior

See git log before the v4.0.0 commit, or check out v3.1.0:

git checkout v3.1.0