@c-d-cc/reap 0.1.0

package/README.ko.md

@@ -0,0 +1,309 @@
+<p align="center">
+  <img src="media/logo.png" alt="REAP" width="80" height="80" />
+</p>
+
+<h1 align="center">REAP</h1>
+
+<p align="center">
+  <strong>Recursive Evolutionary Autonomous Pipeline</strong><br>
+  AI와 인간이 세대(Generation)를 거듭하며 소프트웨어를 진화시키는 개발 파이프라인.
+</p>
+
+> For English version, see [README.md](README.md).
+
+```
+Genome (설계와 지식)  →  Evolution (세대를 거친 진화)  →  Civilization (Source Code)
+```
+
+REAP은 Application의 유전 정보(Genome)를 정의하고, 각 세대에서 목표를 설정하여 구현하고, 그 과정에서 발견한 Genome 결함을 다음 단계에서 반영합니다. 세대를 거듭하며 Genome이 진화하고, Source Code(Civilization)가 성장합니다.
+
+## Why REAP?
+
+AI 에이전트와 함께 개발할 때 이런 문제를 겪어본 적 있나요?
+
+- **컨텍스트 유실** — 새 세션을 열면 에이전트가 프로젝트 맥락을 잊어버림
+- **산발적 개발** — 명확한 목표 없이 여기저기 코드를 수정
+- **설계와 코드의 괴리** — 문서는 따로, 코드는 따로 놀면서 점점 벌어짐
+- **교훈의 망각** — 삽질한 경험이 다음 작업에 반영되지 않음
+
+REAP은 **세대 기반 진화 모델**로 이 문제들을 해결합니다:
+
+- 매 세대마다 하나의 목표에 집중 (Objective → Completion)
+- AI 에이전트가 매 세션 시작 시 현재 맥락을 자동으로 인식 (SessionStart Hook)
+- 구현 중 발견한 설계 문제는 backlog에 기록, Completion에서 반영
+- 회고(Completion)에서 도출한 교훈이 Genome에 축적
+
+## 설치
+
+```bash
+# npm
+npm install -g @c-d-cc/reap
+
+# 또는 Bun
+bun install -g @c-d-cc/reap
+```
+
+> **요구사항**: [Bun](https://bun.sh) 런타임, [Claude Code](https://claude.ai/claude-code) CLI
+
+## 빠른 시작
+
+```bash
+# 1. 프로젝트 초기화
+
+# 새 프로젝트
+reap init my-project
+
+# 기존 프로젝트
+cd my-project
+reap init
+
+# 2. Claude Code에서 한 Generation 전체 실행
+claude
+> /reap.evolve "사용자 인증 구현"
+```
+
+`/reap.evolve`는 한 세대의 전체 lifecycle을 — Objective부터 Completion까지 — 사용자와 대화하며 자동으로 실행합니다. Generation 생성, 각 stage 실행, stage 간 전진을 모두 처리합니다. 일상적인 개발에서 가장 많이 사용하는 핵심 명령어입니다.
+
+더 세밀한 제어가 필요하면 각 stage를 수동으로 진행할 수도 있습니다:
+
+```bash
+> /reap.start            # 새 Generation 시작
+> /reap.objective        # 목표 + 명세 정의
+> /reap.next             # 다음 단계로 전진
+> /reap.planning         # 구현 계획
+> /reap.next
+> /reap.implementation   # AI+Human 협업 코드 구현
+> ...
+```
+
+## 생애주기 (Life Cycle)
+
+한 세대(Generation)는 5단계의 생애주기를 거칩니다:
+
+```
+Objective → Planning → Implementation ⟷ Validation → Completion
+(목표 정의)   (계획)      (구현)              (검증)      (완성)
+```
+
+| 단계 | 하는 일 | 산출물 |
+|------|---------|--------|
+| **Objective** | 목표 + 요구사항 + 수용기준 정의 | `01-objective.md` |
+| **Planning** | 태스크 분해, 구현 접근법, 의존관계 | `02-planning.md` |
+| **Implementation** | AI+Human 협업으로 코드 구현 | `03-implementation.md` |
+| **Validation** | 테스트 실행, 완료 조건 점검 | `04-validation.md` |
+| **Completion** | 회고 + Genome 변경 반영 + 아카이빙 | `05-completion.md` |
+
+## 핵심 개념
+
+### Genome
+
+Application의 유전 정보 — 아키텍처 원칙, 비즈니스 규칙, 개발 컨벤션, 기술 제약의 집합.
+
+```
+.reap/genome/
+├── principles.md      # 아키텍처 원칙/결정
+├── domain/            # 비즈니스 규칙 (모듈별)
+├── conventions.md     # 개발 규칙/컨벤션
+└── constraints.md     # 기술 제약/선택
+```
+
+**Genome 불변 원칙**: 현재 세대에서는 Genome을 직접 수정하지 않습니다. 문제를 발견하면 backlog에 기록하고, Completion 단계에서만 반영합니다.
+
+**Environment 불변 원칙**: 현재 세대에서는 Environment를 직접 수정하지 않습니다. 외부 환경 변화를 발견하면 backlog에 기록하고, Completion 단계에서 반영합니다.
+
+### Backlog
+
+`.reap/life/backlog/`에 다음에 반영할 모든 항목을 저장합니다. 각 항목은 markdown + frontmatter 형식:
+
+- `type: genome-change` — Completion에서 Genome에 반영
+- `type: environment-change` — Completion에서 Environment에 반영
+- `type: task` — 다음 Objective에서 goal 후보 (deferred 태스크, 기술 부채 등)
+
+각 항목은 `status` 필드도 가집니다:
+
+- `status: pending` — 미처리 항목 (기본값)
+- `status: consumed` — 현재 세대에서 처리 완료 (`consumedBy: gen-XXX` 필수)
+
+아카이빙 시점(`/reap.next` from Completion)에 `consumed` 항목은 lineage로 이동하고, `pending` 항목은 다음 세대 backlog로 이월됩니다.
+
+**부분 완료는 정상** — Genome 변경에 의존하는 태스크는 `[deferred]`로 마킹하고 다음 세대로 인계합니다.
+
+### 4축 구조
+
+```
+.reap/
+├── genome/        # 유전 정보 (세대를 거치며 진화)
+├── environment/   # 외부 환경 (API 문서, 인프라, 비즈니스 제약)
+├── life/          # 현재 세대의 상태와 산출물
+└── lineage/       # 완료된 세대들의 아카이브
+```
+
+## CLI 명령어
+
+| 명령어 | 설명 |
+|--------|------|
+| `reap init <name>` | 프로젝트 초기화. `.reap/` 구조 생성 |
+| `reap status` | 현재 Generation 상태 확인 |
+| `reap update` | 커맨드/템플릿/훅을 최신 버전으로 동기화 |
+| `reap fix` | `.reap/` 구조 진단 및 복구 |
+| `reap help` | CLI 명령어 + 슬래시 커맨드 + 워크플로우 요약 출력 |
+
+### 옵션
+
+```bash
+reap init my-project --mode adoption    # 기존 프로젝트에 REAP 적용
+reap init my-project --preset bun-hono-react  # 프리셋으로 Genome 초기화
+reap update --dry-run                   # 변경사항 미리보기
+```
+
+## Claude Code 연동
+
+REAP은 Claude Code의 두 가지 메커니즘으로 AI 에이전트와 통합됩니다:
+
+### Slash Commands
+
+Slash command가 `.claude/commands/`에 설치되어 전체 워크플로우를 구동합니다:
+
+| 명령어 | 설명 |
+|--------|------|
+| `/reap.start` | 새 Generation 시작 |
+| `/reap.objective` | 목표 + 요구사항 정의 |
+| `/reap.planning` | 태스크 분해 + 구현 계획 |
+| `/reap.implementation` | AI+Human 협업 코드 구현 |
+| `/reap.validation` | 테스트 실행, 완료 조건 점검 |
+| `/reap.completion` | 회고 + Genome 변경 반영 |
+| `/reap.next` | 다음 Life Cycle stage로 전진 |
+| `/reap.back` | 이전 stage로 복귀 (micro loop) |
+| `/reap.status` | 현재 Generation 상태 및 프로젝트 건강 상태 표시 |
+| `/reap.sync` | 소스 코드 기반 Genome 최신화 |
+| `/reap.help` | 현재 상태에 따른 contextual AI 도움말 (topic: workflow, commands, strict, genome, backlog) |
+| **`/reap.evolve`** | **한 Generation 전체를 처음부터 끝까지 실행 (권장)** |
+
+### SessionStart Hook
+
+매 세션 시작 시 자동으로 실행되어 AI 에이전트에게 다음을 주입합니다:
+
+- REAP 워크플로우 전체 가이드 (Genome, Life Cycle, 4축 구조 등)
+- 현재 Generation 상태 (어떤 stage인지, 다음에 뭘 해야 하는지)
+- REAP lifecycle을 따르라는 규칙
+
+이를 통해 새 세션을 열어도 에이전트가 프로젝트 맥락을 즉시 파악합니다.
+
+### Strict 모드
+
+`.reap/config.yml`에 `strict: true`를 설정하면 AI 에이전트가 REAP 워크플로우 외부에서 코드를 수정하는 것을 제한합니다:
+
+```yaml
+# .reap/config.yml
+strict: true   # 기본값: false
+```
+
+| 상황 | 동작 |
+|------|------|
+| 활성 Generation 없음 / 구현 단계 외 | 코드 수정 완전 차단 |
+| Implementation 단계 | `02-planning.md` 범위 내에서만 수정 허용 |
+| Escape hatch | 사용자가 "override", "bypass strict" 등 명시적 요청 시 허용 |
+
+Strict 모드는 기본적으로 비활성화되어 있습니다 (`strict: false`).
+
+### REAP Hooks
+
+`.reap/config.yml`에 hook을 정의하여 lifecycle 이벤트에 명령 또는 AI 프롬프트를 실행할 수 있습니다:
+
+```yaml
+hooks:
+  onGenerationStart:
+    - command: "echo 'Generation started'"
+  onStageTransition:
+    - command: "echo 'Stage changed'"
+  onGenerationComplete:
+    - command: "reap update"
+    - prompt: "이번 Generation 변경사항을 README에 반영하라."
+  onRegression:
+    - command: "echo 'Regressed'"
+```
+
+각 hook은 `command` (shell 명령) 또는 `prompt` (AI 에이전트 지시) 중 하나를 사용합니다.
+
+| 이벤트 | 트리거 |
+|--------|--------|
+| `onGenerationStart` | `/reap.start`로 새 Generation 생성 후 |
+| `onStageTransition` | `/reap.next`로 다음 stage 전진 후 |
+| `onGenerationComplete` | `/reap.next`로 완료된 Generation 아카이빙 후 |
+| `onRegression` | `/reap.back`으로 이전 stage 복귀 후 |
+
+Hook은 AI 에이전트가 프로젝트 루트 디렉토리에서 실행합니다.
+
+## `reap init` 후 프로젝트 구조
+
+```
+my-project/
+├── src/                          # Civilization (소스 코드)
+└── .reap/
+    ├── config.yml                # 프로젝트 설정
+    ├── genome/                   # 유전 정보
+    │   ├── principles.md
+    │   ├── domain/
+    │   ├── conventions.md
+    │   └── constraints.md
+    ├── environment/              # 외부 환경
+    ├── life/                     # 현재 세대
+    │   ├── current.yml
+    │   └── backlog/
+    └── lineage/                  # 완료된 세대 아카이브
+
+~/.claude/                        # 사용자 레벨 (reap init 시 설치)
+├── commands/                     # Slash commands (/reap.*)
+└── settings.json                 # SessionStart hook 등록
+```
+
+## 계보 압축 (Lineage Compression)
+
+세대가 쌓이면 lineage 디렉토리가 커집니다. REAP은 자동 2단계 압축으로 이를 관리합니다:
+
+| 레벨 | 입력 | 출력 | 최대 줄 수 | 트리거 |
+|------|------|------|-----------|--------|
+| **Level 1** | 세대 폴더 (5개 산출물) | `gen-XXX.md` | 40줄 | lineage > 10,000줄 + 5세대 이상 |
+| **Level 2** | Level 1 파일 5개 | `epoch-XXX.md` | 60줄 | Level 1이 5개 이상 |
+
+압축은 세대 완료 시 자동 실행됩니다. 압축된 파일은 목표(Objective)와 결과(Completion)를 중심으로 보존하고, 중간 과정은 특이사항만 남깁니다.
+
+## 진화 흐름 (Evolution Flow)
+
+```
+Generation #1 (Genome v1)
+  → Objective: "사용자 인증 구현"
+  → Planning → Implementation
+  → Implementation 중 OAuth2 필요 발견 → backlog에 genome-change 기록
+  → Validation (partial)
+  → Completion → 회고 + genome 반영 → Genome v2 → 아카이빙
+
+Generation #2 (Genome v2)
+  → Objective: "OAuth2 연동 + 권한 관리"
+  → 이전 세대의 deferred 태스크 + 새 목표
+  → ...
+```
+
+## 프리셋 (Presets)
+
+`reap init --preset`으로 기술 스택에 맞는 Genome 초기 설정을 적용할 수 있습니다.
+
+| 프리셋 | 스택 |
+|--------|------|
+| `bun-hono-react` | Bun + Hono + React |
+
+```bash
+reap init my-project --preset bun-hono-react
+```
+
+## 진입 모드 (Entry Modes)
+
+| 모드 | 설명 |
+|------|------|
+| `greenfield` | 새 프로젝트를 처음부터 구축 (기본값) |
+| `migration` | 기존 시스템을 참조하여 새로 구축 |
+| `adoption` | 기존 코드베이스에 REAP을 적용 |
+
+## 라이선스
+
+MIT

package/README.md

@@ -0,0 +1,308 @@
+<p align="center">
+  <img src="media/logo.png" alt="REAP" width="80" height="80" />
+</p>
+
+<h1 align="center">REAP</h1>
+
+<p align="center">
+  <strong>Recursive Evolutionary Autonomous Pipeline</strong><br>
+  A development pipeline where AI and humans evolve software across generations.
+</p>
+
+> 한국어 버전은 [README.ko.md](README.ko.md)를 참조하세요.
+
+```
+Genome (Design & Knowledge)  →  Evolution (Generational Progress)  →  Civilization (Source Code)
+```
+
+REAP defines an application's genetic information (Genome), sets objectives for each generation to implement, and feeds back any Genome defects discovered along the way into subsequent stages. As generations accumulate, the Genome evolves and the Source Code (Civilization) grows.
+
+## Why REAP?
+
+Have you ever run into these problems when developing with AI agents?
+
+- **Context loss** — The agent forgets the project context every time you start a new session
+- **Scattered development** — Code gets modified here and there with no clear goal
+- **Design–code drift** — Documentation and code diverge over time
+- **Forgotten lessons** — Hard-won insights from past struggles never carry forward
+
+REAP solves these with a **generation-based evolution model**:
+
+- Each generation focuses on a single objective (Objective → Completion)
+- The AI agent automatically picks up current context at every session start (SessionStart Hook)
+- Design issues discovered during implementation are logged in the backlog and addressed at Completion
+- Lessons drawn from retrospectives (Completion) accumulate in the Genome
+
+## Installation
+
+```bash
+# npm
+npm install -g @c-d-cc/reap
+
+# or Bun
+bun install -g @c-d-cc/reap
+```
+
+> **Requirements**: [Bun](https://bun.sh) runtime, [Claude Code](https://claude.ai/claude-code) CLI
+
+## Quick Start
+
+```bash
+# 1. Initialize the project
+
+# New project
+reap init my-project
+
+# Existing project
+cd my-project
+reap init
+
+# 2. Open Claude Code and run a full generation
+claude
+> /reap.evolve "Implement user authentication"
+```
+
+`/reap.evolve` runs the entire generation lifecycle — from Objective through Completion — interactively with you. It automatically starts a generation, executes each stage in order, and advances between them. This is the primary command you'll use for day-to-day development.
+
+You can also drive each stage manually if you need finer control:
+
+```bash
+> /reap.start            # Start a new generation
+> /reap.objective        # Define objective + spec
+> /reap.next             # Advance to the next stage
+> /reap.planning         # Create implementation plan
+> /reap.next
+> /reap.implementation   # Build with AI + human collaboration
+> ...
+```
+
+## Life Cycle
+
+Each generation goes through a five-stage life cycle:
+
+```
+Objective → Planning → Implementation ⟷ Validation → Completion
+```
+
+| Stage | What happens | Artifact |
+|-------|-------------|----------|
+| **Objective** | Define goal, requirements, and acceptance criteria | `01-objective.md` |
+| **Planning** | Break down tasks, choose approach, map dependencies | `02-planning.md` |
+| **Implementation** | Build with AI + human collaboration | `03-implementation.md` |
+| **Validation** | Run tests, verify completion criteria | `04-validation.md` |
+| **Completion** | Retrospective + apply Genome changes + archive | `05-completion.md` |
+
+## Core Concepts
+
+### Genome
+
+The application's genetic information — a collection of architecture principles, business rules, development conventions, and technical constraints.
+
+```
+.reap/genome/
+├── principles.md      # Architecture principles/decisions
+├── domain/            # Business rules (per module)
+├── conventions.md     # Development rules/conventions
+└── constraints.md     # Technical constraints/choices
+```
+
+**Genome Immutability Principle**: The Genome is never modified directly during the current generation. When an issue is found, it is recorded in the backlog and only applied at the Completion stage.
+
+**Environment Immutability Principle**: The Environment is never modified directly during the current generation. External changes are recorded in the backlog and applied at the Completion stage.
+
+### Backlog
+
+All items to be addressed next are stored in `.reap/life/backlog/`. Each item uses markdown + frontmatter format:
+
+- `type: genome-change` — Applied to the Genome at Completion
+- `type: environment-change` — Applied to the Environment at Completion
+- `type: task` — Candidate goals for the next Objective (deferred tasks, tech debt, etc.)
+
+Each item also carries a `status` field:
+
+- `status: pending` — Not yet processed (default)
+- `status: consumed` — Processed in the current generation (requires `consumedBy: gen-XXX`)
+
+At archiving time (`/reap.next` from Completion), `consumed` items move to lineage while `pending` items are carried forward to the next generation's backlog.
+
+**Partial completion is normal** — Tasks that depend on Genome changes are marked `[deferred]` and handed off to the next generation.
+
+### Four-Axis Structure
+
+```
+.reap/
+├── genome/        # Genetic information (evolves across generations)
+├── environment/   # External context (API docs, infra, business constraints)
+├── life/          # Current generation's state and artifacts
+└── lineage/       # Archive of completed generations
+```
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `reap init <name>` | Initialize project. Creates the `.reap/` structure |
+| `reap status` | Check the current generation's status |
+| `reap update` | Sync commands/templates/hooks to the latest version |
+| `reap fix` | Diagnose and repair the `.reap/` structure |
+| `reap help` | Print CLI commands, slash commands, and workflow summary |
+
+### Options
+
+```bash
+reap init my-project --mode adoption    # Apply REAP to an existing project
+reap init my-project --preset bun-hono-react  # Initialize Genome with a preset
+reap update --dry-run                   # Preview changes before applying
+```
+
+## Claude Code Integration
+
+REAP integrates with the AI agent through two Claude Code mechanisms:
+
+### Slash Commands
+
+Slash commands are installed in `.claude/commands/` and drive the entire workflow:
+
+| Command | Description |
+|---------|-------------|
+| `/reap.start` | Start a new generation |
+| `/reap.objective` | Define goal + requirements |
+| `/reap.planning` | Task decomposition + implementation plan |
+| `/reap.implementation` | Code implementation with AI + human |
+| `/reap.validation` | Run tests, verify completion criteria |
+| `/reap.completion` | Retrospective + apply Genome changes |
+| `/reap.next` | Advance to the next life cycle stage |
+| `/reap.back` | Return to a previous stage (micro loop) |
+| `/reap.status` | Show current generation state and project health |
+| `/reap.sync` | Synchronize Genome with current source code |
+| `/reap.help` | Contextual AI help based on current state (topic: workflow, commands, strict, genome, backlog) |
+| **`/reap.evolve`** | **Run an entire generation from start to finish (recommended)** |
+
+### SessionStart Hook
+
+Runs automatically at the start of every session, injecting the following into the AI agent:
+
+- The full REAP workflow guide (Genome, Life Cycle, Four-Axis Structure, etc.)
+- Current generation state (which stage you're in, what to do next)
+- Rules to follow the REAP lifecycle
+
+This ensures the agent immediately understands the project context even in a brand-new session.
+
+### Strict Mode
+
+When `strict: true` is set in `.reap/config.yml`, the AI agent is restricted from modifying code outside the REAP workflow:
+
+```yaml
+# .reap/config.yml
+strict: true   # default: false
+```
+
+| Context | Behavior |
+|---------|----------|
+| No active generation / non-implementation stage | Code modifications are fully blocked |
+| Implementation stage | Only modifications within the scope of `02-planning.md` are allowed |
+| Escape hatch | User explicitly requests "override" or "bypass strict" to allow modifications |
+
+Strict mode is disabled by default (`strict: false`).
+
+### REAP Hooks
+
+Projects can define hooks in `.reap/config.yml` to run commands or AI prompts at lifecycle events:
+
+```yaml
+hooks:
+  onGenerationStart:
+    - command: "echo 'Generation started'"
+  onStageTransition:
+    - command: "echo 'Stage changed'"
+  onGenerationComplete:
+    - command: "reap update"
+    - prompt: "Update README if this generation changed any features."
+  onRegression:
+    - command: "echo 'Regressed'"
+```
+
+Each hook supports `command` (shell) or `prompt` (AI agent instruction).
+
+| Event | Trigger |
+|-------|---------|
+| `onGenerationStart` | After `/reap.start` creates a new generation |
+| `onStageTransition` | After `/reap.next` advances to the next stage |
+| `onGenerationComplete` | After `/reap.next` archives a completed generation |
+| `onRegression` | After `/reap.back` returns to a previous stage |
+
+Hooks are executed by the AI agent in the project root directory.
+
+## Project Structure After `reap init`
+
+```
+my-project/
+├── src/                          # Civilization (your code)
+└── .reap/
+    ├── config.yml                # Project configuration
+    ├── genome/                   # Genetic information
+    │   ├── principles.md
+    │   ├── domain/
+    │   ├── conventions.md
+    │   └── constraints.md
+    ├── environment/              # External context
+    ├── life/                     # Current generation
+    │   ├── current.yml
+    │   └── backlog/
+    └── lineage/                  # Completed generation archive
+
+~/.claude/                        # User-level (installed by reap init)
+├── commands/                     # Slash commands (/reap.*)
+└── settings.json                 # SessionStart hook registration
+```
+
+## Lineage Compression
+
+As generations accumulate, the lineage directory grows. REAP manages this with automatic two-level compression:
+
+| Level | Input | Output | Max lines | Trigger |
+|-------|-------|--------|-----------|---------|
+| **Level 1** | Generation folder (5 artifacts) | `gen-XXX.md` | 40 lines | lineage > 10,000 lines + 5+ generations |
+| **Level 2** | 5 Level 1 files | `epoch-XXX.md` | 60 lines | 5+ Level 1 files |
+
+Compression runs automatically when a generation completes. Compressed files preserve objectives and completion results while retaining only notable findings from intermediate stages.
+
+## Evolution Flow
+
+```
+Generation #1 (Genome v1)
+  → Objective: "Implement user authentication"
+  → Planning → Implementation
+  → OAuth2 need discovered during Implementation → genome-change logged in backlog
+  → Validation (partial)
+  → Completion → Retrospective + genome update → Genome v2 → Archive
+
+Generation #2 (Genome v2)
+  → Objective: "OAuth2 integration + permission management"
+  → Deferred tasks from previous generation + new goals
+  → ...
+```
+
+## Presets
+
+Use `reap init --preset` to apply an initial Genome configuration tailored to your tech stack.
+
+| Preset | Stack |
+|--------|-------|
+| `bun-hono-react` | Bun + Hono + React |
+
+```bash
+reap init my-project --preset bun-hono-react
+```
+
+## Entry Modes
+
+| Mode | Description |
+|------|-------------|
+| `greenfield` | Build a new project from scratch (default) |
+| `migration` | Build anew while referencing an existing system |
+| `adoption` | Apply REAP to an existing codebase |
+
+## License
+
+MIT