Methodology

# Cavekit Methodology

## Core Principle: Specify Before Building

**Always define what you want before telling agents how to build it. Go through a cavekit stage — never jump straight from raw requirements to implementation.**

Cavekit is a methodology for building software with AI coding agents that **puts kits at the center of the development process — code is derived from them, not the other way around**. Whether starting from scratch or modernizing an existing system, the principle is the same:

- **Greenfield projects:** reference material → kits → code
- **Rewrites:** old code → kits → new code

In both cases, the kits become a living contract that agents consume to continuously build, validate, and refine the application.

### Why Kits Are the First-Class Citizen

| Property | Benefit |
|----------|---------|
| **Structured** | Organized as a navigable tree, enabling agents to load only what they need |
| **Human-legible** | Engineers can audit requirements at a higher level than code |
| **Stack-independent** | Decoupled from any single framework or language |
| **Independently evolvable** | Kits can be refined without touching implementation |
| **Verifiable** | Every requirement includes acceptance criteria agents can check |

> **Key Insight:** Well-written kits with strong validation make your application reproducible — any agent can rebuild it from the kits alone. Think of it as continuous regeneration.

---

## The Scientific Method Analogy

LLMs are inherently non-deterministic — like running an experiment, each individual call may yield different results. But through the right methodology — clear hypotheses, controlled conditions, and repeated trials — we extract reliable, reproducible outcomes from a stochastic process.

**Cavekit applies the scientific method to software construction — hypothesize, test, observe, refine.**

| Layer | Analogy | What It Does |
|-------|---------|-------------|
| **LLM calls** | Individual experiments | Each run may produce different results; no single output is authoritative |
| **Kits** | Hypotheses | Define what you expect to observe — the predicted behavior |
| **Validation gates** | Controlled conditions | Ensure reproducibility by constraining what counts as a valid outcome |
| **Convergence loops** | Repeated trials | Build statistical confidence through successive passes |
| **Implementation tracking** | Lab notebook | Record what was tried, what worked, and what failed |
| **Revision** | Revising the hypothesis | When results contradict expectations, update the theory upstream |

The outcome: a disciplined, repeatable engineering process layered on top of probabilistic generation.

---

## The 5 Hunt Phases

The Hunt is the four-phase lifecycle: **Sketch, Map, Make, Check**. Each phase has dedicated prompts that drive it.

| Phase | Input | Output | AI Role | Human Role |
|-------|-------|--------|---------|------------|
| **Draft** | Source materials, domain knowledge, existing systems | Implementation-agnostic kits | Extract requirements, structure knowledge | Verify kits capture intent accurately |
| **Architect** | Kits + framework research | Framework-specific implementation plans | Design architecture, break down work, order steps | Approve architectural choices |
| **Build** | Plans + kits | Working code + tests + tracking docs | Write code, run tests, check against kits | Watch for drift and blockers |
| **Inspect** | Failed validations, gaps, manual fixes | Updated kits/plans via