Extend cavekit from a 3-command core into the simplest full SDD loop, every
change traced to a documented pain point or research finding. Additive and
backward compatible: the spec → build → check core is unchanged, §R is
optional, existing SPEC.md files still parse.
Four reach-for verbs (skill + thin command, opt-in, right-sized):
- grill calibrated interrogation → sharp §G/§C, one question at a time
- research external knowledge → new compressed §R log, every finding sourced
- review adversarial senior review of the spec before build, go/no-go gate
- deepen spare-budget design pass — make one shallow module deep (Ousterhout)
Format: add §R RESEARCH, sectioned ownership (no verb rewrites a foreign
section — kills the "tool deleted my spec" failure mode), and a right-size rule
(ceremony scales to blast radius, never a typo).
Core sharpened: build now names which test proves each §V (verification
contract) and reads §R; check reframed as the drift detector. Original
spec/build/check commands converted to thin pointers to their skills (single
source of truth). Nine skill descriptions cost ~1.1k context, 16x lighter than
spec-kit's 18.6k.
Grounded in real pain points (spec-kit #230/#1401/#1686, BMAD #1188/#446/#2003,
OpenSpec #1212, Kiro #5239, HN threads) and research (Anthropic context
engineering, ADaPT NAACL'24, Huang ICLR'24, Du ICML'24, TDAD'26). Design was
adversarially reviewed before commit; 2 BLOCK + 2 HARDEN findings fixed. Full
sourced traceability in CHANGELOG.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01J3whGonu8mvZLJC9xx2hn4
- plugin.json 2.0.0 → 4.0.0 (semver-consistent, matches existing tag line)
- README, CHANGELOG, UPGRADE reference v3.1.0 as the frozen v1-generation release
- drop "cavekit v2" dual naming — now just cavekit (version 4.0.0)
- add LAUNCH-POST.md for the launch announcement (move to Discussions post-push)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Migrate project to a compressed 'v2' focused workflow: add FORMAT.md (SPEC.md format + caveman encoding and backprop rules), streamline README to describe the new single-file SPEC and three core commands (/ck:spec, /ck:build, /ck:check), and update plugin metadata (.claude-plugin/plugin.json and marketplace.json) to reflect v2. Remove legacy Codex plugin assets, many agent/command/docs/scripts/internal implementation files and tests that belonged to the previous, larger architecture to concentrate on the minimal v2 surface.
Add an optional trailing `Files` column to build-site task tables declaring
each task's expected file footprint (comma- or semicolon-separated globs).
- Parser: Task gains Files []string; trailing column parsed for tier 0
(cell[5]) and tier N (cell[6]). Empty / "-" treated as unset.
- Scheduler: replaces substring heuristic with real PathsOverlap check when
Files is present; falls back to the old spec-substring hint for legacy
sites. NextSuggestion now returns the task's Files as Paths.
- Claim: if --paths is omitted and the kit declares Files, Claim defaults
to those globs. Removes the "user forgot --paths" failure mode and means
the pre-commit guard gets correct scope without anyone guessing.
- Tests: parser Files parsing (both tiers, both separators, placeholder
dashes); Claim_DefaultsPathsFromSiteFiles asserts the claim event records
the kit's Files in the ledger.
Install: `scripts/cavekit` never dispatched `team` to the Go binary, so
`cavekit team init` failed on every fresh install. Fixed by:
- install.sh builds cmd/cavekit → $INSTALL_DIR/bin/cavekit-bin (warn if
`go` is missing).
- scripts/cavekit delegates team/version/debug/reset/status/monitor to the
Go binary via a delegate_to_bin helper.
Docs: README gets a "Teams" section describing setup, the Files column,
day-to-day commands, and where configuration lives.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Fix two bugs that could break /ck:make under the quality preset:
1. Caveman mode was telling task-builder subagents to apply caveman-speak
to their *reasoning*, which corrupted <tool_use> formatting — subagents
emitted tool calls as body text and terminated with 0 tool_uses.
Scope caveman to final prose output only (status reports, summaries).
Reasoning, tool calls, tool arguments, code, commits, and structured
fields are explicitly excluded. Fixed in make.md, task-builder.md,
check.md, map.md.
2. Parallel ck:task-builder dispatch with isolation: "worktree" can hit
a Claude-Code-harness worktree race, returning "[Tool result missing
due to internal error]" with no agentId. Avoid the race by defaulting
/ck:make to inline sequential execution: no subagent, no worktree, no
merge. The parent session implements tasks directly on the current
branch — the path the user confirmed works.
New command /ck:make-parallel keeps the parallel-subagent path available
as explicit opt-in. It forces TB_ISOLATION=worktree + MAX_PARALLEL=3
(tunable via --concurrency N) for a single run without touching config.
Adds a one-time retry-on-harness-error rule: harness failures re-dispatch
once sequentially, then mark BLOCKED.
Config knob: task_builder_isolation (worktree/inline, default inline).
parallelism defaults lowered: max_agents=1, max_per_repo=1.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Remove numerous deprecated/duplicated command docs and consolidate CLI documentation. Add new commands: ck-review (consolidated branch review), ck-ship, and ck-status; update plugin.json. Revise major command pages (help, init, check, design, map, make, research, config) to clarify "What this does"/"When to use it", introduce init --tools-only capability discovery and summary output, and standardize flags and workflows. Adjust skill docs (peer-review, revision) and drop obsolete skill/command files to streamline review/backprop/quick/inspect flows and unify the end-to-end pipeline documentation.
The runtime from 2.1.0 shipped as a standalone engine; this change wires
it through every existing command so /ck:make drives itself under the
stop-hook once /ck:init has been run. No breaking changes — every command
detects .cavekit/ and falls back to the pre-2.2 path when absent.
Correctness:
- Fix sentinel mismatch: stop-hook, cavekit-tools, docs now match
setup-build.sh's <promise>CAVEKIT COMPLETE</promise> (space, not
underscore). Without this, the loop could never terminate.
- .gitignore: add the transient runtime files (.loop.json, .loop.lock,
.progress.json, tool-cache/, state.md, ledgers, etc.) while leaving
.cavekit/config.json and .cavekit/history/ under version control.
Command wiring:
- /ck:init — calls cavekit-tools init + discover; seeds .cavekit/; appends
runtime entries to .gitignore if missing; prints detected capabilities.
- /ck:config — surfaces new runtime keys (session_budget, task_budget_*,
auto_backprop, tool_cache, parallelism_*, model_routing, graphify) and
accepts get/set directly for any bp-config.sh key.
- /ck:progress — prints `cavekit-tools status` block first when .cavekit/
is present; legacy impl-based rollup follows.
- /ck:sketch — dispatches ck:complexity per approved kit to auto-fill the
complexity: frontmatter; tags novelty-heavy kits for research.
- /ck:map — emits .cavekit/tasks.json and calls init-registry; inserts
ck:researcher dependency tasks for kits tagged needs_research.
- /ck:make — documents runtime mode: setup-loop activates the stop-hook,
the hook routes waves automatically, task-builders mark completions
via cavekit-tools, and the final message emits
<promise>CAVEKIT COMPLETE</promise>. Legacy Ralph-loop path preserved.
- /ck:check — dispatches ck:verifier for goal-backward verification and
falsely_complete detection; routes gaps through /ck:backprop.
- /ck:review-branch — adds a fix-cycle section: blocking findings become
fix tasks on the next loop iteration; max 2 cycles, then
ADVANCE_WITH_FINDINGS.
- /ck:backprop — consumes .cavekit/.auto-backprop-pending.json when
invoked with no args, in addition to --from-flag / --from-finding.
- /ck:revise — preferred path: route each manual fix through /ck:backprop
when .cavekit/ is present (regression test + audit log).
- /ck:research — prefers a single ck:researcher dispatch for narrow
briefs; multi-agent fan-out for broad topics.
Scripts:
- setup-build.sh — calls cavekit-tools init + setup-loop when node is
available, activating the stop-hook mid-/ck:make. Keeps the legacy
.claude/ralph-loop.local.md file for back-compat.
- cavekit-tools.cjs — adds `intensity` subcommand that resolves
lite|full|ultra based on session budget pressure, task depth, and
phase. Consumed by /ck:make and /ck:check.
Go CLI (cmd/cavekit/main.go):
- runStatus prints `cavekit-tools status` block when .cavekit/state.md
exists (alongside the existing worktree rollup).
- runReset additionally clears transient runtime files from .cavekit/
(.loop.json, .loop.lock, .progress.json, .auto-backprop-pending.json,
.debug.log), leaving config.json and history/ untouched.
Tests:
- tests/intensity.test.cjs — six new assertions covering the caveman-
internal decision table (session pressure, task pressure, depth clamps,
phase clamps, explicit override).
- Total: 40/40 passing.
Plugin manifest:
- plugin.json, .claude-plugin/plugin.json, install.sh → 2.2.0.
https://claude.ai/code/session_018edLvsv8JE9947oFiBXyHS
Introduces the machinery that turns /ck:make into a hands-off autonomous
loop without changing the Hunt methodology. Nothing in existing commands,
skills, or agents breaks; the new layer is additive and opt-in.
New runtime (scripts/):
- cavekit-tools.cjs — state machine, lock with heartbeat, token ledger,
task registry, routing, capability discovery, backprop directive,
status-block dashboard. Zero runtime deps.
- cavekit-router.cjs — five-axis task scoring mapped to haiku/sonnet/opus
tiers with role baselines and budget-pressure demotion.
New hook system (hooks/):
- stop-hook.sh — Stop-event driver; reads .cavekit/state, routes the next
prompt, returns {decision:"block",reason:...} to keep the session going
until <promise>CAVEKIT_COMPLETE</promise> is emitted or a budget trips.
- token-monitor.sh — per-task budget (80% warn, 100% halt).
- tool-cache.js / tool-cache-store.js — 120s TTL cache for read-only tools.
- test-output-filter.js — condense test output around failure lines.
- auto-backprop.js — write flag file on test failure; stop-hook prepends
a backpropagation directive on the next iteration.
- progress-tracker.js — zero-stdout snapshot for /ck:watch.
- hooks.json — registers all of the above (Stop + PreToolUse + PostToolUse).
New skills (skills/):
- karpathy-guardrails — four behavioral rules (think-before-code, simplicity,
surgical, goal-driven) enforced by reviewer and task-builder.
- caveman-internal — three intensity modes (lite/full/ultra) for
machine-to-machine artifacts, with budget-pressure auto-selection and a
verbose-regeneration fallback. Separate from the user-facing /caveman skill.
- backpropagation — six-step bug-to-kit trace; auto-triggered by the
auto-backprop hook or manually via /ck:backprop.
- complexity-detection — five-axis scoring rubric; depth mapping
(0-6 quick / 7-13 standard / 14+ thorough).
- autonomous-loop — end-to-end loop reference (state files, sentinels,
lock protocol, debugging).
- capability-discovery — MCP + plugin + CLI detection, writes
.cavekit/capabilities.json.
- graphify-integration — optional knowledge-graph queries; degrades to grep
when graphify-out/graph.json is absent.
New commands (commands/):
- /ck:watch — live dashboard.
- /ck:resume — recover from crash, lock conflict, or interrupt.
- /ck:backprop — manual entry to the backpropagation skill.
- /ck:review-branch — two-pass (kit + code) branch review, optional Codex.
- /ck:setup-tools — run capability discovery and summarize.
New agents (agents/):
- complexity — haiku-only classifier, returns JSON score.
- verifier — goal-backward verification with stub detection.
- researcher — multi-source research brief with citations.
Templates (templates/):
- state.md, config.json, task-status.json, spec-kit.md — seed files that
commands copy into .cavekit/ or context/ on init.
Config (scripts/bp-config.sh):
- Adds session_budget, max_iterations, task_budget_{quick,standard,thorough},
auto_backprop, tool_cache(+_ttl_ms), test_filter, progress_tracker,
parallelism_max_{agents,per_repo}, model_routing, graphify_enabled.
- Extends caveman_phases validator to accept review and verify.
Plugin manifest (.claude-plugin/):
- plugin.json + marketplace.json for the marketplace discovery path.
Existing root plugin.json bumped to 2.1.0; install.sh version strings
bumped to match.
Tests (tests/):
- 34 zero-dep Node.js tests covering frontmatter round-trip, state
merging, lock acquire/heartbeat/steal/release, per-task + session
budget, task registry with dependency ordering, routing sentinels,
router tier bands, preset matrix, and deep-merged config loading.
- Runner: `node tests/run-tests.cjs`.
No changes to existing /ck:sketch, /ck:map, /ck:make, /ck:check, or any
existing skill/agent — this commit strictly adds the runtime layer beneath
them.
https://claude.ai/code/session_018edLvsv8JE9947oFiBXyHS
- Plugin prefix: bp: → ck: (bp: kept as deprecated alias via symlink)
- DABI cycle renamed: sketch (draft), map (architect), make (build), check (inspect)
- Also renamed: scan (gap-analysis), judge (codex-review)
- Old command names preserved as symlinks for backward compatibility
- All commands include deprecation notices pointing to new names
- install.sh registers both ck and bp plugins
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Rename all files/directories: .blueprint -> .cavekit, cmd/blueprint -> cmd/cavekit,
context/blueprints -> context/kits, skills/blueprint-writing -> skills/cavekit-writing,
agents/blueprint-reviewer -> agents/cavekit-reviewer, scripts/blueprint* -> scripts/cavekit*
- Update Go module path: github.com/julb/blueprint-monitor -> github.com/JuliusBrussee/cavekit
- Replace all content references from blueprint/Blueprint to cavekit/Cavekit
- Update plugin.json, install.sh, codex-plugin config, and all documentation
- Add caveman ecosystem link to README
- Binary renamed from blueprint to cavekit
Part of the Caveman ecosystem: https://github.com/JuliusBrussee/cavemanhttps://claude.ai/code/session_012D3nKU3keqDLHpk7ustfUc
Rename terminology across docs to use "revision" and "blueprints" instead of "backpropagation" and "specs". Updates apply to plugin.json (description), references (git-as-memory, multi-repo-strategy, session-feedback-protocol), and skills (convergence-monitoring, impl-tracking, prompt-pipeline, validation-first) to keep naming consistent and clarify the Blueprint framework workflow.
Replace the long 'blueprint' namespace with the shorter 'bp' across docs, command specs, agent descriptions, scripts, and skills. Updated README, command/agent metadata, install/setup scripts, launcher/picker scripts, plugin.json (name -> "bp"), and many SKILL.md cross-references so slash commands (e.g. /blueprint:build) and plugin identifiers consistently use /bp:... and bp@... to avoid mismatches.
Large rework to rename and restructure the project from "SDD" (Spec-Driven Development) to "Blueprint": update README and .gitignore; rename specs → blueprints and frontiers → sites in context; rename CLI commands and slash commands (sdd:* → blueprint:* and sdd CLI → blueprint); rename agent roles and related files (e.g. plan-architect → architect, implementer → builder, adversarial-reviewer → inspector, gap-analyzer → surveyor), remove spec-writer and execute docs, add drafter agent and a new blueprint-build command; update various command docs, templates, and references to map requirements/acceptance criteria to blueprints; adjust scripts and other renamed files accordingly. This commit realigns naming and workflows to the new "Blueprint" terminology and adds the drafter + build flow while pruning legacy spec/execute artifacts.
Julius Brussee