why agent guess when agent can know

The loop • Install • Your first run • Existing repo • Commands • How it works • Examples

🪨 Caveman Ecosystem  ·  caveman talk less  ·  cavemem remember more  ·  cavekit build better _{(you are here)}

A Cavekit bundle for Claude Code and Codex that turns natural language into specs, specs into parallel build plans, and build plans into working software — with an autonomous loop, validation gates, and optional cross-model review.

You describe what you want. Cavekit writes the contract. Agents build from the contract. Every line of code traces to a requirement. Every requirement has acceptance criteria.

/ck:sketch   →   /ck:map   →   /ck:make   →   /ck:check
 what to         how to        build it       verify
  build          build it                       it

Four commands. In that order. That is the whole main cycle.

• /ck:sketch — decompose your project into domains, write kits with R-numbered requirements and testable acceptance criteria.
• /ck:map — read kits, generate a tiered build site with a task dependency graph.
• /ck:make — autonomous parallel build loop. Ready tasks grouped into packets, validated, merged wave by wave. Runs until all tasks are done or a budget trips.
• /ck:check — gap analysis against kits + peer review of the code. Produces an APPROVE / REVISE / REJECT verdict and auto-amends kits when gaps appear.

One shortcut: /ck:ship "<description>" runs all four end-to-end with no user gates. For tiny features and throwaways — the guided path is better for anything non-trivial, because the design conversation is where the value is.

git clone https://github.com/JuliusBrussee/cavekit.git ~/.cavekit
cd ~/.cavekit && ./install.sh

Configures Cavekit for Claude Code, links the Codex bundle, and installs the cavekit CLI. Restart Claude Code and Codex after installing.

• Claude Code: Cavekit is consumed primarily as slash commands and subagents. Anthropic's public docs describe project and user commands under .claude/commands/ and subagents under .claude/agents/.
• Codex: Cavekit is consumed as Codex skills and plugin-bundled assets. OpenAI's docs describe skills as SKILL.md-based workflows, with plugins as the installable distribution unit.
• Cavekit ships both surfaces so the same methodology can be used from Claude Code and Codex, but they are not the same extension mechanism under the hood.

Requires: Claude Code, git, macOS/Linux.

Optional: Codex (npm install -g @openai/codex) — adds adversarial review. Cavekit works without it.

Greenfield. New repo. You want a task-management API.

> /ck:init
  Context hierarchy created. Capabilities detected.
  Next: /ck:sketch

> /ck:sketch
  What are you building?

> A REST API for task management. Users, projects, tasks with
  priorities and due dates. PostgreSQL.

  (design conversation — research if warranted, domain decomposition,
   acceptance criteria refinement)

  4 kits, 22 requirements, 69 acceptance criteria.
  Next: /ck:map

> /ck:map
  34 tasks across 5 tiers. Coverage: 69/69 criteria mapped.
  Next: /ck:make

> /ck:make
  Loop active — 34 tasks, 20 max iterations.
  Wave 1 (3 tasks), Wave 2 (4 tasks), …
  ALL TASKS DONE. Build passes. Tests pass.
  Next: /ck:check

> /ck:check
  Coverage: 100%. Verdict: APPROVE.
  CAVEKIT COMPLETE

That is the experience.

Same loop, different first command.

> /ck:sketch --from-code
  Scanning repo… Next.js 14, Prisma, NextAuth.
  6 kits reverse-engineered. 4 requirements flagged as gaps (not yet implemented).
  Next: /ck:map --filter collaboration   (or whichever domain you're adding to)

> /ck:map --filter collaboration
  8 tasks, 3 tiers.
  Next: /ck:make

> /ck:make
  …

> /ck:check
  Verdict: APPROVE. Design-system compliance: 100%.

See example.md for fully annotated sessions.

The main cycle is four commands. Everything else is optional.

Run /ck:help for flag-level detail on any command.

Four phases. Each one a slash command.

Describe what you're building in natural language. Cavekit decomposes it into domain kits — structured documents with numbered requirements (R1, R2, …) and testable acceptance criteria. Stack-independent. Human-readable.

If Codex is installed, kits go through a design challenge — adversarial review that catches decomposition flaws before any code is written.

Brownfield: /ck:sketch --from-code reverse-engineers kits from your code and flags gaps.

Reads every kit. Breaks requirements into tasks. Maps dependencies. Organizes into a tiered build site — a dependency graph where Tier 0 has no deps, Tier 1 depends only on Tier 0, and so on. Includes a Coverage Matrix mapping every acceptance criterion to its task(s). Nothing specified gets lost in translation.

Pre-flight coverage check validates all acceptance criteria are covered. Then the loop runs:

┌──────────────────────────────────────────────────────┐
│  Read build site → Find next unblocked task          │
│       ▼                                              │
│  Load kit + acceptance criteria                      │
│       ▼                                              │
│  Implement task                                      │
│       ▼                                              │
│  Validate (build + tests + acceptance criteria)      │
│       ▼                                              │
│  PASS → commit → mark done → next ──┐                │
│  FAIL → diagnose → fix → revalidate │                │
│  ◄──────────────────────────────────┘                │
│                                                      │
│  Loop until: all tasks done OR budget exhausted      │
└──────────────────────────────────────────────────────┘

/ck:make parallelizes automatically. Multiple ready tasks get grouped into coherent work packets and dispatched concurrently:

═══ Wave 1 ═══
3 task(s) ready:
  T-001: Database schema   (tier 0)
  T-002: Auth middleware   (tier 0)
  T-003: Config loader     (tier 0)

Dispatching 2 grouped subagents…
All 3 tasks complete. Merging…

═══ Wave 2 ═══
2 task(s) ready:
  T-004: User endpoints    (tier 1, deps: T-001, T-002)
  T-005: Health check      (tier 1, deps: T-003)
…

Circuit breakers prevent infinite loops: 3 test failures → task BLOCKED; all blocked → stop and report.

At every tier boundary, optional Codex review gates advancement. P0/P1 findings must be fixed before the next tier starts. Speculative review (default) adds near-zero latency.

Gap analysis: built vs. specified. Peer review: bugs, security, missed requirements. Everything traced back to kit requirements. Verdict: APPROVE / REVISE / REJECT. Gaps feed back as remediation tasks.

If the project has UI, run /ck:design first. It creates or imports DESIGN.md — a 9-section Google-Stitch-format design system. Every kit then references its design tokens; every UI task carries a Design Ref; every build result is audited for design violations during /ck:check.

/ck:design                       # interactive
/ck:design --import vercel       # start from a known system
/ck:design --from-site <url>     # extract tokens from a live site
/ck:design --audit               # gap-check an existing DESIGN.md

Settings live in two places:

/ck:config                       # show current
/ck:config preset balanced       # change preset for this repo
/ck:config preset fast --global  # change default for all repos

Cavekit has an opt-in team mode that lets multiple people — or the same person on multiple devices — safely share one build site without stepping on each other.

It is not a server. It's a CAS-backed ledger on its own git ref plus a pre-commit guard, so the coordination state travels with the repo and nothing else needs to be hosted.

cavekit team init   # once, per repo — creates the ledger ref on origin and installs a pre-commit hook
cavekit team join   # in every other checkout / clone / machine

• Claims on tasks — cavekit team claim T-013 reserves a task for your identity. Teammates see it and team next skips it.
• Path-scoped claims — two people can share one task if their file footprints are disjoint: claim T-013 --paths "src/auth/**,tests/auth/**".
• Automatic path scoping from kits — if the build site declares a Files column, claims default to those globs. No one has to guess.
• Pre-commit guard — a local hook refuses to commit files another teammate has actively claimed. Emergency override: CAVEKIT_TEAM_OVERRIDE=1 git commit … (recorded in the ledger).
• Offline-safe — claims and releases queue locally if you can't reach origin, and drain on the next successful op.
• No feature-branch pollution — the ledger lives on refs/heads/cavekit/team, not on your working branch.

Add an optional trailing Files column to any build-site table. When present, the scheduler uses it for real path-overlap detection and claim auto-defaults to these globs:

## Tier 0 — No Dependencies

| Task  | Title       | Spec     | Requirement | Effort | Files                         |
|-------|-------------|----------|-------------|--------|-------------------------------|
| T-001 | Auth module | spec.md  | R1          | S      | src/auth/**, tests/auth/**    |

## Tier 1 — Depends on Tier 0

| Task  | Title   | Spec    | Requirement | blockedBy | Effort | Files                           |
|-------|---------|---------|-------------|-----------|--------|---------------------------------|
| T-003 | DB layer| spec.md | R2          | T-001     | M      | internal/db/**; migrations/**   |

Separate globs with commas (or semicolons if a pattern itself contains a comma). Kits without a Files column keep working — the scheduler falls back to coarser heuristics for those tasks.

cavekit team status              # active claims, recent activity, idle members
cavekit team status --conflicts  # add race/override/outbox diagnostics
cavekit team next --json         # best unclaimed path-safe task for you
cavekit team claim T-013         # paths default to the kit's Files column
cavekit team release T-013 --complete
cavekit team sync --timeout 5    # fetch ledger + drain offline outbox

/ck:make integrates automatically — when team mode is active, it claims packets before dispatch, runs a background heartbeat, and releases on merge or failure.

Configuration lives in .cavekit/team/config.json (lease_ttl_seconds, heartbeat_interval_seconds, allow_offline, …). Exit codes and troubleshooting are in /ck:team --help and commands/team.md.

.cavekit/
├── config.json
├── state.md
├── .loop.json
├── .loop.lock
├── token-ledger.json
├── task-status.json
├── capabilities.json
├── .progress.json
├── .auto-backprop-pending.json
├── history/backprop-log.md
└── tool-cache/

context/                       # Project artifacts (persist across cycles)
├── kits/
│   ├── cavekit-overview.md
│   └── cavekit-{domain}.md
├── designs/
│   ├── DESIGN.md
│   └── design-changelog.md
├── plans/
│   └── build-site.md
├── impl/
│   ├── impl-{domain}.md
│   ├── impl-review-findings.md
│   └── loop-log.md
└── refs/

.cavekit/                      # Runtime state (machine-managed)
├── config.json
├── state.md
├── .loop.json
├── .loop.lock
├── token-ledger.json
├── task-status.json
├── capabilities.json
├── .progress.json
├── .auto-backprop-pending.json
├── history/backprop-log.md
└── tool-cache/

If cavekit save you mass debug time — leave star.

Three tools. One philosophy: agent do more with less.

They compose: cavekit orchestrates the build, caveman compresses what the agent says (bundled, on by default for build/inspect phases), cavemem compresses what the agent remembers across sessions. Install one, some, or all — each stands alone.

• Revu — local-first macOS study app with FSRS spaced repetition. revu.cards

MIT