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?"**

| Weak Criterion | Strong Criterion |
|----------------|-----------------|
| "UI should look good" | "All interactive elements have minimum 44x44px touch targets" |
| "System should be fast" | "API responses return within 200ms at p95 under 100 concurrent users" |
| "Handle errors gracefully" | "Network failures display a retry prompt with exponential backoff (1s, 2s, 4s)" |
| "Support authentication" | "Valid credentials return a session token; invalid credentials return 401 with error message" |

### 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

```markdown
**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:

```markdown
# 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-ap