Cavekit Writing

Cavekit Writing

Core Principle: Kits Describe WHAT, Not HOW

Kits are implementation-agnostic. They define what the system must do and how to verify it, but never prescribe a specific framework, language, or architecture.

This is the fundamental distinction in Cavekit:

• Kits = WHAT must be true (framework-agnostic, durable, portable)
• Plans = HOW to build it (framework-specific, derived from kits)
• Code = the implementation (generated from plans, validated against kits)

Why Implementation-Agnostic?

When kits avoid prescribing HOW, they become:

• Portable — the same kits can drive implementations in different frameworks
• Durable — kits survive technology migrations
• Testable — acceptance criteria are about behavior, not implementation details
• Reusable — the same kits work for greenfield, rewrites, and cross-framework evaluation

Bad cavekit requirement: "Use React useState hook to manage form state" Good cavekit requirement: "Form state persists across user interactions within a session. Acceptance: entering values, navigating away, and returning preserves all entered values."

Every Requirement Needs Testable Acceptance Criteria

This is the single most important rule in Cavekit writing. If an agent cannot automatically validate a requirement, that requirement will not be met.

The Validation-First Rule

Every requirement must answer: "How would an automated test verify this?"

Acceptance Criteria Format

Each criterion should be:

• Observable — can be checked by reading output, UI state, or logs
• Deterministic — same input always produces same pass/fail result
• Automatable — an agent can write a test that checks this
• Independent — does not depend on subjective judgment

**Acceptance Criteria:**
- [ ] {Action} results in {observable outcome}
- [ ] Given {precondition}, when {action}, then {result}
- [ ] {Metric} meets {threshold} under {conditions}

Hierarchical Structure with Index

Kits must be organized as a hierarchy — one index file linking to domain-specific sub-kits. This enables progressive disclosure: agents read the index first, then only the sub-kits relevant to their task.

The Cavekit Index Pattern

Create a cavekit-overview.md as the entry point:

# Cavekit Overview

## Domains

| Domain | Cavekit File | Summary |
|--------|-----------|---------|
| Authentication | cavekit-auth.md | User registration, login, session management, OAuth |
| Data Models | cavekit-data-models.md | Core entities, relationships, validation rules |
| API | cavekit-api.md | REST endpoints, request/response formats, error handling |
| UI Components | cavekit-ui-components.md | Shared components, accessibility, responsive behavior |
| Notifications | cavekit-notifications.md | Email, push, in-app notification delivery |

## Cross-Cutting Concerns
- Security requirements: see cavekit-auth.md R3, cavekit-api.md R7
- Performance budgets: see cavekit-api.md R12, cavekit-ui-components.md R5
- Accessibility: see cavekit-ui-components.md R8-R10

Why Hierarchical?

1. Context window efficiency — agents load only the domains they need
2. Parallel work — different agents can own different spec domains
3. Review efficiency — humans can review domain-by-domain
4. Cross-referencing — domains link to each other explicitly

Cross-Referencing Between Kits

Related kits must link to each other. Cross-references prevent requirements from being lost at domain boundaries.

Cross-Reference Patterns

## Cross-References
- **Depends on:** cavekit-auth.md R1 (session tokens required for API access)
- **Depended on by:** cavekit-notifications.md R4 (uses user preferences from this cavekit)
- **Related:** cavekit-ui-components.md R6 (error display components used by this domain)

When to Cross-Reference

• When one domain's requirement depends on another domain's output
• When shared entities are defined in one cavekit but used in many
• When validation criteria span multiple domains
• When out-of-scope items are in-scope for another cavekit

Full Cavekit Format Template

Use this template for every domain cavekit:

# Cavekit: {Domain Name}

## Scope
{One paragraph describing what this spec covers and its boundaries.}

## Requirements

### R1: {Requirement Name}
**Description:** {What must be true — stated in terms of behavior, not implementation.}
**Acceptance Criteria:**
- [ ] {Testable criterion 1}
- [ ] {Testable criterion 2}
- [ ] {Testable criterion 3}
**Dependencies:** {Other specs/requirements this depends on, or "None"}

### R2: {Requirement Name}
**Description:** {What must be true}
**Acceptance Criteria:**
- [ ] {Testable criterion 1}
- [ ] {Testable criterion 2}
**Dependencies:** {Dependencies}

### R3: ...

## Out of Scope
{Explicit list of things this cavekit does NOT cover. This is critical — it prevents
agents from over-building and clarifies domain boundaries.}
- {Thing explicitly excluded and why}
- {Another exclusion}

## Cross-References
- See also: cavekit-{related-domain}.md — {why it is related}
- Depends on: cavekit-{dependency}.md R{N} — {what is needed}
- Depended on by: cavekit-{dependent}.md R{N} — {what depends on this}

Template Rules

1. Number requirements sequentially (R1, R2, R3...) — agents reference them by ID
2. Every requirement gets acceptance criteria — no exceptions
3. Out of Scope is mandatory — explicit exclusions prevent scope creep
4. Cross-References section is mandatory — even if it says "None"
5. Scope section is one paragraph — concise boundary description

Greenfield Pattern: Reference Material → Kits

When building from scratch, you start with reference materials and derive kits from them.

Flow

context/refs/              context/kits/
├── prd.md          →      ├── cavekit-overview.md
├── design-doc.md   →      ├── cavekit-auth.md
├── api-draft.md    →      ├── cavekit-api.md
└── research/       →      ├── cavekit-data-models.md
    └── ...         →      └── cavekit-ui.md

Process

1. Place all reference materials in context/refs/
2. Run cavekit generation — agent reads all refs, decomposes into domains
3. Agent produces:
   • cavekit-overview.md — index with domain summaries
   • One cavekit-{domain}.md per identified domain
   • Cross-references between related domains
4. Human reviews kits for completeness and correctness
5. Iterate — refine kits based on review feedback

Greenfield Prompt Pattern

The first prompt in a greenfield pipeline (typically 001-generate-kits-from-refs.md) should:

• Read all files in context/refs/
• Decompose reference material into domains
• Generate kits following the template above
• Create cavekit-overview.md as the index
• Cross-reference related kits

Rewrite Pattern: Old Code → Reference Docs → Kits

When rewriting an existing system, the existing code becomes your reference material. But you never go directly from old code to new code — you always extract kits first.

Flow

Existing codebase          context/refs/              context/kits/
├── src/            →      ├── ref-apis.md      →     ├── cavekit-overview.md
├── tests/          →      ├── ref-data-models.md →   ├── cavekit-auth.md
└── docs/           →      ├── ref-ui-components.md →  ├── cavekit-api.md
                           └── ref-architecture.md →   └── cavekit-data.md

Process

1. Agent explores the existing codebase and generates reference documents
2. Reference docs capture the current system's behavior, APIs, data models, and UI patterns
3. Agent generates kits from reference docs — implementation-agnostic requirements
4. Validate kits against existing code — verify acceptance criteria match current behavior
5. Proceed with normal Hunt — kits drive the new implementation

Rewrite Prompt Pattern

Rewrites typically use more prompts because of the reverse-engineering step:

• 001: Generate reference materials from old code
• 002: Generate kits from references + feature scope
• 003: Validate kits against existing codebase
• 004+: Plans and implementation

The key difference from greenfield: step 003 validates that your kits actually describe what the old system does, before you start building the new one.

Cavekit Compaction

When implementation tracking or cavekit files grow beyond approximately 500 lines, they become unwieldy for agents to process efficiently. Spec compaction compresses large files while preserving active context.

When to Compact

• Implementation tracking file exceeds 500 lines
• Cavekit file has many resolved/completed requirements mixed with active ones
• Agent is spending too much context window on historical information

How to Compact

1. Identify resolved content: completed tasks, resolved issues, archived dead ends
2. Archive removed content to a separate file (e.g., impl/archive/impl-domain-v1.md)
3. Preserve in the compacted file:
   • All active/in-progress tasks
   • All open issues
   • Recent dead ends (last 2-3 sessions)
   • Current test health status
   • Active cross-references
4. Target: under 500 lines in the active file

Compaction Rule

Never delete information — move it to an archive. Agents can still find archived context if needed, but it will not consume context window during normal operations.

Gap Analysis

Gap analysis compares what was built against what was intended, identifying where kits, plans, or validation fell short.

How to Perform Gap Analysis

1. Read kits (intended behavior) and implementation tracking (what was built)
2. For each cavekit requirement, check if acceptance criteria are satisfied
3. Classify each requirement:

4. Report gaps with: which cavekit, which criterion, what is missing
5. Feed gaps into revision — update kits if needed, then re-implement

Gap Analysis as Feedback

Gap analysis is not a one-time activity. Run it:

• After each implementation iteration
• Before starting a new session (to prioritize work)
• When convergence stalls (to identify what is blocking progress)