@c-d-cc/reap 0.2.1 → 0.3.0

package/dist/cli.js

@@ -8840,7 +8840,7 @@ var {
 } = import__.default;
 
 // src/cli/commands/init.ts
-import { mkdir as mkdir3 } from "fs/promises";
+import { mkdir as mkdir3, readdir as readdir3, chmod } from "fs/promises";
 import { join as join4 } from "path";
 
 // src/core/paths.ts
@@ -8943,7 +8943,7 @@ class ReapPaths {
   get legacyTemplates() {
     return join(this.root, "templates");
   }
-  get legacyHooks() {
+  get hooks() {
     return join(this.root, "hooks");
   }
   get legacyClaudeCommands() {
@@ -9178,10 +9178,10 @@ class ClaudeCodeAdapter {
     return { action: "migrated" };
   }
   getHookEntry() {
-    const sessionStartPath = join2(ReapPaths.packageHooksDir, "session-start.sh");
+    const sessionStartPath = join2(ReapPaths.packageHooksDir, "session-start.cjs");
     return {
       matcher: "",
-      hooks: [{ type: "command", command: `bash "${sessionStartPath}"` }]
+      hooks: [{ type: "command", command: `node "${sessionStartPath}"` }]
     };
   }
   hasReapHook(sessionStartHooks) {
@@ -9450,7 +9450,7 @@ async function initProject(projectRoot, projectName, entryMode, preset, onProgre
   };
   await ConfigManager.write(paths, config);
   log("Setting up Genome templates...");
-  const genomeTemplates = ["principles.md", "conventions.md", "constraints.md"];
+  const genomeTemplates = ["principles.md", "conventions.md", "constraints.md", "source-map.md"];
   const genomeSourceDir = preset ? join4(ReapPaths.packageTemplatesDir, "presets", preset) : ReapPaths.packageGenomeDir;
   for (const file of genomeTemplates) {
     const src = join4(genomeSourceDir, file);
@@ -9468,6 +9468,19 @@ async function initProject(projectRoot, projectName, entryMode, preset, onProgre
   const domainGuideSrc = join4(ReapPaths.packageGenomeDir, "domain/README.md");
   const domainGuideDest = join4(ReapPaths.userReapTemplates, "domain-guide.md");
   await writeTextFile(domainGuideDest, await readTextFileOrThrow(domainGuideSrc));
+  log("Installing hook conditions...");
+  const conditionsSourceDir = join4(ReapPaths.packageTemplatesDir, "conditions");
+  const conditionsDestDir = join4(paths.hooks, "conditions");
+  await mkdir3(conditionsDestDir, { recursive: true });
+  const conditionFiles = await readdir3(conditionsSourceDir);
+  for (const file of conditionFiles) {
+    if (!file.endsWith(".sh"))
+      continue;
+    const src = join4(conditionsSourceDir, file);
+    const dest = join4(conditionsDestDir, file);
+    await writeTextFile(dest, await readTextFileOrThrow(src));
+    await chmod(dest, 493);
+  }
   log("Detecting AI agents...");
   const detectedAgents = await AgentRegistry.detectInstalled();
   const sourceDir = ReapPaths.packageCommandsDir;
@@ -9484,7 +9497,7 @@ async function initProject(projectRoot, projectName, entryMode, preset, onProgre
 }
 
 // src/cli/commands/update.ts
-import { readdir as readdir3, unlink as unlink3, rm, mkdir as mkdir4 } from "fs/promises";
+import { readdir as readdir4, unlink as unlink3, rm, mkdir as mkdir4 } from "fs/promises";
 import { join as join5 } from "path";
 
 // src/core/hooks.ts
@@ -9510,7 +9523,7 @@ async function updateProject(projectRoot, dryRun = false) {
   const config = await ConfigManager.read(paths);
   const adapters = await AgentRegistry.getActiveAdapters(config ?? undefined);
   const commandsDir = ReapPaths.packageCommandsDir;
-  const commandFiles = await readdir3(commandsDir);
+  const commandFiles = await readdir4(commandsDir);
   for (const adapter of adapters) {
     const agentCmdDir = adapter.getCommandsDir();
     const label = `${adapter.displayName}`;
@@ -9579,10 +9592,9 @@ async function updateProject(projectRoot, dryRun = false) {
 async function migrateLegacyFiles(paths, dryRun, result) {
   await removeDirIfExists(paths.legacyCommands, ".reap/commands/", dryRun, result);
   await removeDirIfExists(paths.legacyTemplates, ".reap/templates/", dryRun, result);
-  await removeDirIfExists(paths.legacyHooks, ".reap/hooks/", dryRun, result);
   try {
     const claudeCmdDir = paths.legacyClaudeCommands;
-    const files = await readdir3(claudeCmdDir);
+    const files = await readdir4(claudeCmdDir);
     for (const file of files) {
       if (file.startsWith("reap.") && file.endsWith(".md")) {
         if (!dryRun)
@@ -9630,7 +9642,7 @@ async function migrateLegacyFiles(paths, dryRun, result) {
 }
 async function removeDirIfExists(dirPath, label, dryRun, result) {
   try {
-    const entries = await readdir3(dirPath);
+    const entries = await readdir4(dirPath);
     if (entries.length > 0 || true) {
       if (!dryRun)
         await rm(dirPath, { recursive: true });
@@ -9641,7 +9653,7 @@ async function removeDirIfExists(dirPath, label, dryRun, result) {
 
 // src/core/generation.ts
 var import_yaml2 = __toESM(require_dist(), 1);
-import { readdir as readdir5, mkdir as mkdir5, rename } from "fs/promises";
+import { readdir as readdir6, mkdir as mkdir5, rename } from "fs/promises";
 import { join as join7 } from "path";
 
 // src/types/index.ts
@@ -9696,13 +9708,14 @@ class LifeCycle {
 }
 
 // src/core/compression.ts
-import { readdir as readdir4, rm as rm2 } from "fs/promises";
+import { readdir as readdir5, rm as rm2 } from "fs/promises";
 import { join as join6 } from "path";
-var LINEAGE_MAX_LINES = 1e4;
+var LINEAGE_MAX_LINES = 5000;
 var MIN_GENERATIONS_FOR_COMPRESSION = 5;
 var LEVEL1_MAX_LINES = 40;
 var LEVEL2_MAX_LINES = 60;
 var LEVEL2_BATCH_SIZE = 5;
+var RECENT_PROTECTED_COUNT = 3;
 async function countLines(filePath) {
   const content = await readTextFile(filePath);
   if (content === null)
@@ -9713,7 +9726,7 @@ async function countLines(filePath) {
 async function countDirLines(dirPath) {
   let total = 0;
   try {
-    const entries = await readdir4(dirPath, { withFileTypes: true });
+    const entries = await readdir5(dirPath, { withFileTypes: true });
     for (const entry of entries) {
       const fullPath = join6(dirPath, entry.name);
       if (entry.isFile() && entry.name.endsWith(".md")) {
@@ -9728,7 +9741,7 @@ async function countDirLines(dirPath) {
 async function scanLineage(paths) {
   const entries = [];
   try {
-    const items = await readdir4(paths.lineage, { withFileTypes: true });
+    const items = await readdir5(paths.lineage, { withFileTypes: true });
     for (const item of items) {
       const fullPath = join6(paths.lineage, item.name);
       if (item.isDirectory() && item.name.startsWith("gen-")) {
@@ -9911,7 +9924,8 @@ async function compressLineageIfNeeded(paths) {
   if (totalLines <= LINEAGE_MAX_LINES) {
     return result;
   }
-  const dirs = entries.filter((e) => e.type === "dir").sort((a, b) => a.genNum - b.genNum);
+  const allDirs = entries.filter((e) => e.type === "dir").sort((a, b) => a.genNum - b.genNum);
+  const dirs = allDirs.slice(0, Math.max(0, allDirs.length - RECENT_PROTECTED_COUNT));
   for (const dir of dirs) {
     const currentTotal = await countDirLines(paths.lineage);
     if (currentTotal <= LINEAGE_MAX_LINES)
@@ -9998,7 +10012,7 @@ class GenerationManager {
     const genDirName = `${state.id}-${goalSlug}`;
     const genDir = this.paths.generationDir(genDirName);
     await mkdir5(genDir, { recursive: true });
-    const lifeEntries = await readdir5(this.paths.life);
+    const lifeEntries = await readdir6(this.paths.life);
     for (const entry of lifeEntries) {
       if (/^\d{2}-[a-z]+(?:-[a-z]+)*\.md$/.test(entry)) {
         await rename(join7(this.paths.life, entry), join7(genDir, entry));
@@ -10007,13 +10021,13 @@ class GenerationManager {
     const backlogDir = join7(genDir, "backlog");
     await mkdir5(backlogDir, { recursive: true });
     try {
-      const backlogEntries = await readdir5(this.paths.backlog);
+      const backlogEntries = await readdir6(this.paths.backlog);
       for (const entry of backlogEntries) {
         await rename(join7(this.paths.backlog, entry), join7(backlogDir, entry));
       }
     } catch {}
     try {
-      const mutEntries = await readdir5(this.paths.mutations);
+      const mutEntries = await readdir6(this.paths.mutations);
       if (mutEntries.length > 0) {
         const mutDir = join7(genDir, "mutations");
         await mkdir5(mutDir, { recursive: true });
@@ -10031,7 +10045,7 @@ class GenerationManager {
   }
   async listCompleted() {
     try {
-      const entries = await readdir5(this.paths.lineage);
+      const entries = await readdir6(this.paths.lineage);
       return entries.filter((e) => e.startsWith("gen-")).sort();
     } catch {
       return [];
@@ -10133,7 +10147,7 @@ async function fixProject(projectRoot) {
 
 // src/cli/index.ts
 import { join as join8 } from "path";
-program.name("reap").description("REAP — Recursive Evolutionary Autonomous Pipeline").version("0.2.1");
+program.name("reap").description("REAP — Recursive Evolutionary Autonomous Pipeline").version("0.3.0");
 program.command("init").description("Initialize a new REAP project (Genesis)").argument("[project-name]", "Project name (defaults to current directory name)").option("-m, --mode <mode>", "Entry mode: greenfield, migration, adoption", "greenfield").option("-p, --preset <preset>", "Bootstrap with a genome preset (e.g., bun-hono-react)").action(async (projectName, options) => {
   try {
     const cwd = process.cwd();

package/dist/templates/commands/reap.back.md

@@ -45,10 +45,18 @@ description: "REAP Back — Return to a previous lifecycle stage"
    - **Affected**: [affected subsequent artifacts]
    ```
 
-### Hook Execution
-7. Read `.reap/config.yml` — if `hooks.onRegression` is defined, execute each hook in order:
-   - If hook has `command`: run the shell command
-   - If hook has `prompt`: follow the prompt instructions (AI agent executes the described task)
+### Hook Execution (Regression)
+7. Scan `.reap/hooks/` for files matching `onRegression.*`
+   - For each matched file (sorted by `order` from frontmatter, then alphabetically):
+     1. Read the frontmatter (`condition`, `order`)
+     2. Evaluate `condition` by running `.reap/hooks/conditions/{condition}.sh` (exit 0 = met, non-zero = skip):
+        - If `condition` is absent: treat as `always`
+        - If the condition script doesn't exist: warn and skip the hook
+        - Default conditions: `always`, `has-code-changes`, `version-bumped`
+        - Users can add custom conditions by placing scripts in `.reap/hooks/conditions/`
+     3. Execute based on file extension:
+        - `.md`: read the file content (after frontmatter) as AI prompt and follow the instructions
+        - `.sh`: run as shell script in the project root directory
 
 ## Completion
 - "Returned to [stage] stage. Proceed with `/reap.[stage]`."

package/dist/templates/commands/reap.completion.md

@@ -71,6 +71,39 @@ Do NOT finalize Genome changes without running Validation Commands.
     - **If called standalone**: Show the modified genome/environment content to the human and get approval. Do NOT finalize changes until the human approves.
 16. For each applied `type: genome-change` and `type: environment-change` backlog item, update its frontmatter to `status: consumed` and add `consumedBy: gen-XXX`
 
+### Phase 5: Hook Suggestion
+
+17. Read the last 3 completed generations from `.reap/lineage/` (sorted by gen number, most recent first)
+    - For each: read `03-implementation.md` (Implementation Notes) and `05-completion.md` (Retrospective)
+    - Identify **manual tasks that were repeated across 2+ generations**
+    - Examples: docs update, lint fix, dependency sync, test data setup, specific file regeneration
+18. If a repeated pattern is found, engage the human with a step-by-step confirmation:
+    a. **Describe the pattern**: "최근 N개 generation에서 '[작업 설명]'이 반복적으로 수행되었습니다."
+    b. **Ask if it should be a hook**: "이 작업을 hook으로 자동화할까요? (yes/no)"
+    c. If yes, ask **event**: "어떤 이벤트에서 실행할까요?"
+       - `onGenerationComplete` — generation 완료 후
+       - `onStageTransition` — stage 전환 시
+       - `onGenerationStart` — generation 시작 시
+       - `onRegression` — stage 회귀 시
+    d. Ask **condition**: "실행 조건은 무엇인가요?"
+       - `always` — 항상
+       - `has-code-changes` — src/ 변경이 있을 때
+       - `version-bumped` — version bump가 있을 때
+       - Custom — 유저가 직접 기술
+    e. Ask **hook name**: "hook 이름을 지어주세요 (예: lint-fix, docs-sync)"
+    f. **Preview**: 생성될 hook 파일 내용을 보여주고 확인:
+       ```
+       파일: .reap/hooks/{event}.{name}.md
+       ---
+       condition: {condition}
+       order: 50
+       ---
+       {작업 내용}
+       ```
+    g. 유저 확인 후 `.reap/hooks/{event}.{name}.md` 생성
+19. 반복 패턴이 없으면 skip — "반복 패턴이 감지되지 않았습니다."
+20. **Limit**: 한 번에 최대 2개까지만 제안 (과부하 방지)
+
 ## Self-Verification
 Before saving the artifact, verify:
 - [ ] Are lessons concrete and applicable to the next generation? (No vague "do better next time")

package/dist/templates/commands/reap.help.md

@@ -82,5 +82,5 @@ For command-name topics: read `reap.{name}.md` from the same directory as this f
 - **regression** — `/reap.back`: 이전 stage 회귀. timeline + artifact에 Regression 섹션 기록.
 - **minor-fix** — 5분 이내, 설계 변경 없는 수정. stage 전환 없이 현재 artifact에 기록.
 - **compression** — 10,000줄 + 5세대 이상 시 lineage 자동 압축. L1(40줄), L2(60줄).
-- **author** — HyeonIL Choi (At C to D). hichoi@c-d.cc / https://reap.cc / https://github.com/c-d-cc/reap
+- **author** — HyeonIL Choi. Email: hichoi@c-d.cc / Homepage: https://c-d.cc / LinkedIn: https://www.linkedin.com/in/hichoi-dev / GitHub: https://github.com/casamia918
 - **start** / **objective** / **planning** / **implementation** / **validation** / **completion** / **next** / **back** / **sync** / **status** / **update** / **help** — Read `reap.{name}.md` from same directory, explain.

package/dist/templates/commands/reap.next.md

@@ -21,9 +21,17 @@ description: "REAP Next — Advance to the next lifecycle stage"
 - Immediately create the next stage's artifact file from template (empty, ready to fill)
 
 ### Hook Execution (Stage Transition)
-- Read `.reap/config.yml` — if `hooks.onStageTransition` is defined, execute each hook in order:
-  - If hook has `command`: run the shell command
-  - If hook has `prompt`: follow the prompt instructions (AI agent executes the described task)
+- Scan `.reap/hooks/` for files matching `onStageTransition.*`
+- For each matched file (sorted by `order` from frontmatter, then alphabetically):
+  1. Read the frontmatter (`condition`, `order`)
+  2. Evaluate `condition` by running `.reap/hooks/conditions/{condition}.sh` (exit 0 = met, non-zero = skip):
+     - If `condition` is absent: treat as `always`
+     - If the condition script doesn't exist: warn and skip the hook
+     - Default conditions: `always`, `has-code-changes`, `version-bumped`
+     - Users can add custom conditions by placing scripts in `.reap/hooks/conditions/`
+  3. Execute based on file extension:
+     - `.md`: read the file content (after frontmatter) as AI prompt and follow the instructions
+     - `.sh`: run as shell script in the project root directory
 
 ### When Advancing from Completion (Archiving)
 - Add the current timestamp to `completedAt` in `current.yml`
@@ -43,10 +51,18 @@ description: "REAP Next — Advance to the next lifecycle stage"
   - If there are no code changes (REAP-only generation), use `chore(reap): [goal summary]`
 
 ### Hook Execution (Generation Complete)
-- Read `.reap/config.yml` — if `hooks.onGenerationComplete` is defined, execute each hook in order:
-  - If hook has `command`: run the shell command
-  - If hook has `prompt`: follow the prompt instructions (AI agent executes the described task)
-  - Note: hooks run AFTER the commit, so any changes from hooks will be uncommitted
+- Scan `.reap/hooks/` for files matching `onGenerationComplete.*`
+- For each matched file (sorted by `order` from frontmatter, then alphabetically):
+  1. Read the frontmatter (`condition`, `order`)
+  2. Evaluate `condition` by running `.reap/hooks/conditions/{condition}.sh` (exit 0 = met, non-zero = skip):
+     - If `condition` is absent: treat as `always`
+     - If the condition script doesn't exist: warn and skip the hook
+     - Default conditions: `always`, `has-code-changes`, `version-bumped`
+     - Users can add custom conditions by placing scripts in `.reap/hooks/conditions/`
+  3. Execute based on file extension:
+     - `.md`: read the file content (after frontmatter) as AI prompt and follow the instructions
+     - `.sh`: run as shell script in the project root directory
+- Note: hooks run AFTER the commit, so any changes from hooks will be uncommitted
 
 ## Completion
 - If archived: "Generation [id] complete and archived. Run `/reap.start` to begin a new generation."

package/dist/templates/commands/reap.start.md

@@ -35,10 +35,18 @@ description: "REAP Start — Start a new Generation"
    ```
 5. Immediately create `.reap/life/01-objective.md` from the artifact template with the Goal section filled in
 
-### Hook Execution
-6. Read `.reap/config.yml` — if `hooks.onGenerationStart` is defined, execute each hook in order:
-   - If hook has `command`: run the shell command
-   - If hook has `prompt`: follow the prompt instructions (AI agent executes the described task)
+### Hook Execution (Generation Start)
+6. Scan `.reap/hooks/` for files matching `onGenerationStart.*`
+   - For each matched file (sorted by `order` from frontmatter, then alphabetically):
+     1. Read the frontmatter (`condition`, `order`)
+     2. Evaluate `condition` by running `.reap/hooks/conditions/{condition}.sh` (exit 0 = met, non-zero = skip):
+        - If `condition` is absent: treat as `always`
+        - If the condition script doesn't exist: warn and skip the hook
+        - Default conditions: `always`, `has-code-changes`, `version-bumped`
+        - Users can add custom conditions by placing scripts in `.reap/hooks/conditions/`
+     3. Execute based on file extension:
+        - `.md`: read the file content (after frontmatter) as AI prompt and follow the instructions
+        - `.sh`: run as shell script in the project root directory
 
 ## Completion
 - "Generation gen-XXX started. Proceed with `/reap.objective` to define the goal, or `/reap.evolve` to run the full lifecycle."

package/dist/templates/conditions/always.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+# Always true — hook always executes
+exit 0

package/dist/templates/conditions/has-code-changes.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# True if src/ files were changed in the most recent commit
+# Exit 0 = condition met, Exit 1 = condition not met
+last_commit=$(git log -1 --format="%H" 2>/dev/null)
+if [ -z "$last_commit" ]; then
+  exit 1
+fi
+changes=$(git diff-tree --no-commit-id --name-only -r "$last_commit" -- src/ 2>/dev/null)
+if [ -n "$changes" ]; then
+  exit 0
+else
+  exit 1
+fi

package/dist/templates/conditions/version-bumped.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# True if package.json version differs from the last git tag
+# Exit 0 = version was bumped, Exit 1 = same version
+last_tag=$(git describe --tags --abbrev=0 2>/dev/null)
+if [ -z "$last_tag" ]; then
+  exit 1
+fi
+tag_version="${last_tag#v}"
+pkg_version=$(node -e "console.log(require('./package.json').version)" 2>/dev/null)
+if [ -z "$pkg_version" ]; then
+  exit 1
+fi
+if [ "$tag_version" != "$pkg_version" ]; then
+  exit 0
+else
+  exit 1
+fi

package/dist/templates/genome/constraints.md

@@ -3,7 +3,7 @@
 > **Writing principle**: This file should be a **map** of ~100 lines or fewer.
 > Record not only the "what" but also the "why" of each technical choice.
 > Agents refer to this file when making technical decisions.
-> Modified only during the Birth phase.
+> Modified only during the Completion stage.
 
 ## Tech Stack
 

package/dist/templates/genome/conventions.md

@@ -4,7 +4,7 @@
 > Write rules to be mechanically verifiable whenever possible.
 > Instead of "write good code", describe it as "functions must not exceed 50 lines".
 > Prioritize rules that can be enforced via linters/tests over documentation-only rules.
-> Modified only during the Birth phase.
+> Modified only during the Completion stage.
 
 ## Code Style
 

package/dist/templates/genome/principles.md

@@ -3,7 +3,7 @@
 > **Writing principle**: This file should be a **map** of ~100 lines or fewer.
 > Write at a level where agents can act immediately.
 > Separate detailed content into files under `domain/`.
-> Modified only during the Birth phase.
+> Modified only during the Completion stage.
 
 ## Core Beliefs
 
@@ -22,10 +22,6 @@ Agents should be able to reason about "why it is this way".
 |----|----------|-----------|------|
 | | | | |
 
-## Layer Map
+## Source Map
 
-Describe the project's layer structure and dependency direction.
-Specify which layers can depend on which layers.
-Write detailed layer rules in files under `domain/`.
-
-- (Describe layer structure here)
+→ See `genome/source-map.md` for C4 Container + Component level Mermaid diagrams.

package/dist/templates/genome/source-map.md

@@ -0,0 +1,22 @@
+# Source Map
+
+> C4 Container + Component level project structure map.
+> Agents reference this before exploring code to quickly identify entry points.
+> Line limit: ~150 lines (adaptive to codebase size).
+> Modified only during the Completion stage.
+
+## C4 Context
+
+(Describe the system context: users, external systems, and relationships)
+
+## C4 Container
+
+(Describe containers: applications, data stores, and their interactions)
+
+## Core Components
+
+(Describe key components within each container)
+
+## Data Flow
+
+(Describe how data flows through the system)

package/dist/templates/hooks/reap-guide.md

@@ -92,7 +92,7 @@ Regression reason is recorded as a `## Regression` section in the target stage's
 Trivial issues (typos, lint errors, etc.) are fixed directly in the current stage without a stage transition and recorded in the artifact. Judgment criterion: resolvable within 5 minutes without design changes.
 
 ### Lineage Compression
-As generations accumulate, lineage grows. Auto-compression triggers when total exceeds 10,000 lines + 5 or more generations:
+As generations accumulate, lineage grows. Auto-compression triggers when total exceeds 5,000 lines + 5 or more generations (most recent 3 generations are protected):
 - **Level 1**: Generation folder → single .md (40 lines). Only goal + result + notable items preserved.
 - **Level 2**: 5 Level 1 entries → epoch .md (60 lines). Only key flow preserved.
 
@@ -100,26 +100,34 @@ Compression runs automatically during `/reap.next` (archiving after completion).
 
 ## REAP Hooks
 
-Projects can define hooks in `.reap/config.yml` to run commands or prompts at lifecycle events:
-
-```yaml
-hooks:
-  onGenerationStart:
-    - command: "echo 'Generation started'"
-  onStageTransition:
-    - command: "echo 'Stage changed'"
-  onGenerationComplete:
-    - command: "reap update"
-    - prompt: "Check if README needs updating based on this generation's changes."
-  onRegression:
-    - command: "echo 'Regressed'"
+Hooks are defined as individual files in `.reap/hooks/` with the naming convention `{event}.{name}.{md|sh}`:
+
+```
+.reap/hooks/
+├── onGenerationComplete.version-bump.md
+├── onGenerationComplete.reap-update.sh
+├── onGenerationComplete.docs-update.md
+└── onGenerationComplete.release-notes.md
 ```
 
-Each hook entry supports two types:
-- `command` — Run a shell command in the project root directory
-- `prompt` — AI agent instruction. The agent reads and executes the described task.
+File naming: `{event}.{name}.{extension}`
+- Event: onGenerationStart, onStageTransition, onGenerationComplete, onRegression
+- Extension: `.md` (AI prompt) or `.sh` (shell script)
+
+Frontmatter (`.md` files) or comment headers (`.sh` files):
+- `condition`: name of a script in `.reap/hooks/conditions/` (default: `always`)
+- `order`: execution order within the same event (default: 50, lower runs first)
+
+### Conditions
 
-Only one of `command` or `prompt` should be set per entry.
+Conditions are executable scripts in `.reap/hooks/conditions/`. Exit code 0 = condition met, non-zero = skip.
+
+Default conditions (installed by `reap init`):
+- `always.sh` — always true
+- `has-code-changes.sh` — true if src/ files were changed in the last commit
+- `version-bumped.sh` — true if package.json version ≠ last git tag
+
+Custom conditions: add any `.sh` script to `.reap/hooks/conditions/`. The hook's `condition` field matches the filename (without `.sh`).
 
 | Event | Trigger |
 |-------|---------|
@@ -128,7 +136,11 @@ Only one of `command` or `prompt` should be set per entry.
 | `onGenerationComplete` | After `/reap.next` archives a completed generation (after commit) |
 | `onRegression` | After `/reap.back` returns to a previous stage |
 
-Hooks are executed by the AI agent.
+Hooks are executed by the AI agent by scanning `.reap/hooks/` for files matching the current event.
+
+## Multi-Agent Support
+
+REAP supports multiple AI agents simultaneously through the AgentAdapter abstraction. Currently supported: **Claude Code** and **OpenCode**. Detected agents are listed in `.reap/config.yml` under the `agents` field (managed by `reap init` / `reap update`). Slash commands and session hooks are installed to each detected agent's configuration directory.
 
 ## Role Separation