Self-Evolving Features
REAP is not a static framework. The AI automatically selects goals from vision and memory, the human judges fitness through natural language feedback, and the pipeline adjusts its communication style based on context clarity. These features work together to create a development pipeline that genuinely evolves alongside your project.
Gap-Driven Goal Selection
At the end of each generation (adapt phase), the AI analyzes the gap between the project's vision and its current state to propose the next goal. This is the core mechanism that makes REAP self-evolving.
- Read unchecked goals from vision/goals.md
- Cross-reference with pending backlog items for priority boost
- Rank by impact — goals with related backlog tasks score higher
- Propose the top candidate to the human for approval
In cruise mode, goal selection happens automatically between generations without human intervention.
Human Judges Fitness
There are no quantitative metrics. The human's natural language feedback during the fitness phase is the only fitness signal. The AI is explicitly prohibited from scoring its own success — only self-assessment (metacognition) is allowed.
This ensures the project evolves toward what the human values, not toward what the AI can optimize for.
Clarity-Driven Interaction
The AI dynamically assesses how well-defined the current context is and adjusts its communication depth accordingly. Clarity is evaluated at the start of each generation during the learning stage.
| Clarity | Signals | AI Behavior |
|---|---|---|
| High | Clear goal, defined tasks, established patterns | Execute with minimal questions. Report results. |
| Medium | Direction exists, details unclear | Present 2-3 options with tradeoffs. Let human choose. |
| Low | Ambiguous goal, conflicting constraints | Active dialogue with examples to build shared understanding. |
Cruise Mode
Pre-approve N generations for autonomous execution. The AI selects goals from vision gaps and backlog tasks, runs the full lifecycle, and self-assesses (not self-scores) each generation.
# Enable cruise mode for 5 generations
reap cruise 5Activation: Sets cruiseCount: 1/5 in config.yml. The counter increments after each generation completes.
Goal selection: During adapt, the AI analyzes gaps between vision/goals.md and the current state, then picks the highest-value next goal.
Fitness: In cruise mode, the fitness phase uses self-assessment (metacognition) instead of waiting for human feedback. The AI is explicitly prohibited from scoring its own success.
Pause conditions: Cruise automatically pauses and requests human input when: (1) uncertainty exceeds the AI's confidence threshold, (2) a decision requires human judgment (e.g., breaking API changes), or (3) the backlog contains conflicting priorities. After all N generations complete, the human reviews the batch.
Memory System
Memory is a free-form recording system where the AI persists context across sessions and generations. Unlike Genome (modification-constrained) or Lineage (compressed over time), Memory is always accessible and freely writable.
.reap/vision/memory/
longterm.md # Project lifetime — lasting lessons, decision rationale
midterm.md # Multi-generation — ongoing work context, plans
shortterm.md # 1-2 sessions — next session handoff, immediate context| Tier | Role | Decision rule | Pruning |
|---|---|---|---|
| shortterm | Session handoff | "Is this needed right now?" | Replaced every generation — never accumulates |
| midterm | Ongoing tracks | "Is this an incomplete large track?" | Deleted when a track completes, after promoting its lessons |
| longterm | Design lessons | "Does this prevent the next generation repeating a mistake?" | Entries already covered by the genome are removed |
Rules:
- Read and write at any time — no phase restriction, no permission needed
- Classify by what the content is FOR, not how long it will live. Lifespan requires predicting the future, which produced misclassification and bloat
- Finished with no lasting lesson? Do not record it — lineage and git history already preserve it
- Pruning is mandatory during the reflect phase, not optional cleanup
- Bloat is a failure signal: longterm past ~50 lines or midterm past ~70 means pruning was skipped. Empty files are a valid state
Vision & Gap-Driven Evolution
Vision is the primary driver of each generation. The file .reap/vision/goals.md defines north-star objectives for the project. During the adapt phase, the AI performs gap analysis: comparing vision goals against the current state of the codebase.
The human writes high-level objectives in goals.md. Each goal is a markdown checkbox item. Goals can be nested for sub-objectives.
The AI compares unchecked goals against the current codebase, environment, and generation history. It identifies the highest-value gap and suggests it as the next generation's goal.
When a generation achieves a vision goal, the AI marks the corresponding checkbox in goals.md during the adapt phase. This provides a persistent view of project progress.
Vision evolves too. The human updates goals as the project's direction changes. The AI references both completed and remaining goals to maintain trajectory.
# goals.md example
- [x] Core lifecycle engine (learning -> completion)
- [x] Genome 3-file structure
- [ ] Distributed merge workflow
- [x] Detect + mate stages
- [ ] Reconcile stage with genome-source consistency check
- [ ] Plugin system for custom stage logic