REAP (c-d-cc/reap) — Summary

REAP (Recursive Evolutionary Autonomous Pipeline) is a generation-based development framework where AI and humans co-evolve software across discrete, structured generations. Each generation follows a five-stage lifecycle (learning → planning → implementation → validation → completion), and every completed generation feeds lessons back into a typed knowledge base split into Genome (prescriptive: architecture, conventions, constraints) and Environment (descriptive: codebase, dependencies, domain). The most distinctive mechanic is automatic two-level lineage compression: generation artifacts auto-compress into summary files, which further compress into epoch files after 100+ generations, keeping context manageable without manual pruning. REAP ships as a global npm CLI (@c-d-cc/reap) with adapter support for Claude Code and OpenCode, deploying 15 slash commands through each client's native slash-command system. A nonce-chain integrity mechanism enforces stage ordering at the code level — stages cannot be skipped, forged, or replayed. Closest in spirit to SPEC-DRIVER's delta-first lifecycle, but REAP replaces SPEC-DRIVER's spec artifact files with a biology-metaphor knowledge layer (Genome/Environment/Lineage) where the knowledge base itself evolves between generations rather than being authored once up-front.

REAP (c-d-cc/reap) — Overview

Identity

Problem Statement

REAP addresses five failure modes of AI-assisted development:

1. Context loss — agents forget everything between sessions
2. Scattered development — code modified with no clear direction
3. Design-code drift — documentation diverges from implementation
4. Forgotten lessons — hard-won insights never carry forward
5. Collaboration chaos — multiple agents produce conflicting changes

Solution Approach

REAP wraps AI development in a generational model borrowed from biology:

• Genome stores prescriptive knowledge (how to build)
• Environment stores descriptive knowledge (what exists now)
• Civilization is the source code (what gets evolved)
• Lineage archives the history of completed generations
• Vision holds long-term goals and 3-tier AI memory

Each generation is a complete cycle with typed artifacts and approval gates. Between generations, the Genome and Environment are updated to reflect what was learned — the knowledge base self-evolves.

Supported AI Clients

• Claude Code (default, agentClient: claude-code)
• OpenCode (agentClient: opencode)

Switching clients: edit .reap/config.yml → run reap install-skills && reap update.

Quick Start

npm install -g @c-d-cc/reap
# Open Claude Code in your project
/reap.init       # Initialize REAP (auto-detects greenfield vs. existing codebase)
/reap.evolve     # Run a complete generation

REAP (c-d-cc/reap) — Architecture

System Layers

┌─────────────────────────────────────────┐
│  Adapter Layer (src/adapters/)          │  dispatcher + per-client modules
├─────────────────────────────────────────┤
│  CLI Layer (src/cli/)                   │  command routing, phase dispatch
├─────────────────────────────────────────┤
│  Core Layer (src/core/)                 │  lifecycle, nonce, archive, compression
├─────────────────────────────────────────┤
│  State Layer (.reap/)                   │  file-based state (YAML + Markdown)
└─────────────────────────────────────────┘

State Layer — .reap/ Directory

.reap/
  config.yml                # Project config (agentClient, cruiseCount, strictEdit, etc.)
  genome/                   # Prescriptive knowledge (always fully loaded)
    application.md          # Project identity, architecture, conventions, constraints
    evolution.md            # AI behavior guide, evolution direction, soft lifecycle rules
    invariants.md           # Absolute constraints (human-only edits)
  environment/              # Descriptive knowledge (two-tier loading)
    summary.md              # Always loaded at session start (~100 lines)
    domain/                 # Domain knowledge (on-demand)
    resources/              # External reference docs (API specs, SDK docs) — on-demand
    docs/                   # Project reference docs (design docs, specs) — on-demand
    source-map.md           # Current code structure + dependencies — on-demand
  vision/
    goals.md                # North star objectives (drives gap-based goal selection)
    docs/                   # Planning documents
    memory/                 # AI memory (longterm.md / midterm.md / shortterm.md)
  life/
    current.yml             # Active generation metadata (stage, goal, nonce chain)
    backlog/                # Pending backlog items (.yml per item)
  lineage/                  # Completed generation archive (auto-compressed)
  hooks/                    # Lifecycle hooks (.md = AI prompt, .sh = shell script)

Adapter Layer

The adapter dispatcher (src/adapters/index.ts) reads agentClient from config and routes installs/updates to the correct adapter. Each adapter handles:

• Entry-point file generation (CLAUDE.md or AGENTS.md)
• Slash command deployment (~/.claude/commands/reap.*.md or ~/.config/opencode/commands/)
• Session integration (SessionStart hook vs. plugin on session.created)
• Dynamic state dump (.reap/.session-state.md for OpenCode)

Claude Code Adapter

• Entry-point: CLAUDE.md with @ imports for static knowledge (genome + environment summary + reap-guide)
• Session integration: ~/.claude/settings.json SessionStart hook → reap load-context
• Commands: 15 .md files at ~/.claude/commands/reap.*.md

OpenCode Adapter

• Entry-point: AGENTS.md + opencode.json instructions field
• Session integration: .opencode/plugins/reap-plugin.ts — fires on session.created and tool.execute.before
• Dynamic state: .reap/.session-state.md — synchronously written after every REAP lifecycle command

Nonce-Chain Integrity

Stage ordering is enforced at the code level. Each lifecycle command:

1. Validates the current nonce against life/current.yml
2. Executes
3. Writes a new nonce before returning

This prevents stage skipping, forgery, and replay. No skipping from planning to completion without completing implementation and validation first.

Two-Level Lineage Compression

• Level 1: After a generation completes, its 5 artifact files (.md per stage) are compressed into a single summary file
• Level 2: After 100+ Level 1 files accumulate, they are compressed into a single epoch.md

DAG metadata is preserved through compression, enabling branch-aware lineage traversal during merge workflows.

Immutability Constraints

REAP (c-d-cc/reap) — Components

CLI Binary

• Binary: reap (global npm install)
• Package: @c-d-cc/reap
• Runtime: Node.js v18+ (built with Bun)
• Key internal commands: reap load-context, reap install-skills, reap update, reap run <cmd>

Slash Commands (15)

All deployed to ~/.claude/commands/reap.*.md (Claude Code) or ~/.config/opencode/commands/ (OpenCode).

Core Layer Modules (src/core/)

Genome Files (3 fixed files)

Environment Loading Strategy

• summary.md — always loaded at session start (~100 lines)
• domain/, resources/, docs/, source-map.md — on-demand only

This two-tier strategy prevents context bloat while keeping essential context always available.

Memory System (3-tier, under .reap/vision/memory/)

Unlike Genome (immutability constraints) and Lineage (auto-compressed), Memory is always accessible and freely writable by the AI.

Hooks (.reap/hooks/)

• .md files — AI prompts executed by the agent at lifecycle events
• .sh files — shell scripts executed directly

Hooks extend lifecycle stages without modifying the core CLI.

Configuration (.reap/config.yml)

Key fields:

• agentClient: claude-code | opencode — controls adapter selection
• cruiseCount: N/M — enables cruise mode (N = current generation, M = total approved)
• autoSubagent: true/false — auto-delegate evolve to subagent
• strictEdit: true/false — restrict code changes to REAP lifecycle scope
• strictMerge: true/false — restrict direct git pull/push/merge
• language: english — artifact and prompt language

REAP (c-d-cc/reap) — Uniqueness

What Makes REAP Distinctive

1. Biology Metaphor as a Complete Mental Model

REAP is the only framework in the batch that uses an internally consistent biology metaphor as its entire architectural vocabulary:

This is not decoration — the metaphor is load-bearing. Because Genome = DNA, it must be stable during development. Because Fitness = natural selection, the AI cannot self-score. The metaphor predicts the rules.

2. Genome Immutability + Backlog Discipline

No other framework in the batch enforces a hard constraint against modifying knowledge during a generation. REAP's rule: all discovered issues go to backlog; knowledge updates happen only at designated phases (reflect, adapt). This prevents the most common failure mode in iterative development — scope creep as "quick fixes" that accumulate into an unrecognizable codebase.

3. Two-Level Lineage Compression with DAG Preservation

5 stage artifacts → 1 summary (Level 1). 100+ summaries → 1 epoch (Level 2). DAG metadata is preserved through both compression levels, enabling branch-aware lineage traversal. No other framework in batch-19 has a comparable auto-compression scheme for long-running project history.

4. Human-Only Fitness Signal

The invariants.md file is human-only — the AI is prohibited from writing to it. The fitness phase accepts only natural-language human feedback. No automated test suites, no quantitative metrics, no AI self-scoring. This is a deliberate philosophical stance: quantitative metrics are gameable; human judgment is not.

5. Nonce-Chain Stage Ordering Enforcement

Stage ordering is enforced at the code level via a nonce chain in life/current.yml. This is not a "please follow the workflow" instruction in a markdown prompt — it is a cryptographic lock that the CLI validates before executing any stage transition. No other framework in this batch implements equivalent lifecycle integrity at the code level.

6. Adapter Abstraction for Multi-Client Support

The adapter dispatcher (src/adapters/index.ts) allows REAP to target multiple AI clients from a single codebase. Switching from Claude Code to OpenCode is one config field change + reap update. The adapter generates the appropriate entry-point file, session integration, and slash command deployment for the target client. This is architecture-level multi-tool support, not just documentation coverage.

7. Clarity-Driven Interaction

The AI's communication density is programmatically tied to context clarity level. High clarity → execute quietly. Low clarity → active dialogue. This prevents the common anti-pattern of verbose agents that ask permission at every step in well-understood situations.

Differs From Seeds

Most similar to: SPEC-DRIVER (delta-first lifecycle with structured spec artifacts per phase) and SPEC-KIT (structured knowledge files loaded at session start).

Key differences from SPEC-DRIVER: SPEC-DRIVER tracks spec artifacts (requirements.md, design.md, tasks.md) as the workflow output. REAP tracks a typed knowledge base (Genome, Environment) that itself evolves between generations. SPEC-DRIVER specs are authored; REAP knowledge is grown.

Key differences from SPEC-KIT: SPEC-KIT's memory bank is static files (AGENTS.md, architecture.md, decisions.md). REAP's equivalent (Genome + Environment + Memory) has strict immutability rules, compression, and a schema-constrained 3-file structure. REAP adds the generation lifecycle and nonce enforcement that SPEC-KIT lacks entirely.

Absent from all seeds: Two-level lineage compression with DAG preservation, nonce-chain stage enforcement at the code level, biology-metaphor architecture vocabulary, and cruise mode (N autonomous generations with gap-driven goal selection).