Recursive Evolutionary Autonomous Pipeline
A development pipeline where AI and humans evolve software across generations.
| Knowledge Base Genome + Environment |
→ | Evolution Generational Progress |
→ | Civilization Source Code |
REAP captures an application's design knowledge — the Genome (architecture, conventions, constraints) and Environment (external APIs, infrastructure) — then sets objectives for each generation to implement. Defects discovered along the way feed back into the Knowledge Base. As generations accumulate, knowledge evolves and the Source Code (Civilization) grows.
- Why REAP?
- Installation
- Quick Start
- Life Cycle
- Core Concepts
- Distributed Workflow
- CLI Commands
- Agent Integration
- Project Structure
- Lineage Compression
- Evolution Flow
- Presets
- Entry Modes
Have you ever run into these problems when developing with AI agents?
- Context loss — The agent forgets the project context every time you start a new session
- Scattered development — Code gets modified here and there with no clear goal
- Design–code drift — Documentation and code diverge over time
- Forgotten lessons — Hard-won insights from past struggles never carry forward
- Collaboration chaos — Multiple developers or agents working in parallel leads to conflicting changes and merge nightmares
REAP solves these with a generation-based evolution model:
- Each generation focuses on a single objective (Objective → Completion)
- The AI agent automatically picks up current context at every session start (SessionStart Hook)
- Design issues discovered during implementation are logged in the backlog and addressed at Completion
- Lessons drawn from retrospectives (Completion) accumulate in the Genome
- Repeated manual tasks are automatically detected across generations, with user-confirmed hook creation
- Parallel work across branches is reconciled through a genome-first merge workflow — design conflicts are resolved before code conflicts
Global installation required. REAP is a CLI tool and must be installed globally. Local project-level installation (
npm i @c-d-cc/reap) is blocked.
# npm
npm install -g @c-d-cc/reap
# or Bun
bun install -g @c-d-cc/reapRequirements: Node.js v18+, Claude Code or OpenCode CLI. Bun is optional.
# 1. Initialize the project
# New project
reap init my-project
# Existing project
cd my-project
reap init
# 2. Open Claude Code, sync knowledge, then run a full generation
claude
> /reap.sync
> /reap.evolve "Implement user authentication"/reap.evolve runs the entire generation lifecycle — from Objective through Completion — interactively with you. It automatically starts a generation, executes each stage in order, and advances between them. This is the primary command you'll use for day-to-day development.
You can also drive each stage manually if you need finer control:
> /reap.start # Start a new generation
> /reap.objective # Define objective + spec (--phase complete auto-advances)
> /reap.planning # Create implementation plan (--phase complete auto-advances)
> /reap.implementation # Build with AI + human collaboration
> /reap.validation # Run tests, verify completion criteria
> /reap.completion # Retrospective + finalizeLife Cycle ↗
Each generation goes through a five-stage life cycle:
Objective → Planning → Implementation ⟷ Validation → Completion
| Stage | What happens | Artifact |
|---|---|---|
| Objective | Define goal through structured brainstorming: clarifying questions, 2-3 approach alternatives, sectional design approval, optional visual companion, and spec review loop | 01-objective.md |
| Planning | Break down tasks, choose approach, map dependencies | 02-planning.md |
| Implementation | Build with AI + human collaboration | 03-implementation.md |
| Validation | Run tests, verify completion criteria | 04-validation.md |
| Completion | Retrospective + apply Genome changes + hook suggestion + auto-archive (consume + archive + commit) | 05-completion.md |
Core Concepts ↗
Genome ↗
The application's genetic information — a collection of architecture principles, business rules, development conventions, and technical constraints.
.reap/genome/
├── principles.md # Architecture principles/decisions
├── domain/ # Business rules (per module)
├── conventions.md # Development rules/conventions
├── constraints.md # Technical constraints/choices
└── source-map.md # C4 Container/Component diagram (Mermaid)
Genome Immutability Principle: The Genome is never modified directly during the current generation. When an issue is found, it is recorded in the backlog and only applied at the Completion stage.
Environment Immutability Principle: The Environment is never modified directly during the current generation. External changes are recorded in the backlog and applied at the Completion stage.
Backlog ↗
All items to be addressed next are stored in .reap/life/backlog/. Each item uses markdown + frontmatter format:
type: genome-change— Applied to the Genome at Completiontype: environment-change— Applied to the Environment at Completiontype: task— Candidate goals for the next Objective (deferred tasks, tech debt, etc.)
Each item also carries a status field:
status: pending— Not yet processed (default)status: consumed— Processed in the current generation (requiresconsumedBy: gen-XXX-{hash})
At archiving time (during Completion), consumed items move to lineage while pending items are carried forward to the next generation's backlog.
Partial completion is normal — Tasks that depend on Genome changes are marked [deferred] and handed off to the next generation.
Four-Axis Structure ↗
.reap/
├── genome/ # Genetic information (evolves across generations)
├── environment/ # External context (API docs, infra, business constraints)
├── life/ # Lifecycle — current generation's state and artifacts
└── lineage/ # Archive of completed generations
Distributed Workflow ↗
⚠ Early Stage — The distributed workflow requires further testing. Use with caution in production. We're collecting feedback — open an issue.
REAP supports a distributed workflow for collaboration environments where multiple developers or AI agents work on the same project in parallel — without a central server. Git is the only transport layer.
Machine A: branch-a — gen-046-a (authentication) → /reap.push
Machine B: branch-b — gen-046-b (search) → /reap.push
Machine A:
/reap.pull branch-b → Fetch + full merge generation lifecycle
Each machine works independently on its own branch and generation. When it's time to combine, REAP orchestrates the merge with a genome-first strategy (learn more):
- Detect — Identify divergence by scanning the remote branch's genome and lineage via git refs
- Mate — Resolve genome conflicts first (human decides)
- Merge — Merge source code guided by the finalized genome (
git merge --no-commit) - Sync — AI compares genome and source for consistency; user confirms any inconsistencies
- Validation — Run mechanical testing (bun test, tsc, build) — same as normal generation
- Completion — Commit the merged result and archive
All distributed operations run through your AI agent:
/reap.pull <branch> # Fetch + run full merge generation (the distributed /reap.evolve)
/reap.merge <branch> # Run full merge generation for a local branch (no fetch)
/reap.push # Validate REAP state + push current branch
/reap.merge.start # Start a merge generation (for step-by-step control)
/reap.merge.detect # Analyze divergence
/reap.merge.mate # Resolve genome conflicts
/reap.merge.merge # Merge source code
/reap.merge.sync # Verify genome–source consistency
/reap.merge.validation # Run mechanical testing (bun test, tsc, build)
/reap.merge.evolve # Run merge lifecycle from current stage- Opt-in —
git pull/pushalways work normally. REAP commands are additive. - Genome-first — Genome conflicts are resolved before source merge. Like amending the constitution before updating the laws.
- No server — Everything is local + Git. No external services.
- DAG lineage — Each generation references its parents via a hash-based ID (
gen-046-a3f8c2), forming a directed acyclic graph that naturally supports parallel work.
CLI Commands ↗
| Command | Description |
|---|---|
reap init <name> |
Initialize project. Creates the .reap/ structure |
reap status |
Check the current generation's status |
reap update |
Sync commands/templates/hooks to the latest version |
reap fix |
Diagnose and repair the .reap/ structure (--check for read-only mode) |
reap clean |
Reset REAP project with interactive options |
reap destroy |
Remove all REAP files from project (requires typing "yes destroy" to confirm) |
reap help |
Print CLI commands, slash commands, and workflow summary |
reap run <cmd> |
Execute a slash command's script directly (used internally by 1-line .md wrappers) |
reap init my-project --mode adoption # Apply REAP to an existing project
reap init my-project --preset bun-hono-react # Initialize Genome with a preset
reap update --dry-run # Preview changes before applyingREAP integrates with AI agents through slash commands and session hooks. Currently supported agents: Claude Code and OpenCode.
Since v0.11.0, all 31 slash commands follow a 1-line .md wrapper + TypeScript script pattern. Each .md file simply calls reap run <cmd>, and the TS script (src/cli/commands/run/) handles all deterministic logic — returning structured JSON instructions for the AI agent. This ensures consistency and testability.
Signature-Based Locking ↗
REAP uses a cryptographic nonce chain to enforce stage ordering. When --phase complete runs, it generates a one-time nonce, stores its hash in current.yml, and auto-transitions to the next stage. The next stage command verifies the nonce at entry — without it, the stage is rejected.
--phase complete current.yml Next Stage Entry
──────────────── ─────────── ────────────────
generate nonce ──────→ store hash(nonce)
auto-transition ─────→ advance stage
←── verify nonce at entry
verify hash(nonce)
✓ advance stage
This prevents:
- Skipping stages — no valid nonce exists for stages that were not executed
- Forging tokens — the hash is one-way; guessing the nonce from the hash is infeasible
- Replaying old nonces — each nonce is single-use and bound to the current stage
When /reap.evolve is run, REAP can automatically delegate the entire generation lifecycle to a subagent. This is controlled by:
# .reap/config.yml
autoSubagent: true # default: trueThe subagent receives the full context and runs autonomously through all stages, only surfacing when genuinely blocked.
When an unexpected error occurs during reap run, REAP can automatically create a GitHub Issue via gh issue create. This is controlled by:
# .reap/config.yml
autoIssueReport: true # default: true (when gh CLI is available)When reap update detects structural gaps between your project and the latest REAP version (e.g., missing config fields, outdated templates), it offers an AI-assisted migration prompt. The agent analyzes the differences and applies changes interactively — no manual migration needed.
reap init also ensures all config fields are explicitly declared, and reap update backfills any missing fields automatically.
During reap init and reap update, REAP adds a managed section to .claude/CLAUDE.md containing essential project context for Claude Code sessions.
Slash Commands ↗
Slash commands are installed in .claude/commands/ and drive the entire workflow:
| Command | Description |
|---|---|
/reap.start |
Start a new generation |
/reap.objective |
Define goal + requirements |
/reap.planning |
Task decomposition + implementation plan |
/reap.implementation |
Code implementation with AI + human |
/reap.validation |
Run tests, verify completion criteria |
/reap.completion |
Retrospective + apply Genome changes + lineage compression |
/reap.next |
Confirm auto-transition (fallback) |
/reap.back |
Return to a previous stage (micro loop) |
/reap.abort |
Abort current generation (rollback/stash/hold + backlog save) |
/reap.status |
Show current generation state and project health |
/reap.sync |
Synchronize both Genome and Environment |
/reap.sync.genome |
Synchronize Genome with current source code |
/reap.sync.environment |
Discover and document external environment dependencies |
/reap.config |
Display current project configuration |
/reap.report |
Report a bug or feedback to the REAP project (privacy-safe) |
/reap.help |
Contextual AI help with 24+ topics |
/reap.update |
Upgrade REAP package + sync commands/templates/hooks |
/reap.update-genome |
Apply pending genome-change backlog without a generation |
/reap.evolve |
Run an entire generation from start to finish (recommended) |
/reap.evolve.recovery |
Recover from a failed/interrupted generation |
/reap.pull <branch> |
Fetch + run full merge generation (distributed /reap.evolve) |
/reap.merge <branch> |
Run full merge generation for a local branch (no fetch) |
/reap.push |
Validate REAP state and push current branch |
/reap.merge.start |
Start a merge generation to combine divergent branches |
/reap.merge.detect |
Analyze divergence between branches |
/reap.merge.mate |
Resolve genome conflicts before source merge |
/reap.merge.merge |
Merge source code with resolved genome as guide |
/reap.merge.sync |
Verify genome–source consistency (AI compares, user confirms) |
/reap.merge.validation |
Run mechanical testing (bun test, tsc, build) |
/reap.merge.evolve |
Run the full merge lifecycle automatically |
/reap.refreshKnowledge |
Reload REAP context (Genome, Environment, state). Useful after context compaction or in subagents |
SessionStart Hook ↗
Runs automatically at the start of every session, injecting the following into the AI agent:
- The full REAP workflow guide (Genome, Life Cycle, Four-Axis Structure, etc.)
- Current generation state (which stage you're in, what to do next)
- Environment summary (
environment/summary.md) — external system context - Rules to follow the REAP lifecycle
- Genome staleness detection — checks if code-related commits have occurred since the last Genome update
- Source-map drift detection — compares documented components against actual files
- Slash command installation — copies commands from
~/.reap/commands/to project.claude/commands/
This ensures the agent immediately understands the project context even in a brand-new session.
Strict Mode ↗
Strict mode controls what the AI agent is allowed to do. It supports two granular options:
# .reap/config.yml
strict: true # shorthand: enables both edit and merge
# Or granular control:
strict:
edit: true # restrict code changes to REAP lifecycle
merge: false # restrict raw git pull/push/mergestrict.edit — Code modification control:
| Context | Behavior |
|---|---|
| No active generation / non-implementation stage | Code modifications are fully blocked |
| Implementation stage | Only modifications within the scope of 02-planning.md are allowed |
| Escape hatch | User explicitly requests "override" or "bypass strict" — bypass applies to that specific action only, then strict mode re-engages |
strict.merge — Git command control: when enabled, direct git pull/push/merge are restricted. The agent guides users to use /reap.pull, /reap.push, /reap.merge instead.
Both are disabled by default. strict: true enables both.
Strict mode is disabled by default (strict: false).
REAP Hooks ↗
Hooks are file-based and stored in .reap/hooks/. Each hook is a file named {event}.{name}.{md|sh}:
.mdfiles contain AI prompts (executed by the AI agent).shfiles contain shell scripts (executed directly)
.reap/hooks/
├── onLifeStarted.context-load.md
├── onLifeCompleted.reap-update.sh
├── onLifeCompleted.docs-update.md
├── onLifeTransited.notify.sh
└── onLifeRegretted.alert.sh
Each hook file supports frontmatter with the following fields:
---
condition: has-code-changes # script name in .reap/hooks/conditions/
order: 10 # execution order (lower runs first)
---Normal Lifecycle Events:
| Event | Trigger |
|---|---|
onLifeStarted |
After /reap.start creates a new generation |
onLifeObjected |
After objective stage completes |
onLifePlanned |
After planning stage completes |
onLifeImplemented |
After implementation stage completes |
onLifeValidated |
After validation stage completes |
onLifeCompleted |
After completion + archiving (runs after git commit) |
onLifeTransited |
After any stage transition (generic) |
onLifeRegretted |
After /reap.back regression |
Merge Lifecycle Events:
| Event | Trigger |
|---|---|
onMergeStarted |
After /reap.merge.start creates a merge generation |
onMergeDetected |
After detect stage completes |
onMergeMated |
After mate stage completes (genome resolved) |
onMergeMerged |
After merge stage completes (source merged) |
onMergeSynced |
After sync stage completes |
onMergeValidated |
After merge validation completes |
onMergeCompleted |
After merge completion + archiving |
onMergeTransited |
After any merge stage transition (generic) |
my-project/
├── src/ # Civilization (your code)
└── .reap/
├── config.yml # Project configuration
├── genome/ # Genetic information
│ ├── principles.md
│ ├── domain/
│ ├── conventions.md
│ ├── constraints.md
│ └── source-map.md
├── hooks/ # Lifecycle hooks (.md/.sh)
├── environment/ # External context (3-layer)
│ ├── summary.md # Session context (~100 lines, auto-loaded)
│ ├── docs/ # Main reference docs
│ └── resources/ # Raw materials (user-managed)
├── life/ # Current generation
│ ├── current.yml
│ └── backlog/
└── lineage/ # Completed generation archive
~/.reap/ # User-level (installed by reap init)
├── commands/ # Slash command originals (1-line .md wrappers)
└── templates/ # Artifact templates
~/.claude/
└── settings.json # SessionStart hook registration
.claude/commands/ # Project-level slash commands
└── reap.*.md # Active slash commands (each calls `reap run <cmd>`)
Lineage Compression ↗
As generations accumulate, the lineage directory grows. REAP manages this with automatic two-level compression during the Completion stage:
| Level | Input | Output | Trigger | Protection |
|---|---|---|---|---|
| Level 1 | Generation folder (5 artifacts) | gen-XXX-{hash}.md (40 lines) |
lineage > 5,000 lines + 5+ generations | Recent 3 generations + DAG leaf nodes |
| Level 2 | 100+ Level 1 files | Single epoch.md |
Level 1 files > 100 | Recent 9 Level 1 files + fork points |
DAG preservation: Level 1 files retain DAG metadata (id, parents, genomeHash) in frontmatter. Level 2 epoch.md stores a generations hash chain in frontmatter for DAG traversal.
Fork guard: Before Level 2 compression, all local and remote branches are scanned. Generations that serve as fork points for other branches are protected from epoch compression. Epoch-compressed generations cannot be used as merge bases.
Generation #1 (Genome v1)
→ Objective: "Implement user authentication"
→ Planning → Implementation
→ OAuth2 need discovered during Implementation → genome-change logged in backlog
→ Validation (partial)
→ Completion → Retrospective + genome update → Genome v2 → Archive
Generation #2 (Genome v2)
→ Objective: "OAuth2 integration + permission management"
→ Deferred tasks from previous generation + new goals
→ ...
Use reap init --preset to apply an initial Genome configuration tailored to your tech stack.
| Preset | Stack |
|---|---|
bun-hono-react |
Bun + Hono + React |
reap init my-project --preset bun-hono-react| Mode | Description |
|---|---|
greenfield |
Build a new project from scratch (default) |
migration |
Build anew while referencing an existing system |
adoption |
Apply REAP to an existing codebase |
HyeonIL Choi — hichoi@c-d.cc | c-d.cc | LinkedIn | GitHub
MIT