# Ralph Skill for Claude Code

> Fully autonomous development with fresh context windows, SQLite-backed progress tracking, and Playwright testing

## Introduction

### What is Ralph Skill?

Ralph Skill is a Claude Code skill system that enables **fully autonomous software development**. After you describe what you want to build and answer a few clarifying questions, Ralph takes over and builds everything automatically - implementing features, running tests, and committing code until the project is complete.

**Key Features:**
1. **Fully Autonomous** - Skills run the Ralph Loop automatically until all tasks complete
2. **Cross-Platform** - Works on Windows (PowerShell) and Unix (Linux/macOS)
3. **Fresh Context Per Task** - Each task runs with a clean context, avoiding AI degradation
4. **Integrated Testing** - Playwright E2E tests verify each task before committing
5. **Learning from Failures** - Failed attempts are logged so the next iteration can try differently

### The Ralph Loop Workflow

```
┌─────────────────────────────────────────────────────────────────┐
│                      RALPH LOOP WORKFLOW                        │
├─────────────────────────────────────────────────────────────────┤
│  For each task (runs automatically):                            │
│  1. QUERY ralph.db → get next task by status/priority           │
│  2. READ progress.txt → check Learnings for patterns            │
│  3. IMPLEMENT the task (write code, create files)               │
│  4. RUN Playwright tests                                        │
│  5. If pass: UPDATE database → mark [x] in PRD → commit         │
│  6. If fail: LOG learnings → try different approach             │
│  7. CONTINUE until all tasks complete                           │
│  8. Output <promise>COMPLETE</promise> when done                │
└─────────────────────────────────────────────────────────────────┘
```

---

## Cross-Platform Support

Ralph Skill works on both Windows and Unix systems:

| Action | Windows (PowerShell) | Unix (Bash) |
|--------|---------------------|-------------|
| Create directory | `New-Item -ItemType Directory` | `mkdir -p` |
| Copy file | `Copy-Item` | `cp` |
| Run SQLite | `sqlite3 ralph.db "query"` | `sqlite3 ralph.db "query"` |
| Run Playwright | `npx playwright test` | `npx playwright test` |
| Git commit | `git commit -m "msg"` | `git commit -m "msg"` |

---

## Ralph Skill vs Ralph Wiggum Plugin

| Aspect | Ralph Skill (This Project) | Ralph Wiggum Plugin |
|--------|---------------------------|---------------------|
| **Execution** | Fully autonomous until complete | Requires manual loop start |
| **Architecture** | Fresh context per task | Single continuous session |
| **Platform** | Windows + Linux/macOS | Varies |
| **Testing** | Playwright E2E integrated | Basic test running |
| **Best For** | Large projects (10+ tasks) | Quick tasks (< 5 iterations) |

---

## Installation

### Prerequisites

Ralph Skill will **automatically install** dependencies when needed:

| Dependency | Purpose | Auto-Install |
|------------|---------|--------------|
| **SQLite3** | Task database | Yes (brew/apt/winget) |
| **Git** | Version control | Yes |
| **Playwright** | E2E testing | Setup during project creation |

### Install the Skills

**Clone the repository:**
```bash
git clone https://github.com/kroegha/Ralph-Skill.git
cd Ralph-Skill
```

**Copy skills to Claude Code:**

**Linux/macOS:**
```bash
mkdir -p ~/.claude/skills
cp -r .claude/skills/* ~/.claude/skills/
```

**Windows (PowerShell):**
```powershell
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude\skills"
Copy-Item -Recurse .claude\skills\* "$env:USERPROFILE\.claude\skills\"
```

**Verify installation:**
```bash
claude
> /ralph-new
```

---

## Usage Guide

### `/ralph-new` - Create and Build New Project

Creates a complete project and **automatically builds it** until all tasks are done.

**What Happens:**
1. **Gather Requirements** - Asks what you want to build (text, documents, URLs)
2. **Ask Clarifying Questions** - Tech stack, testing, auth requirements
3. **Fetch Documentation** - Uses Context7 for framework docs
4. **Generate PRD** - Creates PRD.md with properly-sized user stories
5. **Initialize Database** - Creates ralph.db with all tasks
6. **Setup Playwright** - Configures E2E testing
7. **🔄 AUTO-RUN LOOP** - Implements ALL tasks automatically until complete

**Example:**
```
/ralph-new

What would you like to build? (text, document paths, or URLs)
> A REST API for task management using FastAPI with SQLite

[Clarifying questions about tech stack, testing, auth...]

Creating project...
✓ PRD.md with 8 user stories
✓ ralph.db initialized
✓ Playwright configured

🔄 Starting autonomous development...

Implementing US-001: Create database schema...
✓ Tests passed - committed

Implementing US-002: Create todo model...
✓ Tests passed - committed

[... continues until all tasks complete ...]

<promise>COMPLETE</promise>
```

**You don't need to run any scripts** - the skill does everything automatically.

---

### `/ralph-enhance` - Add Features Automatically

Adds features to an existing codebase and **implements them automatically**.

**What Happens:**
1. **Gather Requirements** - What enhancement you want (text, documents, URLs)
2. **Analyze Codebase** - Understands existing structure and patterns
3. **Ask Clarifying Questions** - Scope, UI changes, API changes
4. **Create Enhancement Doc** - docs/enhancements/ENH-XXX.md
5. **Update PRD** - Adds new user stories
6. **Update Database** - Inserts new tasks
7. **🔄 AUTO-RUN LOOP** - Implements ALL enhancement tasks automatically

**Example:**
```
/ralph-enhance

What enhancement would you like? (text, document paths, or URLs)
> Add JWT authentication with refresh tokens

[Analyzes codebase...]
[Clarifying questions...]

✓ Created ENH-001.md
✓ Added 5 user stories (US-009 to US-013)
✓ Database updated

🔄 Starting autonomous development...

Implementing US-009: Add user model with password hash...
✓ Tests passed - committed

[... continues until all enhancement tasks complete ...]

<promise>COMPLETE</promise>
```

---

### `/ralph-status` - View Status and Continue

Shows project progress and offers to **continue development** if tasks remain.

**Example:**
```
/ralph-status

╔══════════════════════════════════════════════════════════════════╗
║                     RALPH PROJECT STATUS                          ║
╠══════════════════════════════════════════════════════════════════╣

TASK SUMMARY
  ● In Progress:  1
  ○ Planned:      3
  ✓ Completed:    8
  ✗ Failed:       0

PROGRESS
  [████████████████████░░░░░░░░░░] 67% Complete

╚══════════════════════════════════════════════════════════════════╝

Tasks remaining: 4

Would you like to:
A) Continue development (run Ralph Loop automatically)
B) View web dashboard (Kanban board)
C) Exit (status only)
```

If you choose **A**, the skill continues implementing remaining tasks automatically.

---

## Manual Loop Execution (Optional)

If you prefer to run the loop manually or need to resume:

**Linux/macOS:**
```bash
./scripts/ralph.sh 25        # 25 iterations
```

**Windows:**
```powershell
.\scripts\ralph.ps1 -MaxIterations 25
```

---

## Database Commands

**Linux/macOS:**
```bash
./scripts/ralph-db.sh status          # View status
./scripts/ralph-db.sh list            # List tasks
./scripts/ralph-db.sh list planned    # Filter by status
./scripts/ralph-db.sh log             # Recent activity
./scripts/ralph-db.sh dashboard       # Generate Kanban data
```

**Windows:**
```powershell
.\scripts\ralph-db.ps1 status
.\scripts\ralph-db.ps1 list
.\scripts\ralph-db.ps1 dashboard
```

---

## Web Dashboard (Kanban Board)

The skills automatically copy `dashboard.html` to your project during setup.

### Starting the Dashboard

The dashboard requires an HTTP server (browsers block local file JSON loading for security).

**Step 1: Generate dashboard data**
```bash
./scripts/ralph-db.sh dashboard    # Unix
.\scripts\ralph-db.ps1 dashboard   # Windows
```

**Step 2: Start the HTTP server**

**Linux/macOS:**
```bash
python3 -m http.server 8080
```

**Windows (PowerShell):**
```powershell
python -m http.server 8080
```

**Step 3: Open in browser**
```
http://localhost:8080/dashboard.html
```

### Quick Start (One Command)

**Linux/macOS:**
```bash
./scripts/ralph-db.sh dashboard && python3 -m http.server 8080
```

**Windows (PowerShell):**
```powershell
.\scripts\ralph-db.ps1 dashboard; python -m http.server 8080
```

Then open http://localhost:8080/dashboard.html in your browser.

### If dashboard.html is missing

Copy from Ralph-Skill or download:
```bash
# From cloned repo
cp /path/to/Ralph-Skill/templates/dashboard.html .

# Or download directly
curl -sO https://raw.githubusercontent.com/kroegha/Ralph-Skill/main/templates/dashboard.html
```

### Dashboard Features
- 4-column Kanban: Planned → In Progress → Done → Failed
- Auto-refresh every 5 seconds
- Light/Dark mode toggle (Theme button)
- Task cards with priority and details
- Progress bar with completion percentage
- Iteration statistics (success/failed counts)

---

## Testing with Playwright

All projects use Playwright for E2E testing.

**Node.js:**
```bash
npm init playwright@latest
npx playwright test
```

**Python:**
```bash
pip install pytest-playwright
playwright install
pytest tests/e2e
```

### Test Steps in PRD

User stories include Playwright test steps:
```json
[
  {"step": 1, "action": "navigate", "target": "/login"},
  {"step": 2, "action": "fill", "target": "#email", "value": "test@example.com"},
  {"step": 3, "action": "click", "target": "button[type=submit]"},
  {"step": 4, "action": "verify", "target": "h1", "expected": "Dashboard"}
]
```

---

## Task Sizing

**Critical:** Each task must complete in ONE context window (~10 min).

| Too Big | Split Into |
|---------|-----------|
| "Build dashboard" | Schema, queries, UI, filters |
| "Add auth" | Schema, middleware, login UI, sessions |

**Rule:** If you cannot describe the change in 2-3 sentences, it's too big.

---

## Project Structure

After setup:
```
your-project/
├── PRD.md                  # User stories with checkboxes
├── ralph.db                # SQLite database (source of truth)
├── progress.txt            # Learnings log
├── AGENTS.md               # Reusable patterns
├── dashboard.html          # Web dashboard (Kanban board)
├── ralph-dashboard.json    # Generated by dashboard command
├── docs/enhancements/      # Enhancement docs
├── tests/e2e/              # Playwright tests
├── templates/
│   └── schema.sql          # Database schema
└── scripts/
    ├── ralph.sh / .ps1     # Loop scripts
    └── ralph-db.sh / .ps1  # Database helpers
```

---

## Completion Signals

Skills output these signals when done:

| Signal | Meaning |
|--------|---------|
| `<promise>COMPLETE</promise>` | All tasks finished successfully |
| `<promise>FAILED</promise>` | Blocked by repeated failures |

---

## Troubleshooting

### "sqlite3: command not found"
```bash
brew install sqlite3        # macOS
sudo apt install sqlite3    # Ubuntu
winget install SQLite.SQLite # Windows
```

### "No database found"
Run `/ralph-new` or `/ralph-enhance` first.

### Tasks keep failing
Check `progress.txt` for learnings. Task may be too large - split it.

### Platform detection issues
Skills auto-detect Windows vs Unix. If issues occur, check `$OSTYPE` (Unix) or `$env:OS` (Windows).

---

## Links

- **GitHub:** https://github.com/kroegha/Ralph-Skill
- **Medium Article:** [Breaking Free from AI Context Limits](docs/medium-article.md)

---

## Support

- **Issues:** https://github.com/kroegha/Ralph-Skill/issues
- **Discussions:** https://github.com/kroegha/Ralph-Skill/discussions

---

## License

MIT License - See LICENSE file for details.