ralph-skill

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# 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](https://github.com/kroegha/ralph-skill/blob/HEAD/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.

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:

Fully Autonomous - Skills run the Ralph Loop automatically until all tasks complete
Cross-Platform - Works on Windows (PowerShell) and Unix (Linux/macOS)
Fresh Context Per Task - Each task runs with a clean context, avoiding AI degradation
Integrated Testing - Playwright E2E tests verify each task before committing
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:

git clone https://github.com/kroegha/Ralph-Skill.git
cd Ralph-Skill

Copy skills to Claude Code:

Linux/macOS:

mkdir -p ~/.claude/skills
cp -r .claude/skills/* ~/.claude/skills/

Windows (PowerShell):

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude\skills"
Copy-Item -Recurse .claude\skills\* "$env:USERPROFILE\.claude\skills\"

Verify installation:

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:

Gather Requirements - Asks what you want to build (text, documents, URLs)
Ask Clarifying Questions - Tech stack, testing, auth requirements
Fetch Documentation - Uses Context7 for framework docs
Generate PRD - Creates PRD.md with properly-sized user stories
Initialize Database - Creates ralph.db with all tasks
Setup Playwright - Configures E2E testing
🔄 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:

Gather Requirements - What enhancement you want (text, documents, URLs)
Analyze Codebase - Understands existing structure and patterns
Ask Clarifying Questions - Scope, UI changes, API changes
Create Enhancement Doc - docs/enhancements/ENH-XXX.md
Update PRD - Adds new user stories
Update Database - Inserts new tasks
🔄 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:

./scripts/ralph.sh 25        # 25 iterations

Windows:

.\scripts\ralph.ps1 -MaxIterations 25

Database Commands

Linux/macOS:

./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:

.\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

./scripts/ralph-db.sh dashboard    # Unix
.\scripts\ralph-db.ps1 dashboard   # Windows

Step 2: Start the HTTP server

Linux/macOS:

python3 -m http.server 8080

Windows (PowerShell):

python -m http.server 8080

Step 3: Open in browser

http://localhost:8080/dashboard.html

Quick Start (One Command)

Linux/macOS:

./scripts/ralph-db.sh dashboard && python3 -m http.server 8080

Windows (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:

# 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:

npm init playwright@latest
npx playwright test

Python:

pip install pytest-playwright
playwright install
pytest tests/e2e

Test Steps in PRD

User stories include Playwright test steps:

[
  {"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"

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).

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.

ralph-skill

原始内容

Ralph Skill for Claude Code

Introduction

What is Ralph Skill?

The Ralph Loop Workflow

Cross-Platform Support

Ralph Skill vs Ralph Wiggum Plugin

Installation

Prerequisites

Install the Skills

Usage Guide

/ralph-new - Create and Build New Project

/ralph-enhance - Add Features Automatically

/ralph-status - View Status and Continue

Manual Loop Execution (Optional)

Database Commands

Web Dashboard (Kanban Board)

Starting the Dashboard

Quick Start (One Command)

If dashboard.html is missing

Dashboard Features

Testing with Playwright

Test Steps in PRD

Task Sizing

Project Structure

Completion Signals

Troubleshooting

"sqlite3: command not found"

"No database found"

Tasks keep failing

Platform detection issues

Links

Support

License

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

`/ralph-enhance` - Add Features Automatically

`/ralph-status` - View Status and Continue