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
Add skills/spec, skills/build, skills/check as SKILL.md files mirroring
the corresponding command prompts. Each has a description frontmatter
that triggers auto-activation when the user asks to write a spec, run
a build, or check drift.
Keeps commands/ intact for the plugin-install slash-command path; the
two are kept in sync at the prose level.
`npx skills add JuliusBrussee/cavekit` now installs all five skills
(spec, build, check, caveman, backprop). The three /ck: slash commands
remain available via plugin marketplace install.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Reword README / LAUNCH-POST to reflect that `npx skills add JuliusBrussee/cavekit`
installs both the three /ck: commands and the two skills together —
it is the primary one-line install path, not a skill-only fallback.
Marketplace and git clone remain as alternatives.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- 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>
Add CHANGELOG.md and UPGRADE.md for the v1→v2 break. Rewrite README
with explicit v1 description and install paths (marketplace tag
v1.3.1-final + git clone), framing v1 as frozen-but-working rather
than deprecated. Link UPGRADE.md for migration guidance and two-way
door reassurance.
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.
Clarify and tighten agent and workflow protocols: make the drafter run inline (do not spawn ck:drafter subagents) and require full-domain decompositions presented in a single message for approval. Add a hard rule to task-builder: never return silently — each dispatch must perform at least one real tool call and emit a TASK RESULT with COMPLETE / PARTIAL / BLOCKED. Introduce silent-return / no-op detection and recovery across make and make-parallel: classify empty bodies / zero tool calls / auto-removed worktrees as no-ops, log dead-ends, retry once inline in the parent session, and mark/block or escalate if the inline retry also fails; add a two-no-op circuit-breaker to fallback to inline processing for the rest of the wave. Update sketch and ship flows to write kits inline, auto-advance on explicit approval, and adjust related guidance in the cavekit-writing skill. These changes reduce subagent/worktree failure modes and make failures observable and recoverable.
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>
Add path-scoped team coordination features and ref-backed ledger plumbing.
- CLI: add `team next` (suggests a non-conflicting frontier task) and `team guard-commit` (invoked by pre-commit). Extend `team claim` with --paths and surface provisional/offline queued claims.
- Pre-commit guard: installable hook that rejects commits touching files claimed by other sessions; supports emergency override via CAVEKIT_TEAM_OVERRIDE (exit code 8). New internal/team/hook.go implements guard and staged-path inspection.
- Ledger/refs: ledger now lives on refs/heads/cavekit/team via a RefClient (Manager.Ref). Manager.Init ensures remote branch (may defer), Sync fetches the ref and opportunistically drains the outbox, Claim/Release/Heartbeat now publish via RefClient and expose provisional commit state and outbox counts. Path overlap detection and AllActiveClaims support added.
- Robustness: Claim retries on CAS loss, with rollback and re-fetch logic; Release and Sync updated to use RefClient. Config loading fills missing heartbeat_publish_every default and tests added (internal/team/config_test.go).
- Git hygiene: .gitignore/.gitattributes patching updated for ref-backed ledger; EnsureGitignoreBlock and EnsureGitattributesBlock adjusted and tests updated.
- Executor: add RunDirStdin and RunDirEnv helpers for deterministic child env/stdin execution.
- Docs/installer: update README, commands docs (team.md, make.md), add implementation tracking (context/impl/impl-team.md), and tweak install wording for Codex/Codex bundle.
These changes enable path-level claim isolation, offline-safe queuing, commit-time enforcement, and safer CAS-backed collaboration without touching the working branch.
Introduce a new team coordination feature: adds a `team` subcommand to the cavekit CLI, the internal team implementation, and documentation/spec kits. Changes include:
- CLI: register `team` in cmd/cavekit/main.go and implement subcommands in cmd/cavekit/team.go (init, join, status, claim, release, sync, internal heartbeat). Supports --json output and deterministic exit codes with exit helpers.
- Internal: new internal/team package (config, identity, lease, ledger, manager, gitpatch, tests) to implement file-based ledger, leases, and claim/release protocol.
- Docs: new / updated docs and kits under commands/ and context/kits/ describing slash-command wrappers (/ck:team), TUI integration, CLI spec, and make-loop dispatch/heartbeat semantics.
- Integration: update commands (make, make-parallel, status) to document and allow invoking cavekit team for task claim/heartbeat/release and add allowed-tools entries. Add commands/team.md wrapper.
- Misc: update scripts/setup-build.sh and site/frontend pieces to reflect team mode; add JSON marshal helpers and argument normalization utilities in CLI.
This commit wires team-mode into the build loop (claim → heartbeat → release), adds the union-merged ledger and lease semantics, and provides machine-readable JSON outputs and docs for TUI and CLI integration.
Adds a preflight step that removes the deprecated
~/.claude/plugins/local/blueprint-marketplace and
~/.claude/plugins/cache/blueprint-local directories left behind by
earlier "bp" installs, so the installer converges on a clean ck-only
plugin layout.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Drops the deprecated "bp" plugin alias from the marketplace manifest,
the plugin list, and the symlink; installs a cleanup step that removes
any stale bp symlink from earlier installs.
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>
Add consistent ecosystem banner near the top and a unified
"Caveman Ecosystem" section near the bottom so visitors of any repo
can discover and reach the others.
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Marketplace metadata referenced 2.2.0 while plugin.json is 3.0.0.
Added /ck:review to the post-install command summary.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Bump plugin to version 3.0 and update plugin/marketplace metadata (description and keywords). Major README rewrite: reorganized into a clear "loop" (sketch → map → make → check), added first-run and brownfield flows, new/renamed commands (e.g. /ck:ship, /ck:review, /ck:revise, /ck:init, /ck:config, /ck:status, /ck:help), expanded CLI and configuration docs, and clarified Codex integration and review modes. Rename/clarify backpropagation → revision flows (commands and docs updated to use /ck:revise --trace), update verifier routing in commands/check.md, and adjust Codex-related command names (/ck:review --codex). Update agent metadata (architect, drafter) to reflect new command names. Update runtime and tooling docs and scripts (install.sh, scripts/cavekit-tools.cjs) and several context/kit implementation files to reflect the Codex review loop, tier gating, and make/mapping command changes. Misc: README copy edits, skills docs updates, and small doc/path adjustments throughout the repository to match the new workflow and naming.
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
Passing nil as context to worktree methods causes SIGKILL on macOS.
Both runStatus() and runKill() were passing nil context to
wtMgr.ProjectRoot(), tmuxMgr.ListSessions(), tmuxMgr.Kill(), and
wtMgr.Remove(). Changed to use context.Background() instead.
runMonitor() already used context.Background() correctly.
- 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>
Simplify Caveman entry in README (remove the skill number and wording) to state it's bundled in Cavekit and enabled by default. Change scripts/codex-design-challenge.sh to query bp_config_caveman_active with 'draft' instead of 'build' so caveman activation reflects the draft phase.
Bundle Caveman as skill #16 with full CaveKit integration:
- Add skills/caveman/SKILL.md with lite/full/ultra intensity levels
- Add caveman_mode (default: on) and caveman_phases (default: build,inspect)
config options to bp-config.sh with validation and caveman-active helper
- Inject CAVEMAN MODE into subagent prompts in build.md so all inter-agent
communication is token-compressed (~75% savings across parallel waves)
- Add caveman-aware loop logging: compressed one-liner entries when active
- Apply caveman-speak to Codex review and design challenge prompt framing
(structured findings tables stay in normal format)
- Update all four phase commands (draft, architect, build, inspect) to
resolve caveman_active from config at startup
- Update task-builder agent to respect CAVEMAN MODE from dispatch prompt
- Update README with skill #16, config docs, and bundled status
https://claude.ai/code/session_018MDR9vb5fsAKp4c2LtxYb5
Replace custom SVG artwork with emoji-based stone icons: update .codex-plugin/icon.svg and .codex-plugin/logo.svg to simple SVGs that render the 🪨 emoji (add role/aria-label and emoji font fallbacks). Also simplify README by inlining the stone emoji instead of referencing the SVG image. This reduces asset complexity and ensures consistent emoji rendering and accessible labels.
- Punchy, direct prose — no filler, no fluff
- Dynamic GitHub badges (stars, last commit, license)
- Before/After comparison table up front
- Problem framed as table for quick scanning
- All technical content preserved: phases, parallel execution,
Codex adversarial review, configuration, commands, methodology
- Skills listed in table format inside collapsible section
- Star history chart and ecosystem links
- Consistent with caveman README style
https://claude.ai/code/session_012D3nKU3keqDLHpk7ustfUc
- 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
Closes the gap where acceptance criteria specified in draft could be lost
during architect and build phases. Adds:
- Coverage Matrix to build-site format: maps every acceptance criterion to
its assigned task(s), making gaps visible before build starts
- Pre-flight coverage check in build: flags unassigned criteria before
executing any tasks
- Post-flight blueprint verification: cross-references completed tasks
against original blueprint criteria after build, adds remediation tasks
for anything missed
- Quick mode coverage gate: lightweight but mandatory criterion check
- Criterion-level validation rules in architect command and agent
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Julius Brussee