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

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.

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 Transitions

Each phase has gate conditions that must be met before moving to the next:

1. Draft → Architect: All domains have kits with testable acceptance criteria. Human has reviewed for completeness.
2. Architect → Build: Plans reference kits, define implementation sequence, and include test strategies. Architecture decisions validated.
3. Build → Inspect: Code builds, tests pass at current coverage level, implementation tracking is up to date.
4. Inspect → Monitor: Convergence detected (changes decreasing iteration-over-iteration). Remaining changes are trivial.
5. Monitor → Draft (cycle): Gap found or new requirement identified. Revise kits and restart the cycle.

The Inspect phase is where the human serves as reviewer and decision-maker, not hands-on coder. You monitor the process, request changes as needed, and make systemic improvements to kits and prompts.

For the full Hunt phase reference, see references/hunt-phases.md.

Decision Matrix: When to Use Cavekit

Full Cavekit

Use when the project has significant scope, evolving requirements, or needs autonomous agent execution.

What you get: Full Hunt lifecycle, context directory with kits/plans/impl tracking, prompt pipeline, convergence loops, revision, validation gates.

Lightweight Cavekit

Use when scope is moderate — too complex for ad-hoc but not worth a full pipeline.

What you do:

1. Write a focused context/kits/cavekit-task.md capturing requirements
2. Add a context/plans/plan-task.md sequencing the implementation
3. Skip full Hunt — just run an iteration loop against the plan

This is the "Cavekit floor" — most of the benefit without the overhead of a full multi-phase pipeline.

Skip Cavekit

Use when the task is trivially small.

Heuristic: If the whole task fits in one context window with room to spare, full Cavekit adds more overhead than value.

Growth Path

Start with lightweight Cavekit even if the project is small. If the scope expands, you already have the structure in place to scale up. It is much harder to retrofit kits onto a large codebase than to grow a cavekit directory from the beginning.

The CI Pipeline Analogy

Cavekit mirrors a build pipeline — each stage transforms input into validated output, with feedback loops that propagate corrections upstream:

Traditional CI/CD:
  Code → Build → Test → Deploy

Cavekit AI Pipeline:
  Cavekit Change
    → Generate Plans (iteration loop)
    → Generate Implementation (iteration loop)
    → Validate (Tests + Review)
    → Human Audit (Monitor & Steer)
    → [Gap Found]
    → Revise
    → Cavekit Change (cycle repeats)

Every stage can run as an iteration loop — the same prompt executed repeatedly until output stabilizes. The iteration loop is what transforms nondeterministic LLM output into predictable, validated software.