Guide

Vision

Vision is the layer that drives direction. The human defines where the project is going — setting goals, milestones, and priorities. The AI references vision during the adapt phase to analyze gaps and propose the next goal, but the human owns the vision.

Structure

text

.reap/vision/
  goals.md              # North star objectives and milestones
  docs/                 # Planning documents, specs, design notes
  memory/               # AI memory (3-tier)
    longterm.md          #   Project lifetime — lessons, decision rationale
    midterm.md           #   Multi-generation — ongoing plans, agreed directions
    shortterm.md         #   1-2 sessions — next session handoff, immediate context

Goals

goals.md contains the project's long-term objectives as a checklist. During the adapt phase, the AI analyzes gaps between vision and current state to suggest the next generation's goal. Completed goals are automatically checked off.

markdown

# Vision Goals

## Ultimate Goal
Build a self-evolving development pipeline.

## Goal Items
- [x] Core lifecycle implementation
- [x] Merge lifecycle
- [ ] README rewrite for v0.16
- [ ] External project validation

Memory

Memory is a free-form recording system where AI persists context across sessions and generations. Unlike genome (which has modification constraints) or lineage (which gets compressed), memory is always accessible and freely writable.

Tier	Role	Decision rule
Shortterm	Session handoff — context for the next session	"Is this needed right now?"
Midterm	Ongoing tracks — multi-generation work in progress	"Is this an incomplete large track?"
Longterm	Design lessons — worth re-reading later	"Does this prevent a repeated mistake?"

When to Update

Reflect phase — natural moment to update memory (shortterm is mandatory every generation)
Any time — memory can be updated during any stage if useful context arises
Shortterm cleanup — clear items that have been acted on

What NOT to Write in Memory

Code change details — belongs in environment
Test counts or build status — belongs in artifacts
Principles already in genome — no duplication

Gap-driven Evolution

During the adapt phase of completion, the AI:

Reads goals.md and scans backlog
Identifies unchecked goals and pending tasks
Cross-references with the current project state
Suggests the next generation's goal based on the most impactful gap