@canivel/ralph 0.2.0 → 0.2.3

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

package/.agents/ralph/references/GUARDRAILS.md

@@ -1,174 +1,174 @@
-# Guardrails Reference ("Signs")
-
-This document explains how to create and use guardrails in Ralph.
-
-## The Signs Metaphor
-
-From Geoffrey Huntley:
-
-> "Ralph is very good at making playgrounds, but he comes home bruised because he fell off the slide, so one then tunes Ralph by adding a sign next to the slide saying 'SLIDE DOWN, DON'T JUMP, LOOK AROUND,' and Ralph is more likely to look and see the sign."
-
-Signs are explicit instructions added to prevent known failure modes.
-
-## Anatomy of a Sign
-
-```markdown
-### Sign: [Descriptive Name]
-- **Trigger**: When this situation occurs
-- **Instruction**: What to do instead
-- **Added after**: When/why this was added
-- **Example**: Concrete example if helpful
-```
-
-## Types of Signs
-
-### 1. Preventive Signs
-
-Stop problems before they happen:
-
-```markdown
-### Sign: Validate Before Trust
-- **Trigger**: When receiving external input
-- **Instruction**: Always validate and sanitize input before using it
-- **Added after**: Iteration 3 - SQL injection vulnerability
-```
-
-### 2. Corrective Signs
-
-Fix recurring mistakes:
-
-```markdown
-### Sign: Check Return Values
-- **Trigger**: When calling functions that can fail
-- **Instruction**: Always check return values and handle errors
-- **Added after**: Iteration 7 - Null pointer exception
-```
-
-### 3. Process Signs
-
-Enforce good practices:
-
-```markdown
-### Sign: Test Before Commit
-- **Trigger**: Before committing changes
-- **Instruction**: Run the test suite and ensure all tests pass
-- **Added after**: Iteration 2 - Broken tests committed
-```
-
-### 4. Architecture Signs
-
-Guide design decisions:
-
-```markdown
-### Sign: Single Responsibility
-- **Trigger**: When a function grows beyond 50 lines
-- **Instruction**: Consider splitting into smaller, focused functions
-- **Added after**: Iteration 12 - Unmaintainable god function
-```
-
-## When to Add Signs
-
-Add a sign when:
-
-1. **The same mistake happens twice** - Once is learning, twice is a pattern
-2. **A subtle bug is found** - Prevent future occurrences
-3. **A best practice is violated** - Reinforce good habits
-4. **Context-specific knowledge is needed** - Project-specific conventions
-
-## Sign Lifecycle
-
-### Creation
-
-```markdown
-### Sign: [New Sign]
-- **Trigger**: [When it applies]
-- **Instruction**: [What to do]
-- **Added after**: Iteration N - [What happened]
-```
-
-### Refinement
-
-If a sign isn't working:
-- Make the trigger more specific
-- Make the instruction clearer
-- Add examples
-
-### Retirement
-
-Signs can be removed when:
-- The underlying issue is fixed at a deeper level
-- The sign is no longer relevant
-- The sign is causing more problems than it solves
-
-## Example Signs Library
-
-### Security
-
-```markdown
-### Sign: Sanitize All Input
-- **Trigger**: Any user-provided data
-- **Instruction**: Use parameterized queries, escape HTML, validate types
-- **Example**: `db.query("SELECT * FROM users WHERE id = ?", [userId])`
-```
-
-### Error Handling
-
-```markdown
-### Sign: Graceful Degradation
-- **Trigger**: External service calls
-- **Instruction**: Always have a fallback for when services are unavailable
-- **Example**: Cache results, provide default values, show friendly errors
-```
-
-### Testing
-
-```markdown
-### Sign: Test the Unhappy Path
-- **Trigger**: Writing tests for new functionality
-- **Instruction**: Include tests for error cases, edge cases, and invalid input
-```
-
-### Code Quality
-
-```markdown
-### Sign: Explain Why, Not What
-- **Trigger**: Writing comments
-- **Instruction**: Comments should explain reasoning, not describe obvious code
-- **Example**: `// Using retry because API is flaky under load` not `// Call the API`
-```
-
-## Automatic Sign Detection
-
-The Ralph hooks can automatically detect some patterns and suggest signs:
-
-- **Thrashing**: Same file edited many times → "Step back and reconsider"
-- **Repeated errors**: Same test failing → "Check the test assumptions"
-- **Large changes**: Big diffs → "Consider smaller increments"
-
-These are logged in `.ralph/failures.md` and can be promoted to guardrails.
-
-## Using Signs Effectively
-
-### Do
-
-- Keep signs concise and actionable
-- Include concrete examples
-- Update signs when they're not working
-- Remove outdated signs
-
-### Don't
-
-- Add signs for every minor issue
-- Make signs too vague ("be careful")
-- Ignore signs that keep triggering
-- Let the guardrails file become overwhelming
-
-## Integration with Ralph
-
-Signs are:
-1. Stored in `.ralph/guardrails.md`
-2. Injected into context at the start of each iteration
-3. Referenced when relevant situations arise
-4. Updated based on observed failures
-
-The goal is a self-improving system where each failure makes future iterations smarter.
+# Guardrails Reference ("Signs")
+
+This document explains how to create and use guardrails in Ralph.
+
+## The Signs Metaphor
+
+From Geoffrey Huntley:
+
+> "Ralph is very good at making playgrounds, but he comes home bruised because he fell off the slide, so one then tunes Ralph by adding a sign next to the slide saying 'SLIDE DOWN, DON'T JUMP, LOOK AROUND,' and Ralph is more likely to look and see the sign."
+
+Signs are explicit instructions added to prevent known failure modes.
+
+## Anatomy of a Sign
+
+```markdown
+### Sign: [Descriptive Name]
+- **Trigger**: When this situation occurs
+- **Instruction**: What to do instead
+- **Added after**: When/why this was added
+- **Example**: Concrete example if helpful
+```
+
+## Types of Signs
+
+### 1. Preventive Signs
+
+Stop problems before they happen:
+
+```markdown
+### Sign: Validate Before Trust
+- **Trigger**: When receiving external input
+- **Instruction**: Always validate and sanitize input before using it
+- **Added after**: Iteration 3 - SQL injection vulnerability
+```
+
+### 2. Corrective Signs
+
+Fix recurring mistakes:
+
+```markdown
+### Sign: Check Return Values
+- **Trigger**: When calling functions that can fail
+- **Instruction**: Always check return values and handle errors
+- **Added after**: Iteration 7 - Null pointer exception
+```
+
+### 3. Process Signs
+
+Enforce good practices:
+
+```markdown
+### Sign: Test Before Commit
+- **Trigger**: Before committing changes
+- **Instruction**: Run the test suite and ensure all tests pass
+- **Added after**: Iteration 2 - Broken tests committed
+```
+
+### 4. Architecture Signs
+
+Guide design decisions:
+
+```markdown
+### Sign: Single Responsibility
+- **Trigger**: When a function grows beyond 50 lines
+- **Instruction**: Consider splitting into smaller, focused functions
+- **Added after**: Iteration 12 - Unmaintainable god function
+```
+
+## When to Add Signs
+
+Add a sign when:
+
+1. **The same mistake happens twice** - Once is learning, twice is a pattern
+2. **A subtle bug is found** - Prevent future occurrences
+3. **A best practice is violated** - Reinforce good habits
+4. **Context-specific knowledge is needed** - Project-specific conventions
+
+## Sign Lifecycle
+
+### Creation
+
+```markdown
+### Sign: [New Sign]
+- **Trigger**: [When it applies]
+- **Instruction**: [What to do]
+- **Added after**: Iteration N - [What happened]
+```
+
+### Refinement
+
+If a sign isn't working:
+- Make the trigger more specific
+- Make the instruction clearer
+- Add examples
+
+### Retirement
+
+Signs can be removed when:
+- The underlying issue is fixed at a deeper level
+- The sign is no longer relevant
+- The sign is causing more problems than it solves
+
+## Example Signs Library
+
+### Security
+
+```markdown
+### Sign: Sanitize All Input
+- **Trigger**: Any user-provided data
+- **Instruction**: Use parameterized queries, escape HTML, validate types
+- **Example**: `db.query("SELECT * FROM users WHERE id = ?", [userId])`
+```
+
+### Error Handling
+
+```markdown
+### Sign: Graceful Degradation
+- **Trigger**: External service calls
+- **Instruction**: Always have a fallback for when services are unavailable
+- **Example**: Cache results, provide default values, show friendly errors
+```
+
+### Testing
+
+```markdown
+### Sign: Test the Unhappy Path
+- **Trigger**: Writing tests for new functionality
+- **Instruction**: Include tests for error cases, edge cases, and invalid input
+```
+
+### Code Quality
+
+```markdown
+### Sign: Explain Why, Not What
+- **Trigger**: Writing comments
+- **Instruction**: Comments should explain reasoning, not describe obvious code
+- **Example**: `// Using retry because API is flaky under load` not `// Call the API`
+```
+
+## Automatic Sign Detection
+
+The Ralph hooks can automatically detect some patterns and suggest signs:
+
+- **Thrashing**: Same file edited many times → "Step back and reconsider"
+- **Repeated errors**: Same test failing → "Check the test assumptions"
+- **Large changes**: Big diffs → "Consider smaller increments"
+
+These are logged in `.ralph/failures.md` and can be promoted to guardrails.
+
+## Using Signs Effectively
+
+### Do
+
+- Keep signs concise and actionable
+- Include concrete examples
+- Update signs when they're not working
+- Remove outdated signs
+
+### Don't
+
+- Add signs for every minor issue
+- Make signs too vague ("be careful")
+- Ignore signs that keep triggering
+- Let the guardrails file become overwhelming
+
+## Integration with Ralph
+
+Signs are:
+1. Stored in `.ralph/guardrails.md`
+2. Injected into context at the start of each iteration
+3. Referenced when relevant situations arise
+4. Updated based on observed failures
+
+The goal is a self-improving system where each failure makes future iterations smarter.

package/AGENTS.md

@@ -1,20 +1,20 @@
-# AGENTS
-
-Keep this file short. It is always loaded into context.
-
-## Build & test
-- No build step.
-- Tests (dry-run): `npm test`
-- Fast real agent check: `npm run test:ping`
-- Full real loop: `npm run test:real`
-
-## CLI shape
-- CLI entry: `bin/ralph`
-- Templates: `.agents/ralph/` (copied to repos on install)
-- State/logs: `.ralph/` (local only)
-- Skills: `skills/`
-- Tests: `tests/`
-- Docs/examples: `README.md`, `examples/`
-
-## Quirks / Guardrails
-**Add any common quirks guiderails here as needed**
+# AGENTS
+
+Keep this file short. It is always loaded into context.
+
+## Build & test
+- No build step.
+- Tests (dry-run): `npm test`
+- Fast real agent check: `npm run test:ping`
+- Full real loop: `npm run test:real`
+
+## CLI shape
+- CLI entry: `bin/ralph`
+- Templates: `.agents/ralph/` (copied to repos on install)
+- State/logs: `.ralph/` (local only)
+- Skills: `skills/`
+- Tests: `tests/`
+- Docs/examples: `README.md`, `examples/`
+
+## Quirks / Guardrails
+**Add any common quirks guiderails here as needed**