@canivel/ralph 0.2.0

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

@@ -0,0 +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

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

@@ -0,0 +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.

package/AGENTS.md

@@ -0,0 +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**

package/README.md

@@ -0,0 +1,266 @@
+# Ralph
+
+![Ralph](ralph.webp)
+
+Ralph is a minimal, file-based agent loop for autonomous coding. Each iteration starts fresh, reads the same on-disk state, and commits work for one story at a time.
+
+> **Fork Note:** This is a fork of [@iannuttall/ralph](https://github.com/iannuttall/ralph) with improved agent support and first-run configuration.
+
+## What's New in This Fork
+
+- **First-run agent selection** - Prompted to choose your default agent on first use
+- **`ralph config` command** - Reconfigure your default agent anytime
+- **Improved Claude support** - Direct spawning with proper TTY handling for PRD generation
+- **Better Windows compatibility** - Fixed shell quoting issues
+- **Global config storage** - Settings persist in `~/.ralph/config.json`
+
+## How It Works
+
+Ralph treats **files and git** as memory, not the model context:
+
+- **PRD (JSON)** - Defines stories, quality gates, and status
+- **Loop** - Executes one story per iteration
+- **State** - Persists in `.ralph/` directory
+
+![Ralph architecture](diagram.svg)
+
+## Installation
+
+### From npm (recommended)
+
+```bash
+npm i -g @canivel/ralph
+```
+
+### From source
+
+```bash
+git clone https://github.com/canivel/ralph.git
+cd ralph
+npm install
+npm link
+```
+
+### Prerequisites
+
+You need at least one AI agent CLI installed:
+
+| Agent | Install Command |
+|-------|-----------------|
+| Claude | `curl -fsSL https://claude.ai/install.sh \| bash` |
+| Codex | `npm i -g @openai/codex` |
+| Droid | `curl -fsSL https://app.factory.ai/cli \| sh` |
+| OpenCode | `curl -fsSL https://opencode.ai/install.sh \| bash` |
+
+## Quick Start
+
+```bash
+# 1. Navigate to your project
+cd my-project
+
+# 2. Generate a PRD (first run prompts for agent selection)
+ralph prd "A task management app with projects and due dates"
+
+# 3. Build one story at a time
+ralph build 1
+```
+
+On first run, you'll see the agent selection prompt:
+
+```
+Ralph Configuration
+? Select your default agent
+> claude (Anthropic Claude CLI)
+  codex (OpenAI Codex CLI)
+  droid (Factory Droid CLI)
+  opencode (OpenCode CLI)
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `ralph prd ["<request>"]` | Generate a PRD JSON file via agent |
+| `ralph build [n]` | Run n build iterations (default: continuous) |
+| `ralph config` | Configure or change default agent |
+| `ralph install` | Copy templates to current repo for customization |
+| `ralph install --skills` | Install required skills (commit, dev-browser, prd) |
+| `ralph overview` | Generate human-readable overview from PRD |
+| `ralph ping` | Health check for agent connectivity |
+| `ralph log "<message>"` | Append to activity log |
+| `ralph help` | Show help message |
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--agent <name>` | Override agent (codex, claude, droid, opencode) |
+| `--prd <path>` | Override PRD file path |
+| `--out <path>` | Override PRD output path (for `prd` command) |
+| `--progress <path>` | Override progress log path |
+| `--no-commit` | Dry run without committing (for `build` command) |
+| `--force` | Force overwrite (for `install` command) |
+
+## Usage Examples
+
+### Generate a PRD
+
+```bash
+# Interactive mode - prompts for description
+ralph prd
+
+# Direct mode - pass description as argument
+ralph prd "A REST API for user authentication with JWT tokens"
+
+# Specify output path
+ralph prd --out .agents/tasks/prd-auth.json "Auth API"
+```
+
+### Build Stories
+
+```bash
+# Build one story
+ralph build 1
+
+# Build 5 stories
+ralph build 5
+
+# Dry run (no commits)
+ralph build 1 --no-commit
+
+# Use specific PRD file
+ralph build 1 --prd .agents/tasks/prd-auth.json
+
+# Override agent for this run
+ralph build 1 --agent codex
+```
+
+### Configuration
+
+```bash
+# Change default agent
+ralph config
+
+# Install templates for customization
+ralph install
+
+# Install skills (commit, dev-browser, prd)
+ralph install --skills
+```
+
+## Configuration
+
+### Global Config
+
+Ralph stores global settings in `~/.ralph/config.json`:
+
+```json
+{
+  "defaultAgent": "claude",
+  "configuredAt": "2026-01-19T12:00:00.000Z"
+}
+```
+
+To change your default agent:
+
+```bash
+ralph config
+```
+
+### Project Config
+
+After running `ralph install`, you can customize behavior in `.agents/ralph/config.sh`:
+
+```bash
+# Override agent command
+AGENT_CMD="claude -p --dangerously-skip-permissions \"\$(cat {prompt})\""
+
+# Build settings
+NO_COMMIT=false
+MAX_ITERATIONS=25
+STALE_SECONDS=0
+```
+
+## Template Hierarchy
+
+Ralph looks for templates in this order:
+
+1. `.agents/ralph/` in current project (if present)
+2. Bundled defaults from the package
+
+State and logs always go to `.ralph/` in the project.
+
+## PRD Story Status
+
+The build loop automatically updates story status:
+
+| Status | Meaning |
+|--------|---------|
+| `open` | Available for selection |
+| `in_progress` | Currently being worked on (with `startedAt`) |
+| `done` | Completed (with `completedAt`) |
+
+If a loop crashes while a story is `in_progress`, set `STALE_SECONDS` in config to auto-reopen stalled stories.
+
+## State Files
+
+All state is stored in `.ralph/` in your project:
+
+| File | Purpose |
+|------|---------|
+| `progress.md` | Append-only progress log |
+| `guardrails.md` | Lessons learned ("Signs") |
+| `activity.log` | Activity and timing log |
+| `errors.log` | Repeated failures and notes |
+| `runs/` | Raw run logs and summaries |
+
+## Advanced
+
+### Multiple PRD Files
+
+If you have multiple PRD JSON files in `.agents/tasks/` and don't specify `--prd`, Ralph will prompt you to choose.
+
+### OpenCode Server Mode
+
+For faster performance with OpenCode, run `opencode serve` in a separate terminal and uncomment the server mode lines in `.agents/ralph/agents.sh`:
+
+```bash
+AGENT_OPENCODE_CMD="opencode run --attach http://localhost:4096 \"\$(cat {prompt})\""
+```
+
+### Custom Agent Commands
+
+Use `{prompt}` placeholder when the agent needs a file path instead of stdin:
+
+```bash
+AGENT_CMD="my-agent --file {prompt}"
+```
+
+## Development
+
+### Running Tests
+
+```bash
+# Dry-run smoke tests (no agent required)
+npm test
+
+# Fast agent health check
+npm run test:ping
+
+# Integration tests (requires agents)
+RALPH_INTEGRATION=1 npm test
+
+# Full real-agent loop test
+npm run test:real
+```
+
+### Publishing
+
+```bash
+npm login
+npm publish --access public
+```
+
+## License
+
+MIT