Guide

Core Concepts

4-Layer Architecture

REAP consists of four interconnected layers:

Vision

.reap/vision/

Long-term goals and direction. Goals drive each generation. Memory persists context across sessions.

Knowledge

.reap/genome/ + .reap/environment/

Genome (prescriptive — how to build) + Environment (descriptive — what exists). The basis for each generation.

Generation

.reap/life/

A single evolution cycle driven by Vision, grounded in Knowledge. Follows Learning → Planning → Implementation → Validation → Completion.

Civilization

your codebase/

Source code and all project artifacts outside .reap/. What generations evolve. Lessons feed back into Knowledge.

Key Principles

Genome Immutability

Never modified during a normal generation. Changes go through backlog → Completion adapt phase. (Embryo generations allow free modification.)

Human Judges Fitness

No quantitative metrics. The human's natural language feedback is the only fitness signal.

Clarity-Driven Interaction

The AI adjusts communication depth based on context clarity — from active dialogue to autonomous execution. See Self-Evolving Features for details.

Lifecycle Overview

Each generation follows five stages, producing artifacts at each step:

Learning→Planning→Implementation⟷Validation→Completion

Stage	What happens	Artifact
Learning	Explore project, build context, review genome and environment	01-learning.md
Planning	Task decomposition + implementation plan	02-planning.md
Implementation	Code with AI + human collaboration	03-implementation.md
Validation	Run tests, verify completion criteria	04-validation.md
Completion	Reflect + fitness feedback + adapt genome + archive (4 phases)	05-completion.md

→ Lifecycle details · → Backlog & Deferral

Session Context Loading

When you open a REAP project, CLAUDE.md instructs the AI agent to read genome, environment, and the REAP guide. The agent immediately loads the project's knowledge and understands the current state.

Evolution Flow

Knowledge compounds across generations. Each generation evolves the Genome, and lessons accumulate in Lineage:

text

Generation #1 (Genome v1)
  → Learning: explore project, build context
  → Planning → Implementation
  → OAuth2 need discovered → genome-change logged in backlog
  → Validation (partial)
  → Completion: reflect → fitness → adapt (genome v2) → commit → Archive

Generation #2 (Genome v2)
  → Learning: review updated genome, deferred tasks
  → Vision-driven goal: "OAuth2 integration + permission management"
  → ...