@canivel/ralph 0.2.1 → 0.2.3

package/.agents/ralph/PROMPT_build.md

@@ -1,126 +1,126 @@
-# Build
-
-You are an autonomous coding agent. Your task is to complete the work for exactly one story and record the outcome.
-
-## Paths
-- PRD: {{PRD_PATH}}
-- AGENTS (optional): {{AGENTS_PATH}}
-- Progress Log: {{PROGRESS_PATH}}
-- Guardrails: {{GUARDRAILS_PATH}}
-- Guardrails Reference: {{GUARDRAILS_REF}}
-- Context Reference: {{CONTEXT_REF}}
-- Errors Log: {{ERRORS_LOG_PATH}}
-- Activity Log: {{ACTIVITY_LOG_PATH}}
-- Activity Logger: {{ACTIVITY_CMD}}
-- No-commit: {{NO_COMMIT}}
-- Repo Root: {{REPO_ROOT}}
-- Run ID: {{RUN_ID}}
-- Iteration: {{ITERATION}}
-- Run Log: {{RUN_LOG_PATH}}
-- Run Summary: {{RUN_META_PATH}}
-
-## Global Quality Gates (apply to every story)
-{{QUALITY_GATES}}
-
-## Selected Story (Do not change scope)
-ID: {{STORY_ID}}
-Title: {{STORY_TITLE}}
-
-Story details:
-{{STORY_BLOCK}}
-
-If the story details are empty or missing, STOP and report that the PRD story format could not be parsed.
-
-## Rules (Non-Negotiable)
-- Implement **only** the work required to complete the selected story.
-- Complete all tasks associated with this story (and only this story).
-- Do NOT ask the user questions.
-- Do NOT change unrelated code.
-- Do NOT assume something is unimplemented — confirm by reading code.
-- Implement completely; no placeholders or stubs.
-- If No-commit is true, do NOT commit or push changes.
-- Do NOT edit the PRD JSON (status is handled by the loop).
-- All changes made during the run must be committed (including updates to progress/logs).
- - Before committing, perform a final **security**, **performance**, and **regression** review of your changes.
-
-## Your Task (Do this in order)
-1. Read {{GUARDRAILS_PATH}} before any code changes.
-2. Read {{ERRORS_LOG_PATH}} for repeated failures to avoid.
-3. Read {{PRD_PATH}} for global context (do not edit).
-4. Fully audit and read all necessary files to understand the task end-to-end before implementing. Do not assume missing functionality.
-5. If {{AGENTS_PATH}} exists, follow its build/test instructions.
-6. Implement only the tasks that belong to {{STORY_ID}}.
-7. Run verification commands listed in the story, the global quality gates, and in {{AGENTS_PATH}} (if required).
-8. If the project has a build or dev workflow, run what applies:
-   - Build step (e.g., `npm run build`) if defined.
-   - Dev server (e.g., `npm run dev`, `wrangler dev`) if it is the normal validation path.
-   - Confirm no runtime/build errors in the console.
-9. Perform a brief audit before committing:
-   - **Security:** check for obvious vulnerabilities or unsafe handling introduced by your changes.
-   - **Performance:** check for avoidable regressions (extra queries, heavy loops, unnecessary re-renders).
-   - **Regression:** verify existing behavior that could be impacted still works.
-10. If No-commit is false, commit changes using the `$commit` skill.
-    - Stage everything: `git add -A`
-    - Confirm a clean working tree after commit: `git status --porcelain` should be empty.
-    - After committing, capture the commit hash and subject using:
-      `git show -s --format="%h %s" HEAD`.
-11. Append a progress entry to {{PROGRESS_PATH}} with run/commit/test details (format below).
-    If No-commit is true, skip committing and note it in the progress entry.
-
-## Progress Entry Format (Append Only)
-```
-## [Date/Time] - {{STORY_ID}}: {{STORY_TITLE}}
-Thread: [codex exec session id if available, otherwise leave blank]
-Run: {{RUN_ID}} (iteration {{ITERATION}})
-Run log: {{RUN_LOG_PATH}}
-Run summary: {{RUN_META_PATH}}
-- Guardrails reviewed: yes
-- No-commit run: {{NO_COMMIT}}
-- Commit: <hash> <subject> (or `none` + reason)
-- Post-commit status: `clean` or list remaining files
-- Verification:
-  - Command: <exact command> -> PASS/FAIL
-  - Command: <exact command> -> PASS/FAIL
-- Files changed:
-  - <file path>
-  - <file path>
-- What was implemented
-- **Learnings for future iterations:**
-  - Patterns discovered
-  - Gotchas encountered
-  - Useful context
----
-```
-
-## Completion Signal
-Only output the completion signal when the **selected story** is fully complete and verified.
-When the selected story is complete, output:
-<promise>COMPLETE</promise>
-
-Otherwise, end normally without the signal.
-
-## Additional Guardrails
-- When authoring documentation, capture the why (tests + implementation intent).
-- If you learn how to run/build/test the project, update {{AGENTS_PATH}} briefly (operational only).
-- Keep AGENTS operational only; progress notes belong in {{PROGRESS_PATH}}.
-- If you hit repeated errors, log them in {{ERRORS_LOG_PATH}} and add a Sign to {{GUARDRAILS_PATH}} using {{GUARDRAILS_REF}} as the template.
-
-## Activity Logging (Required)
-Log major actions to {{ACTIVITY_LOG_PATH}} using the helper:
-```
-{{ACTIVITY_CMD}} "message"
-```
-Log at least:
-- Start of work on the story
-- After major code changes
-- After tests/verification
-- After updating progress log
-
-## Browser Testing (Required for Frontend Stories)
-If the selected story changes UI, you MUST verify it in the browser:
-1. Load the `dev-browser` skill.
-2. Navigate to the relevant page.
-3. Verify the UI changes work as expected.
-4. Take a screenshot if helpful for the progress log.
-
-A frontend story is NOT complete until browser verification passes.
+# Build
+
+You are an autonomous coding agent. Your task is to complete the work for exactly one story and record the outcome.
+
+## Paths
+- PRD: {{PRD_PATH}}
+- AGENTS (optional): {{AGENTS_PATH}}
+- Progress Log: {{PROGRESS_PATH}}
+- Guardrails: {{GUARDRAILS_PATH}}
+- Guardrails Reference: {{GUARDRAILS_REF}}
+- Context Reference: {{CONTEXT_REF}}
+- Errors Log: {{ERRORS_LOG_PATH}}
+- Activity Log: {{ACTIVITY_LOG_PATH}}
+- Activity Logger: {{ACTIVITY_CMD}}
+- No-commit: {{NO_COMMIT}}
+- Repo Root: {{REPO_ROOT}}
+- Run ID: {{RUN_ID}}
+- Iteration: {{ITERATION}}
+- Run Log: {{RUN_LOG_PATH}}
+- Run Summary: {{RUN_META_PATH}}
+
+## Global Quality Gates (apply to every story)
+{{QUALITY_GATES}}
+
+## Selected Story (Do not change scope)
+ID: {{STORY_ID}}
+Title: {{STORY_TITLE}}
+
+Story details:
+{{STORY_BLOCK}}
+
+If the story details are empty or missing, STOP and report that the PRD story format could not be parsed.
+
+## Rules (Non-Negotiable)
+- Implement **only** the work required to complete the selected story.
+- Complete all tasks associated with this story (and only this story).
+- Do NOT ask the user questions.
+- Do NOT change unrelated code.
+- Do NOT assume something is unimplemented — confirm by reading code.
+- Implement completely; no placeholders or stubs.
+- If No-commit is true, do NOT commit or push changes.
+- Do NOT edit the PRD JSON (status is handled by the loop).
+- All changes made during the run must be committed (including updates to progress/logs).
+ - Before committing, perform a final **security**, **performance**, and **regression** review of your changes.
+
+## Your Task (Do this in order)
+1. Read {{GUARDRAILS_PATH}} before any code changes.
+2. Read {{ERRORS_LOG_PATH}} for repeated failures to avoid.
+3. Read {{PRD_PATH}} for global context (do not edit).
+4. Fully audit and read all necessary files to understand the task end-to-end before implementing. Do not assume missing functionality.
+5. If {{AGENTS_PATH}} exists, follow its build/test instructions.
+6. Implement only the tasks that belong to {{STORY_ID}}.
+7. Run verification commands listed in the story, the global quality gates, and in {{AGENTS_PATH}} (if required).
+8. If the project has a build or dev workflow, run what applies:
+   - Build step (e.g., `npm run build`) if defined.
+   - Dev server (e.g., `npm run dev`, `wrangler dev`) if it is the normal validation path.
+   - Confirm no runtime/build errors in the console.
+9. Perform a brief audit before committing:
+   - **Security:** check for obvious vulnerabilities or unsafe handling introduced by your changes.
+   - **Performance:** check for avoidable regressions (extra queries, heavy loops, unnecessary re-renders).
+   - **Regression:** verify existing behavior that could be impacted still works.
+10. If No-commit is false, commit changes using the `$commit` skill.
+    - Stage everything: `git add -A`
+    - Confirm a clean working tree after commit: `git status --porcelain` should be empty.
+    - After committing, capture the commit hash and subject using:
+      `git show -s --format="%h %s" HEAD`.
+11. Append a progress entry to {{PROGRESS_PATH}} with run/commit/test details (format below).
+    If No-commit is true, skip committing and note it in the progress entry.
+
+## Progress Entry Format (Append Only)
+```
+## [Date/Time] - {{STORY_ID}}: {{STORY_TITLE}}
+Thread: [codex exec session id if available, otherwise leave blank]
+Run: {{RUN_ID}} (iteration {{ITERATION}})
+Run log: {{RUN_LOG_PATH}}
+Run summary: {{RUN_META_PATH}}
+- Guardrails reviewed: yes
+- No-commit run: {{NO_COMMIT}}
+- Commit: <hash> <subject> (or `none` + reason)
+- Post-commit status: `clean` or list remaining files
+- Verification:
+  - Command: <exact command> -> PASS/FAIL
+  - Command: <exact command> -> PASS/FAIL
+- Files changed:
+  - <file path>
+  - <file path>
+- What was implemented
+- **Learnings for future iterations:**
+  - Patterns discovered
+  - Gotchas encountered
+  - Useful context
+---
+```
+
+## Completion Signal
+Only output the completion signal when the **selected story** is fully complete and verified.
+When the selected story is complete, output:
+<promise>COMPLETE</promise>
+
+Otherwise, end normally without the signal.
+
+## Additional Guardrails
+- When authoring documentation, capture the why (tests + implementation intent).
+- If you learn how to run/build/test the project, update {{AGENTS_PATH}} briefly (operational only).
+- Keep AGENTS operational only; progress notes belong in {{PROGRESS_PATH}}.
+- If you hit repeated errors, log them in {{ERRORS_LOG_PATH}} and add a Sign to {{GUARDRAILS_PATH}} using {{GUARDRAILS_REF}} as the template.
+
+## Activity Logging (Required)
+Log major actions to {{ACTIVITY_LOG_PATH}} using the helper:
+```
+{{ACTIVITY_CMD}} "message"
+```
+Log at least:
+- Start of work on the story
+- After major code changes
+- After tests/verification
+- After updating progress log
+
+## Browser Testing (Required for Frontend Stories)
+If the selected story changes UI, you MUST verify it in the browser:
+1. Load the `dev-browser` skill.
+2. Navigate to the relevant page.
+3. Verify the UI changes work as expected.
+4. Take a screenshot if helpful for the progress log.
+
+A frontend story is NOT complete until browser verification passes.

package/.agents/ralph/config.sh

@@ -1,25 +1,25 @@
-# Optional Ralph config overrides.
-# All paths are relative to repo root unless absolute.
-# Uncomment and edit as needed.
-
-# PRD_PATH=".agents/tasks/prd.json"
-# PROGRESS_PATH=".ralph/progress.md"
-# GUARDRAILS_PATH=".ralph/guardrails.md"
-# ERRORS_LOG_PATH=".ralph/errors.log"
-# ACTIVITY_LOG_PATH=".ralph/activity.log"
-# TMP_DIR=".ralph/.tmp"
-# RUNS_DIR=".ralph/runs"
-# GUARDRAILS_REF=".agents/ralph/references/GUARDRAILS.md"
-# CONTEXT_REF=".agents/ralph/references/CONTEXT_ENGINEERING.md"
-# ACTIVITY_CMD=".agents/ralph/log-activity.sh"
-# AGENT_CMD defaults are defined in agents.sh. Override here if needed.
-# AGENT_CMD="codex exec --yolo --skip-git-repo-check -"
-# PRD_AGENT_CMD defaults are defined in agents.sh (interactive).
-# PRD_AGENT_CMD="codex --yolo --skip-git-repo-check {prompt}"
-# AGENT_CMD="claude -p --dangerously-skip-permissions \"\$(cat {prompt})\""
-# AGENT_CMD="droid exec --skip-permissions-unsafe -f {prompt}"
-# AGENTS_PATH="AGENTS.md"
-# PROMPT_BUILD=".agents/ralph/PROMPT_build.md"
-# NO_COMMIT=false
-# MAX_ITERATIONS=25
-# STALE_SECONDS=0
+# Optional Ralph config overrides.
+# All paths are relative to repo root unless absolute.
+# Uncomment and edit as needed.
+
+# PRD_PATH=".agents/tasks/prd.json"
+# PROGRESS_PATH=".ralph/progress.md"
+# GUARDRAILS_PATH=".ralph/guardrails.md"
+# ERRORS_LOG_PATH=".ralph/errors.log"
+# ACTIVITY_LOG_PATH=".ralph/activity.log"
+# TMP_DIR=".ralph/.tmp"
+# RUNS_DIR=".ralph/runs"
+# GUARDRAILS_REF=".agents/ralph/references/GUARDRAILS.md"
+# CONTEXT_REF=".agents/ralph/references/CONTEXT_ENGINEERING.md"
+# ACTIVITY_CMD=".agents/ralph/log-activity.sh"
+# AGENT_CMD defaults are defined in agents.sh. Override here if needed.
+# AGENT_CMD="codex exec --yolo --skip-git-repo-check -"
+# PRD_AGENT_CMD defaults are defined in agents.sh (interactive).
+# PRD_AGENT_CMD="codex --yolo --skip-git-repo-check {prompt}"
+# AGENT_CMD="claude -p --dangerously-skip-permissions \"\$(cat {prompt})\""
+# AGENT_CMD="droid exec --skip-permissions-unsafe -f {prompt}"
+# AGENTS_PATH="AGENTS.md"
+# PROMPT_BUILD=".agents/ralph/PROMPT_build.md"
+# NO_COMMIT=false
+# MAX_ITERATIONS=25
+# STALE_SECONDS=0

package/.agents/ralph/log-activity.sh

@@ -1,15 +1,15 @@
-#!/bin/bash
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-ROOT_DIR="$(cd "${SCRIPT_DIR}/../.." && pwd)"
-ACTIVITY_LOG="$ROOT_DIR/.ralph/activity.log"
-
-if [ $# -lt 1 ]; then
-  echo "Usage: $0 \"message\""
-  exit 1
-fi
-
-mkdir -p "$(dirname "$ACTIVITY_LOG")"
-TS=$(date '+%Y-%m-%d %H:%M:%S')
-echo "[$TS] $*" >> "$ACTIVITY_LOG"
+#!/bin/bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+ACTIVITY_LOG="$ROOT_DIR/.ralph/activity.log"
+
+if [ $# -lt 1 ]; then
+  echo "Usage: $0 \"message\""
+  exit 1
+fi
+
+mkdir -p "$(dirname "$ACTIVITY_LOG")"
+TS=$(date '+%Y-%m-%d %H:%M:%S')
+echo "[$TS] $*" >> "$ACTIVITY_LOG"

package/.agents/ralph/references/CONTEXT_ENGINEERING.md

@@ -1,126 +1,126 @@
-# Context Engineering Reference
-
-This document explains the malloc/free metaphor for LLM context management that underlies the Ralph technique.
-
-## The malloc() Metaphor
-
-In traditional programming:
-- `malloc()` allocates memory
-- `free()` releases memory
-- Memory leaks occur when you allocate without freeing
-
-In LLM context:
-- Reading files, receiving responses, tool outputs = `malloc()`
-- **There is no `free()`** - context cannot be released
-- The only way to "free" is to start a new conversation
-
-## Why This Matters
-
-### Context Pollution
-
-When you work on multiple unrelated tasks in the same context:
-
-```
-Task 1: Build authentication → context contains auth code, JWT docs, security patterns
-Task 2: Build UI components → context now ALSO contains auth stuff
-
-Result: LLM might suggest auth-related patterns when building UI
-        or mix concerns inappropriately
-```
-
-### Autoregressive Failure
-
-LLMs predict the next token based on ALL context. When context contains:
-- Unrelated information
-- Failed attempts
-- Mixed concerns
-
-The model can "spiral" into wrong territory, generating increasingly off-base responses.
-
-### The Gutter Metaphor
-
-> "If the bowling ball is in the gutter, there's no saving it."
-
-Once context is polluted with failed attempts or mixed concerns, the model will keep referencing that pollution. Starting fresh is often faster than trying to correct course.
-
-## Context Health Indicators
-
-### 🟢 Healthy Context
-- Single focused task
-- Relevant files only
-- Clear progress
-- Under 60% capacity
-
-### 🟡 Warning Signs
-- Multiple unrelated topics discussed
-- Several failed attempts in history
-- Approaching 80% capacity
-- Repeated similar errors
-
-### 🔴 Critical / Gutter
-- Mixed concerns throughout
-- Circular failure patterns
-- Over 90% capacity
-- Model suggesting irrelevant solutions
-
-## Best Practices
-
-### 1. One Task Per Context
-
-Don't ask "fix the auth bug AND add the new feature". Do them in separate conversations.
-
-### 2. Fresh Start on Topic Change
-
-Finished auth? Start a new conversation for the next feature.
-
-### 3. Don't Redline
-
-Stay under 80% of context capacity. Quality degrades as you approach limits.
-
-### 4. Recognize the Gutter
-
-If you're seeing:
-- Same error 3+ times
-- Solutions that don't match the problem
-- Circular suggestions
-
-Start fresh. Your progress is in the files.
-
-### 5. State in Files, Not Context
-
-Write progress to files. The next conversation can read them. Context is ephemeral; files are permanent.
-
-## Ralph's Approach
-
-The original Ralph technique (`while :; do cat PROMPT.md | agent ; done`) naturally implements these principles:
-
-1. **Each iteration is a fresh process** - Context is freed
-2. **State persists in files** - Progress survives context resets
-3. **Same prompt each time** - Focused, single-task context
-4. **Failures inform guardrails** - Learning without context pollution
-
-This Cursor implementation aims to bring these benefits while working within Cursor's session model.
-
-## Measuring Context
-
-Rough estimates:
-- 1 token ≈ 4 characters
-- Average code file: 500-2000 tokens
-- Large file: 5000+ tokens
-- Conversation history: 100-500 tokens per exchange
-
-Track allocations in `.ralph/context-log.md` to stay aware.
-
-## When to Start Fresh
-
-**Definitely start fresh when:**
-- Switching to unrelated task
-- Context over 90% full
-- Same error 3+ times
-- Model suggestions are off-topic
-
-**Consider starting fresh when:**
-- Context over 70% full
-- Significant topic shift within task
-- Feeling "stuck"
-- Multiple failed approaches in history
+# Context Engineering Reference
+
+This document explains the malloc/free metaphor for LLM context management that underlies the Ralph technique.
+
+## The malloc() Metaphor
+
+In traditional programming:
+- `malloc()` allocates memory
+- `free()` releases memory
+- Memory leaks occur when you allocate without freeing
+
+In LLM context:
+- Reading files, receiving responses, tool outputs = `malloc()`
+- **There is no `free()`** - context cannot be released
+- The only way to "free" is to start a new conversation
+
+## Why This Matters
+
+### Context Pollution
+
+When you work on multiple unrelated tasks in the same context:
+
+```
+Task 1: Build authentication → context contains auth code, JWT docs, security patterns
+Task 2: Build UI components → context now ALSO contains auth stuff
+
+Result: LLM might suggest auth-related patterns when building UI
+        or mix concerns inappropriately
+```
+
+### Autoregressive Failure
+
+LLMs predict the next token based on ALL context. When context contains:
+- Unrelated information
+- Failed attempts
+- Mixed concerns
+
+The model can "spiral" into wrong territory, generating increasingly off-base responses.
+
+### The Gutter Metaphor
+
+> "If the bowling ball is in the gutter, there's no saving it."
+
+Once context is polluted with failed attempts or mixed concerns, the model will keep referencing that pollution. Starting fresh is often faster than trying to correct course.
+
+## Context Health Indicators
+
+### 🟢 Healthy Context
+- Single focused task
+- Relevant files only
+- Clear progress
+- Under 60% capacity
+
+### 🟡 Warning Signs
+- Multiple unrelated topics discussed
+- Several failed attempts in history
+- Approaching 80% capacity
+- Repeated similar errors
+
+### 🔴 Critical / Gutter
+- Mixed concerns throughout
+- Circular failure patterns
+- Over 90% capacity
+- Model suggesting irrelevant solutions
+
+## Best Practices
+
+### 1. One Task Per Context
+
+Don't ask "fix the auth bug AND add the new feature". Do them in separate conversations.
+
+### 2. Fresh Start on Topic Change
+
+Finished auth? Start a new conversation for the next feature.
+
+### 3. Don't Redline
+
+Stay under 80% of context capacity. Quality degrades as you approach limits.
+
+### 4. Recognize the Gutter
+
+If you're seeing:
+- Same error 3+ times
+- Solutions that don't match the problem
+- Circular suggestions
+
+Start fresh. Your progress is in the files.
+
+### 5. State in Files, Not Context
+
+Write progress to files. The next conversation can read them. Context is ephemeral; files are permanent.
+
+## Ralph's Approach
+
+The original Ralph technique (`while :; do cat PROMPT.md | agent ; done`) naturally implements these principles:
+
+1. **Each iteration is a fresh process** - Context is freed
+2. **State persists in files** - Progress survives context resets
+3. **Same prompt each time** - Focused, single-task context
+4. **Failures inform guardrails** - Learning without context pollution
+
+This Cursor implementation aims to bring these benefits while working within Cursor's session model.
+
+## Measuring Context
+
+Rough estimates:
+- 1 token ≈ 4 characters
+- Average code file: 500-2000 tokens
+- Large file: 5000+ tokens
+- Conversation history: 100-500 tokens per exchange
+
+Track allocations in `.ralph/context-log.md` to stay aware.
+
+## When to Start Fresh
+
+**Definitely start fresh when:**
+- Switching to unrelated task
+- Context over 90% full
+- Same error 3+ times
+- Model suggestions are off-topic
+
+**Consider starting fresh when:**
+- Context over 70% full
+- Significant topic shift within task
+- Feeling "stuck"
+- Multiple failed approaches in history