@c-d-cc/reap 0.1.0

package/dist/templates/artifacts/01-objective.md

@@ -0,0 +1,29 @@
+# Objective
+
+## Goal
+
+
+## Completion Criteria
+
+
+## Requirements
+
+### Functional Requirements
+
+
+### Non-Functional Requirements
+
+
+## Scope
+- **Related Genome Areas**:
+- **Expected Change Scope**:
+- **Exclusions**:
+
+## Genome Reference
+
+
+## Backlog (Genome Modifications Discovered)
+None
+
+## Background
+

package/dist/templates/artifacts/02-planning.md

@@ -0,0 +1,14 @@
+# Planning
+
+## Summary
+
+
+## Technical Context
+- **Tech Stack**:
+- **Constraints**:
+
+## Tasks
+
+
+## Dependencies
+

package/dist/templates/artifacts/03-implementation.md

@@ -0,0 +1,19 @@
+# Implementation Log
+
+## Completed Tasks
+| Task | Description | Completed |
+|------|-------------|-----------|
+| | | |
+
+## Deferred Tasks
+| Task | Description | Reason | Related Backlog |
+|------|-------------|--------|-----------------|
+| | | | |
+
+## Genome-Change Backlog Items
+| Backlog File | Target | Description |
+|-------------|--------|-------------|
+| | | |
+
+## Implementation Notes
+[Notable items, decisions made, and reference material from implementation]

package/dist/templates/artifacts/04-validation.md

@@ -0,0 +1,20 @@
+# Validation Report
+
+## Result: pending
+
+## Completion Criteria Check
+| Criterion | Result | Notes |
+|-----------|--------|-------|
+
+## Test Results
+
+
+## Deferred Items
+
+
+## Minor Fixes (Fixed Directly in This Stage)
+| File | Change | Reason |
+|------|--------|--------|
+
+## Issues Discovered
+

package/dist/templates/artifacts/05-completion.md

@@ -0,0 +1,47 @@
+# Completion
+
+## Summary
+- **Goal**:
+- **Period**: [startedAt] ~ [completedAt]
+- **Genome Version**: v[N] → v[N+1]
+- **Result**: [pass/partial/fail from validation]
+- **Key Changes**:
+
+## Retrospective
+
+### Lessons Learned
+#### What Went Well
+
+
+#### Areas for Improvement
+
+
+### Genome Change Proposals
+| Target File | Change Description | Reason |
+|-------------|-------------------|--------|
+
+### Deferred Task Handoff
+| Task | Description | Related Backlog | Backlog File |
+|------|-------------|-----------------|-------------|
+
+### Next Generation Backlog
+
+
+---
+
+## Genome Changelog
+
+### Genome-Change Backlog Applied
+| Backlog File | Target | Change Description | Applied |
+|-------------|--------|-------------------|---------|
+
+### Retrospective Proposals Applied
+| Target File | Change Description | Applied |
+|-------------|-------------------|---------|
+
+### Genome Version
+- Before:
+- After:
+
+### Modified Genome Files
+

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

@@ -0,0 +1,54 @@
+---
+description: "REAP Back — Return to a previous lifecycle stage"
+---
+
+# Return to Previous Stage
+
+## Gate (Preconditions)
+- Read `.reap/life/current.yml`
+- If no active Generation: ERROR — "No active Generation." **STOP**
+- If current stage is `objective` (first stage): ERROR — "Already at the first stage. Cannot go back." **STOP**
+
+## Steps
+
+1. Determine target stage:
+   - `/reap.back` alone: go to the immediately previous stage
+   - `/reap.back [stage]`: go directly to the specified stage
+   - Stage order: objective → planning → implementation → validation → completion
+   - Only backward transitions are allowed
+2. Ask the human for the reason for regression
+3. Collect regression reason and reference info:
+   - **reason**: why we are going back
+   - **refs**: related files/locations (artifact sections, source code locations)
+4. Modify `current.yml`:
+   - Change `stage` to the target stage
+   - Add a regression entry to `timeline`:
+     ```yaml
+     - stage: [target stage]
+       at: [current ISO 8601]
+       from: [original stage]
+       reason: [regression reason]
+       refs:
+         - [ref 1]
+         - [ref 2]
+     ```
+5. Artifact handling:
+   - **Before the target stage**: preserve
+   - **Target stage**: overwrite on re-entry (implementation only: append)
+   - **After the target stage**: preserve, overwrite on re-entry
+6. Record the regression reason at the top of the target stage artifact as a `## Regression` section:
+   ```markdown
+   ## Regression
+   - **From**: [original stage]
+   - **Reason**: [regression reason]
+   - **Refs**: [reference list]
+   - **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)
+
+## Completion
+- "Returned to [stage] stage. Proceed with `/reap.[stage]`."

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

@@ -0,0 +1,96 @@
+---
+description: "REAP Completion — Retrospect, evolve the Genome, and finalize the Generation"
+---
+
+# Completion
+
+<HARD-GATE>
+Do NOT apply Genome changes without human confirmation — UNLESS called from `/reap.evolve` (Autonomous Override active).
+Do NOT finalize Genome changes without running Validation Commands.
+</HARD-GATE>
+
+## Gate (Preconditions)
+- Read `.reap/life/current.yml` and verify that stage is `completion`
+- Verify that `.reap/life/04-validation.md` exists
+- If not met: ERROR — state the reason and **STOP**
+
+## Context (Generation Info)
+- Read `.reap/life/current.yml` for the current generation info (id, goal, genomeVersion)
+
+## Steps
+
+### Phase 0: Summary
+
+1. Fill the `## Summary` section of `05-completion.md` using data from `current.yml` and `04-validation.md`:
+   - **Goal**: from `current.yml` goal
+   - **Period**: from `current.yml` startedAt ~ completedAt
+   - **Genome Version**: from `current.yml` genomeVersion (v[N] → v[N+1])
+   - **Result**: from `04-validation.md` result (pass/partial/fail)
+   - **Key Changes**: brief one-line summary of what was delivered
+
+### Phase 1: Retrospective
+
+2. Read all `type: genome-change` and `type: environment-change` items from `.reap/life/backlog/`
+3. Read the deferred task list from `.reap/life/03-implementation.md`
+4. Compile lessons learned from this generation
+   - **Limit**: Maximum 5 lessons. Keep only the most impactful ones.
+5. Compile genome changes to apply (which genome file to modify and how)
+
+### Phase 2: Garbage Collection (Codebase Health)
+
+6. Referencing the Enforced Rules in `.reap/genome/conventions.md`, check codebase consistency:
+   - Check whether new convention violations have been introduced
+   - Identify technical debt incurred during implementation
+7. For each piece of technical debt found, add it to `.reap/life/backlog/`:
+   ```markdown
+   ---
+   type: task
+   status: pending
+   ---
+   # [Title]
+   [Description]
+   ```
+
+### Phase 3: Backlog Cleanup
+
+8. Add deferred tasks to `.reap/life/backlog/` as `type: task`
+9. Also add other next-generation goal candidates to the backlog
+10. Finalize the retrospective with the human
+
+### Phase 4: Genome Application
+
+11. Read `type: genome-change` and `type: environment-change` items from `.reap/life/backlog/`
+12. Apply genome-change items to the corresponding files in `.reap/genome/`:
+    - **Map principle**: Each genome file should be **~100 lines or less**
+    - If exceeding 100 lines, extract into files under `domain/`
+    - **When writing domain/ files, follow the guide in `~/.reap/templates/domain-guide.md`**
+13. Apply environment-change items to the corresponding files in `.reap/environment/`
+14. **Verify**: Run the Validation Commands from constraints.md to confirm genome changes do not conflict with existing code
+15. **Human confirmation**:
+    - **If called from `/reap.evolve`** (Autonomous Override active): Apply genome changes automatically after Validation Commands pass. Do NOT pause for human confirmation.
+    - **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`
+
+## Self-Verification
+Before saving the artifact, verify:
+- [ ] Are lessons concrete and applicable to the next generation? (No vague "do better next time")
+- [ ] Have genome changes been confirmed by the human?
+- [ ] Do Validation Commands still pass after the changes?
+- [ ] Have deferred tasks been added to the backlog?
+
+❌ Bad lesson: "We should write more tests"
+✅ Good lesson: "SSE streaming responses are difficult to unit test, so prioritize integration tests"
+
+## Artifact Generation (Progressive Recording)
+- **Language**: Write all artifact content in the user's configured language (see REAP Guide § Language).
+- **Immediately upon entering this stage**: Read `~/.reap/templates/05-completion.md` and create `.reap/life/05-completion.md` with empty sections ready to fill
+- **Update incrementally as each phase completes**:
+  - After Phase 1 (Retrospective) → fill in Lessons Learned, Genome Change Proposals
+  - After Phase 2 (Garbage Collection) → update with any tech debt findings
+  - After Phase 3 (Backlog Cleanup) → fill in Deferred Task Handoff, Next Generation Backlog
+  - After Phase 4 (Genome Application) → fill in Genome Changelog sections
+- The artifact should reflect the current state of completion work at all times
+
+## Completion
+- **If called from `/reap.evolve`** (Autonomous Override active): Proceed automatically to `/reap.next`.
+- **If called standalone**: "Finalize the generation with `/reap.next`. Lineage archiving will be performed automatically."

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

@@ -0,0 +1,48 @@
+---
+description: "REAP Evolve — Run the full lifecycle for a Generation"
+---
+
+# Evolve (Full Lifecycle)
+
+Run the entire Generation lifecycle from start to finish, interactively with the human.
+
+<HARD-GATE>
+NEVER modify `current.yml` directly to change the stage. ALWAYS use `/reap.next` to advance and `/reap.back` to regress.
+Direct modification skips artifact creation and breaks the lifecycle. This is non-negotiable.
+</HARD-GATE>
+
+## Gate (Preconditions)
+- Read `.reap/life/current.yml`
+- If no active Generation exists: run `/reap.start` first to create one
+- If an active Generation exists: resume from the current stage
+
+## Autonomous Override
+When `/reap.evolve` calls each stage command, the following overrides apply:
+- **Skip routine human confirmations**: Do NOT pause to show artifacts and ask for approval at the end of each stage. Proceed autonomously.
+- **Skip environment/genome interactive setup questions**: Use existing data, fill in what you can, skip what's empty.
+- **STOP only when genuinely blocked**: ambiguous goal with multiple valid interpretations, uncertain technical decision with significant trade-offs, conflicts in the genome, or unexpected errors.
+- **Escalation sections still apply**: If a stage's Escalation rules trigger, STOP and ask.
+- This override does NOT apply when stages are invoked standalone (e.g., user runs `/reap.objective` directly).
+
+## Lifecycle Loop
+
+Execute the following loop until the generation is complete:
+
+1. Read `current.yml` to determine the current stage
+2. Execute the corresponding stage command:
+   - `objective` → `/reap.objective`
+   - `planning` → `/reap.planning`
+   - `implementation` → `/reap.implementation`
+   - `validation` → `/reap.validation`
+   - `completion` → `/reap.completion`
+3. When the stage command completes, run `/reap.next` to advance
+4. If `/reap.next` archives the generation (from completion), the loop ends
+5. Otherwise, return to step 1
+
+## Handling Issues
+- If validation fails: `/reap.back` to return to implementation (or earlier), then resume the loop
+- If the human wants to pause: stop the loop, the generation state is preserved in `current.yml`
+- If the human wants to skip a stage: advance with `/reap.next` without running the stage command
+
+## Completion
+- "Generation [id] completed. All artifacts archived to lineage."

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

@@ -0,0 +1,61 @@
+---
+description: "REAP Help — Contextual help based on current state"
+---
+
+# Help
+
+Provide contextual help to the user based on the current REAP state.
+
+## Steps
+
+### 1. Read Current State
+- Read `.reap/life/current.yml`
+- Read `.reap/config.yml` for strict mode status
+
+### 2. Contextual Guidance
+
+**If no active Generation:**
+- "No active Generation. To get started:"
+- "  `/reap.start` — Start a new Generation with a goal"
+- "  `/reap.evolve` — Start and run the full lifecycle autonomously"
+- If there are items in `.reap/life/backlog/`, mention them
+
+**If active Generation exists:**
+- Show current generation ID, goal, and stage
+- Show the next action: "Current stage is [stage]. Run `/reap.[stage]` to proceed, or `/reap.next` to advance."
+- If in implementation stage with strict mode, note the planning scope restriction
+
+### 3. Command Reference
+
+Show available slash commands with brief descriptions:
+
+| Command | Description |
+|---------|-------------|
+| `/reap.start` | Start a new Generation |
+| `/reap.evolve` | Run the full lifecycle autonomously |
+| `/reap.objective` | Define goal + requirements |
+| `/reap.planning` | Task decomposition + plan |
+| `/reap.implementation` | Code implementation |
+| `/reap.validation` | Run tests + verify |
+| `/reap.completion` | Retrospective + genome updates |
+| `/reap.next` | Advance to the next stage |
+| `/reap.back` | Return to a previous stage |
+| `/reap.status` | Show current state |
+| `/reap.sync` | Synchronize Genome with source code |
+| `/reap.help` | This help |
+
+### 4. Topic Help (Optional)
+
+If the user provides a topic (e.g., `/reap.help workflow`), provide deeper explanation:
+
+- **workflow** — Explain the 5-stage lifecycle in detail
+- **commands** — Explain each slash command with examples
+- **strict** — Explain strict mode, how to enable/disable, and escape hatch
+- **genome** — Explain genome structure, immutability principle, and how to modify
+- **backlog** — Explain backlog types, status management, and archiving rules
+
+### 5. Configuration Info
+
+- Show strict mode status (enabled/disabled)
+- Show project name and entry mode
+- Show total completed generations

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

@@ -0,0 +1,102 @@
+---
+description: "REAP Implementation — Implement code through AI+Human collaboration"
+---
+
+# Implementation
+
+<HARD-GATE>
+Do NOT write code without the task list from 02-planning.md.
+Do NOT write code that violates the Genome (conventions.md, constraints.md).
+Do NOT modify the Genome directly — if you discover an issue, record it in the backlog.
+Do NOT modify the Environment directly — if you discover a change, record it in the backlog.
+</HARD-GATE>
+
+## Gate (Preconditions)
+- Read `.reap/life/current.yml` and verify that stage is `implementation`
+- Verify that `.reap/life/02-planning.md` exists
+- Check git working tree status (`git status`)
+  - If there are uncommitted changes that overlap with files this generation will modify:
+    - Ask the user: "There are uncommitted changes. Would you like to commit them before proceeding? (yes/no/show diff)"
+    - If yes: help the user commit the changes, then proceed
+    - If no: proceed with caution, noting the existing changes
+    - If show diff: show the diff, then ask again
+  - If there are uncommitted changes in unrelated files: proceed normally
+  - If the working tree is clean: proceed normally
+- If not met: ERROR — state the reason and **STOP**
+
+## Context (Generation Info)
+- Read `.reap/life/current.yml` for the current generation info (id, goal, genomeVersion)
+- Read `.reap/genome/conventions.md` — rules to reference continuously during implementation
+- Read `.reap/genome/constraints.md` — technical constraints
+
+## Re-entry Check
+- If `.reap/life/03-implementation.md` already exists, this is a **re-entry due to regression**
+- Read the existing log; if a `## Regression` section exists, understand the regression reason
+- On regression re-entry, **append** to the existing log (preserve existing completion records)
+
+## Steps
+
+### 1. Load Task List
+- Read the task list from `.reap/life/02-planning.md`
+- If `03-implementation.md` already exists, read it (preserve existing records)
+- Identify incomplete (`[ ]`) tasks
+
+### 2. Sequential Implementation
+- Implement starting from the first incomplete task, in order
+- **After EACH task completion**, immediately add it to the Completed Tasks table in `03-implementation.md`
+- **After EACH deferred task decision**, immediately add it to the Deferred Tasks table
+- **After EACH genome issue discovery**, immediately add it to the Genome-Change Backlog Items table
+- Do NOT batch-write the log at the end. Update it as you go.
+- **Strictly** follow the rules in conventions.md
+- **Strictly** follow the technical constraints in constraints.md
+
+### 3. When Genome/Environment Changes Are Discovered
+- If you discover something that must be implemented differently from the spec:
+  a. Record it in `.reap/life/backlog/`:
+     ```markdown
+     ---
+     type: genome-change
+     status: pending
+     target: genome/[relevant file]
+     ---
+     # [Title]
+     [What is different and how it should be changed]
+     ```
+  b. Mark tasks that depend on this change as `[deferred]` in `02-planning.md`
+  c. Record the reason for deferral
+- **Do NOT modify Genome or Environment files directly. This is non-negotiable.**
+
+### 3b. When Out-of-Scope Issues Are Discovered
+- If you discover issues outside the current generation's scope (outdated tests, tech debt, broken code unrelated to current tasks, etc.):
+  a. Record it in `.reap/life/backlog/`:
+     ```markdown
+     ---
+     type: task
+     status: pending
+     ---
+     # [Title]
+     [Description of the issue and what needs to be done]
+     ```
+  b. Do NOT fix it in the current generation unless the human explicitly approves
+  c. Record it in `03-implementation.md` under "Genome-Change Backlog Items" or "Implementation Notes"
+
+### 4. Completion Marking
+- Mark completed tasks as `[x]` in `02-planning.md`
+
+## Escalation
+In the following situations, **STOP and ask the human**:
+- When task requirements are unclear
+- When an architectural decision is needed but not covered in the plan
+- When a conflict arises with existing code
+- When the scope turns out to be significantly larger than expected
+
+## Artifact Generation (Progressive Recording)
+- **Language**: Write all artifact content in the user's configured language (see REAP Guide § Language).
+- **Immediately upon entering this stage**: Read `~/.reap/templates/03-implementation.md` and create `.reap/life/03-implementation.md` with empty tables ready to fill (or preserve existing content on re-entry)
+- **Update continuously during Step 2**: After each task, deferral, or discovery, update the artifact immediately
+- By the time all tasks are done, the artifact should already be complete — no separate "generation" step is needed
+- Add Implementation Notes at the end summarizing notable decisions
+
+## Completion
+- "Proceed to the Validation stage with `/reap.next`."
+- "If issues are found during Validation, you can return with `/reap.back`."

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

@@ -0,0 +1,53 @@
+---
+description: "REAP Next — Advance to the next lifecycle stage"
+---
+
+# Next Stage
+
+## Gate (Preconditions)
+- Read `.reap/life/current.yml`
+- If no active Generation: ERROR — "No active Generation. Run `/reap.start` first." **STOP**
+
+## Steps
+
+### Stage Transition
+- Stage order: objective → planning → implementation → validation → completion
+- Update the `stage` in `current.yml` to the next stage
+- Add an entry to `timeline`:
+  ```yaml
+  - stage: [next stage]
+    at: [current ISO 8601]
+  ```
+- 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)
+
+### When Advancing from Completion (Archiving)
+- Add the current timestamp to `completedAt` in `current.yml`
+- Move artifact files (`01-*.md` through `05-*.md`) from `.reap/life/` to `.reap/lineage/[gen-id]-[goal-slug]/`
+  - Goal slug: lowercase, non-alphanumeric/hangul replaced with `-`, max 30 chars
+- Process backlog files from `.reap/life/backlog/`:
+  - Create `.reap/lineage/[gen-id]-[goal-slug]/backlog/` directory
+  - Files with `status: consumed` → move to `.reap/lineage/[gen-id]-[goal-slug]/backlog/`
+  - Files with `status: pending` or no status field → copy to `.reap/lineage/[gen-id]-[goal-slug]/backlog/` for record, then carry over to new `.reap/life/backlog/`
+- Clear `current.yml` (write empty content)
+- Recreate `.reap/life/backlog/` directory (with carried-over pending items already in place)
+- **Commit all changes** (code + `.reap/` artifacts together):
+  - Stage all changed files: code changes from this generation + `.reap/` directory
+  - Commit message format: `feat(gen-NNN): [generation goal summary]`
+  - Use `feat` for feature generations, `fix` for bugfix generations, `chore` for maintenance
+  - Include both code and REAP artifacts in the same commit
+  - 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
+
+## Completion
+- If archived: "Generation [id] complete and archived. Run `/reap.start` to begin a new generation."
+- Otherwise: "Advanced to [next stage]. Proceed with `/reap.[next stage]`."