Brownfield Adoption

# Brownfield Adoption: Adding Cavekit to Existing Codebases

Brownfield adoption layers kits on top of existing code without rewriting it. The existing codebase becomes reference material, and kits are reverse-engineered from what the code actually does. Once kits exist, all future changes flow through the Cavekit lifecycle.

**Core principle:** The existing code is not the enemy -- it is the source of truth for cavekit generation. Respect what works; cavekit what matters.

---

## 1. When to Use Brownfield Adoption

Brownfield adoption is the right choice when:

- You have a **working codebase** that you want to improve incrementally
- You want to adopt Cavekit **without stopping development**
- The codebase is too large or critical for a full rewrite
- You want **traceability** between kits and code for future changes
- You need to **onboard AI agents** to an existing project safely
- The team wants to start with Cavekit on a subset of the codebase

**Brownfield is NOT the right choice when:**
- You are migrating to a completely different framework (use a deliberate rewrite instead)
- The existing code is so broken that kits would just document bugs
- The codebase is being sunset or replaced

---

## 2. Brownfield vs Deliberate Rewrite

Before starting, decide which approach fits your situation:

| Dimension | Incremental Adoption | Clean-Slate Rebuild |
|-----------|---------------------|---------------------|
| **Objective** | Add cavekit coverage around working code | Replace the codebase with a new implementation |
| **What happens to existing code** | Remains in place, evolves under Cavekit governance | Archived once kits are extracted; new code replaces it |
| **Risk profile** | Lower -- production system stays functional throughout | Higher -- new system must achieve feature parity before cutover |
| **Time to first value** | Fast -- kits appear in days, improvements follow | Slow -- significant upfront investment before any return |
| **Ideal scenarios** | Production systems, incremental improvement, large legacy codebases | Technology stack changes, irrecoverable tech debt, greenfield-quality rebuilds |
| **How kits originate** | Derived by analyzing existing behavior | Written forward from product requirements |
| **Handling broken behavior** | Kits capture current state; bugs are fixed through normal Cavekit cycles | Kits capture intended state; fresh implementation avoids old bugs |
| **Impact on ongoing work** | Low -- regular development continues alongside adoption | High -- team capacity is split between old and new systems |

### Decision flowchart

```
Is the existing code fundamentally sound?
  YES -> Are you changing frameworks?
           YES -> Deliberate Rewrite (extract specs, build new)
           NO  -> Brownfield Adoption (layer specs, evolve)
  NO  -> Is a rewrite feasible (time, budget, risk)?
           YES -> Deliberate Rewrite
           NO  -> Brownfield Adoption (spec the broken parts, fix incrementally)
```

---

## 3. The 6-Step Brownfield Process

### Step 1: Set Up the Context Directory

Create the standard Cavekit context directory structure alongside your existing codebase:

```bash
mkdir -p context/{refs,kits,plans,impl,prompts}
```

Resulting structure:

```
your-project/
+-- src/                    # Existing source code (untouched)
+-- tests/                  # Existing tests (untouched)
+-- package.json            # Existing config (untouched)
+-- context/
    +-- refs/
    |   +-- architecture-overview.md   # High-level description of existing s