Software isn't built in one shot — it's evolved. REAP brings that same evolutionary process to AI-assisted development.
The Spec-Driven Approach and Its Limits
The natural first instinct for AI-assisted development is spec-driven: write a detailed specification, hand it to the AI, get working code back. Tools like spec-kit explored this direction — managing specifications as the single source of truth (SSOT).
I used this approach and learned a lot from it. But I kept hitting the same friction: spec-to-code is not deterministic. Give the same spec to two AI sessions and you'll get different code. The mapping from specification to implementation isn't a function — it's a statistic distribution.
- Specs drift from code. The AI makes architectural choices the spec didn't anticipate.
- Updating specs is a losing game. The spec ends up chasing the code, not driving it.
- Context compounds. Each iteration creates implicit decisions the spec can't capture.
A spec is a snapshot of intent, not a living representation of a system. Code is the living representation. Specs are great for capturing intent at a moment in time, but they can't be the SSOT for a system that evolves continuously.
What Actually Works: Following the Proven Human Development Pipeline
Experienced developers don't write a perfect spec and execute it blindly. They:
- Set a goal → 2. Plan → 3. Implement (discovering the unexpected) → 4. Validate → 5. Reflect and update their mental model
This is exactly what Agile taught us. Waterfall failed because it assumed you could fully specify a system before building it. Agile succeeded with iterative delivery, continuous feedback, and adaptation. Sprints, retrospectives, backlog grooming — these let teams discover requirements through building, not before building.
But here's the irony: we threw all of this away when AI entered the picture. We went back to waterfall thinking — write a big prompt (the spec), generate the code (the build), and hope it works. No iterations. No retrospectives. No accumulated learning.
The real insight: create an environment where AI can follow the same proven pipeline that humans use — the one Agile formalized. Not generating code from specs, but evolving code through structured iterations with feedback loops.
That's why I built REAP.
REAP: Recursive Evolutionary Autonomous Pipeline
REAP is an open-source CLI tool and command prompt set that structures AI-assisted development as an evolutionary process. Instead of one-shot code generation, it organizes work into generations — each with a clear objective, plan, implementation, validation, and retrospective.
The metaphor is biological evolution:
| Layer | Analogy | What It Actually Is |
|---|
| Genome | DNA | Architecture principles, business rules, conventions, constraints |
| Evolution | Natural selection | The generational lifecycle that drives improvement |
| Civilization | The organism | Your source code — the accumulated result |
The Genome: Living Knowledge, Not Dead Docs
The Genome is stored in .reap/genome/ and contains four files:
.reap/genome/
├── principles.md # Architecture decisions with rationale (ADR-style)
├── domain/ # Business rules per module
├── conventions.md # Development standards + enforced rules
└── constraints.md # Tech choices + validation commands
But here's what makes it different from documentation: the Genome evolves through the development process itself. It's not written up front and forgotten. It's discovered, refined, and corrected generation after generation.
When the AI discovers during implementation that an architecture decision is wrong, it doesn't silently fix it. It logs a genome-change backlog item. At the end of the generation, those changes are reviewed and applied to the Genome. This means:
- The Genome gets more accurate over time, not less
- Architectural decisions carry their rationale and date
- The knowledge is always in sync with the code because the code feeds back into it
The Five-Stage Lifecycle
Each generation follows a complete lifecycle:
Objective → Planning → Implementation ⟷ Validation → Completion
1. Objective — Define what this generation will accomplish. Not a vague "improve the app" but a concrete goal with acceptance criteria. The AI reads the Genome, reviews the backlog from previous generations, and helps formulate a focused objective.
2. Planning — Break the objective into concrete tasks (max 20). Each task specifies target files and approach. The AI references the Genome to ensure the plan follows established conventions.
3. Implementation — The AI writes code, following the plan. When it discovers something the plan didn't anticipate — a constraint the Genome doesn't mention, a business rule that needs clarification — it logs it in the backlog instead of making silent assumptions.
4. Validation — Run the actual test suite, type checker, and build. No "I think it should work" — the AI must execute validation commands and report real results. If something fails, it can loop back to Implementation.
5. Completion — Retrospective. What worked? What didn't? What did we learn? Genome changes from the backlog are reviewed and applied. The generation is archived in the lineage.
Context That Survives Sessions
One of the biggest problems with AI-assisted development is context loss. Start a new Claude Code session and your AI has no idea what happened yesterday.
REAP solves this with a SessionStart hook that automatically injects into every new session:
- The full Genome (architecture decisions, conventions, constraints)
- Current generation state (which stage you're in, what's next)
- The REAP workflow rules
The AI picks up exactly where you left off. No re-explaining. No "let me read through the codebase first." The Genome gives it the project knowledge; the generation state gives it the task context.
The Backlog: Structured Memory
Every insight, every discovered issue, every deferred task goes into the backlog:
---
type: genome-change
status: pending
target: genome/constraints.md
---
# Add rate limiting constraint
During auth implementation, discovered we need rate limiting
on login endpoints. This should be a documented constraint.
Types of backlog items:
genome-change — The Genome needs updating (applied at Completion)environment-change — External context changedtask — Work to carry into future generations
This means nothing gets lost. A discovery in Generation 3 about a missing business rule gets properly logged, reviewed, and either addressed or carried forward. The project's institutional memory grows with every generation.
A Concrete Example
Let's trace through a real development flow building an inventory management app:
Generation #1 — Goal: "Set up project structure + user authentication + item CRUD"
Objective: Define auth requirements, item schema, API structure
Planning: 8 tasks — project scaffold, DB schema, auth middleware,
CRUD endpoints, shared types, basic tests
Implementation: Build it. Discover that the planned JWT approach
needs refresh tokens (logged as genome-change).
Validation: Run tests, type check, build. 2 tests fail → loop back
to Implementation → fix → Validation passes.
Completion: Retrospective notes that API error handling needs
standardization. Genome updated with JWT + refresh
token decision. Archive generation.
Generation #2 — Goal: "Unit categories + inventory transactions"
The AI starts this generation already knowing:
- The JWT + refresh token decision from Gen 1
- The API error handling concern (from the backlog)
- All architecture conventions established so far
Each generation builds on the knowledge of previous ones. The Genome evolves. The code evolves. The understanding evolves.
Getting Started
npm install -g @c-d-cc/reap
reap init my-project
claude
> /reap.evolve "Implement user authentication"
That's it. /reap.evolve runs the entire lifecycle interactively — from Objective through Completion. You can also drive each stage manually with individual slash commands (/reap.objective, /reap.planning, etc.) if you want finer control.
REAP also supports strict mode (blocks code changes outside the lifecycle), lifecycle hooks (run shell commands or AI prompts at stage transitions), and lineage compression (auto-archives old generations to keep context lean).
Why This Approach Wins
vs. One-Shot Prompting
One-shot prompting ("build me X") works for small tasks. It falls apart for anything that requires accumulated context, iterative refinement, or long-term coherence. REAP gives you the structure to build complex systems incrementally.
vs. Spec-Driven Development
Specs try to capture intent before implementation. But implementation reveals things specs can't anticipate. REAP embraces this by making discovery a first-class part of the process. The Genome evolves because of implementation, not despite it.
vs. RAG/Context Stuffing
Many tools try to solve context loss by stuffing more code into the context window. This is expensive, noisy, and doesn't scale. REAP's Genome is a curated, structured knowledge base — typically under 500 lines — that captures the why behind decisions, not just the code.
The Deeper Philosophy
The biggest mistake in AI-assisted development isn't bad prompts or insufficient context. It's treating AI as a code generator instead of a development partner.
Human developers don't generate code from specs. They evolve software through cycles of planning, building, testing, and learning. The learning part is crucial — it's what makes the 10th feature better than the 1st.
When we give AI agents the same structured pipeline that works for humans — with explicit goals, plans, validation, and retrospectives — they produce dramatically better results. Not because the AI is smarter, but because the process is smarter.
REAP doesn't make the AI write better code. It makes the AI develop better — which includes knowing when to ask questions, when to log discoveries, when to defer decisions, and how to build on what came before.
The future of AI-assisted development isn't better prompts. It's better pipelines.
Get Started
REAP currently integrates with Claude Code. If you're building anything beyond toy projects with AI, give it a try. Your Generation #5 self will thank your Generation #1 self.
Hi, I'm a developer exploring the intersection of AI and software engineering workflows. I built REAP because I got tired of re-explaining my project to AI every morning. You can find me on GitHub or check out the REAP documentation.
