Lifecycle
The lifecycle is the heartbeat of REAP — each generation flows through 5 stages (Learning → Planning → Implementation → Validation → Completion), producing artifacts at every step. Completion has 4 phases: reflect → fitness → adapt → commit.
Artifacts Structure
.reap/life/
├── current.yml # Current generation state (id, goal, stage, timeline)
├── 01-learning.md # Context exploration, genome/environment review
├── 02-planning.md # Task decomposition, dependencies
├── 03-implementation.md # Implementation log, changes made
├── 04-validation.md # Test results, completion criteria check
├── 05-completion.md # Reflect + fitness + adapt + commit
└── backlog/ # Items for next generation
├── fix-auth-bug.md # type: task
└── add-index.md # type: genome-changeEach stage produces its artifact in .reap/life/. When the generation completes, all artifacts are archived to .reap/lineage/gen-XXX-hash-slug/ and current.yml is cleared for the next generation.
/reap.evolve — The Primary Way to Work
Most of the time, you run /reap.evolve and let the AI agent drive through all stages autonomously. It can delegate the entire generation to a subagent that runs through all stages, surfacing only when genuinely blocked (ambiguous goal, significant trade-off, genome conflict, or unexpected error). The subagent handles starting, executing each stage, advancing, and archiving.
For fine-grained control, you can run individual stage commands. See Command Reference for details.
Stage-by-Stage Walkthrough
Explore the project and build context. The AI reviews genome, environment, lineage, and assesses the clarity level. It builds a thorough understanding of the current state before any goal is set.
Output: 01-learning.md — context exploration, genome/environment review, clarity assessment.
Break the goal into actionable tasks. The AI reads the context from learning, references genome conventions and constraints, and proposes an implementation plan with architecture decisions.
Output: 02-planning.md — phased task list, dependencies, parallelizable tasks marked with [P].
Build the code. Tasks are executed sequentially, with each completion recorded immediately. When genome or environment defects are discovered, they're logged to the backlog — never applied directly. Tasks that depend on pending genome changes are marked [deferred].
Output: 03-implementation.md — completed tasks table, deferred tasks, genome-change backlog items.
Verify the work. Run tests, lint, build, and type checks. Check completion criteria and apply minor fixes (5 min or less, no design changes). Verdict is pass, partial (some criteria deferred), or fail.
Output: 04-validation.md — test results with actual command output, criteria check table, verdict.
Reflect: write retrospective + refresh environment. Fitness: collect human feedback (or self-assessment in cruise mode). Adapt: review genome, apply backlog changes, propose next generation goals. Commit: archive to lineage + git commit. A generation can also terminate early via /reap.early-close (lightweight, preserves partial value, auto-defers incomplete tasks) or /reap.abort (cancellation, no lineage entry).
Output: 05-completion.md — retrospective, fitness feedback, genome changelog, next generation hints.
Micro Loop (Regression)
Any stage can go back to a previous stage. This is common — validation fails and you return to implementation, or a planning flaw is found during implementation and you go back to planning. The regression reason is recorded in the timeline and the target artifact.
Artifact handling on regression:
- Before target stage: Preserved as-is
- Target stage: Overwritten (implementation only appends)
- After target stage: Preserved, overwritten upon re-entry
Minor Fix
Trivial issues (typos, lint errors, etc.) can be fixed directly in the current stage without a regression, as long as they're resolvable within 5 minutes and require no design changes. The fix is recorded in the stage artifact.
Role Separation
| Who | Role |
|---|---|
| CLI (reap) | Project setup and maintenance — init, status, run |
| AI Agent | Workflow executor — performs each stage's work via slash commands |
| Human | Decision maker — sets goals, reviews code, provides fitness feedback |