Guide

Hooks

REAP hooks let you run automation at key lifecycle events. Hooks are stored as individual files in .reap/hooks/ and the AI agent executes them at the right moment.

Hook Types

Each hook file supports one of two types based on its extension:

command (.sh)

A shell script. Executed in the project root directory by the AI agent. Use for scripts, CLI tools, build commands.

prompt (.md)

An AI agent instruction in Markdown. The agent reads the prompt and performs the described task — code analysis, file modifications, documentation updates, etc. Use for tasks that require judgment.

Each hook is a single file. Multiple hooks per event are executed in the order specified by frontmatter.

File Naming

Hook files follow the pattern: .reap/hooks/{event}.{name}.{md|sh}

Each hook file supports optional YAML frontmatter:

Field	Description
condition	Name of a condition script in .reap/hooks/conditions/ (e.g. always, has-code-changes, version-bumped)
order	Numeric execution order when multiple hooks exist for the same event (default: 50, lower runs first)

Events

Event	When it fires
onLifeStarted	After /reap.start creates a new generation
onLifeLearned	After learning 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)
onMergeStarted	After merge generation is created
onMergeDetected	After detect stage completes
onMergeMated	After mate stage completes (genome resolved)
onMergeMerged	After merge stage completes (source merged)
onMergeReconciled	After reconcile stage completes (genome-source consistency verified)
onMergeValidated	After merge validation completes
onMergeCompleted	After merge completion + archiving
onMergeTransited	After any merge stage transition (generic)

File-based Configuration

Hooks are file-based — stored in .reap/hooks/, not in config.yml. Each hook is a file named {event}.{name}.{md|sh}.

text

.reap/hooks/
├── onLifeCompleted.reap-update.sh
├── onLifeCompleted.docs-update.md
├── onLifeImplemented.lint-check.sh
└── onMergeMated.notify.md

# Example: .md hook (AI prompt)
# ---
# condition: has-code-changes
# order: 30
# ---
# Review changes and update docs if needed.

# Example: .sh hook (shell script)
# #!/bin/bash
# # condition: always
# # order: 20
# reap update

Automatic Hook Suggestion

During the Completion stage (Phase 5: Hook Suggestion), REAP detects repeated patterns across generations — such as recurring manual steps, repeated commands, or consistent post-stage actions. When a pattern is detected, REAP suggests creating a hook to automate it. Hook creation always requires user confirmation before being applied.

Execution Notes

Hooks are executed by the AI agent, not the CLI. The agent scans .reap/hooks/ for matching files.
.sh files run as shell scripts in the project root directory.
.md files are read as AI prompts and followed by the agent.
Hooks within the same event run in order (frontmatter 'order' field, lower runs first).
Conditions are evaluated via .reap/hooks/conditions/{name}.sh (exit 0 = run, non-zero = skip).
onLifeCompleted/onMergeCompleted hooks run after the git commit — any file changes from hooks will be uncommitted.