Ralph Enhance Project Skill

Add enhancements to an existing project with full Ralph Loop automation, PRD updates, Playwright testing, and automatic execution of all tasks.

CRITICAL: AUTONOMOUS EXECUTION

After gathering requirements and setting up the enhancement, you MUST automatically start implementing tasks and continue until ALL enhancement tasks are complete. Do NOT stop after setup - the goal is fully autonomous development.

WORKFLOW

Phase 1: Gather Enhancement Requirements

Step 1.1: Get User Input

Ask what enhancement they want:

What enhancement would you like to add? You can:

Describe it in text
Provide document path(s) with requirements
Provide URL(s) with specifications

Step 1.2: Read All Input Documents

If user provides documents:

Read each document using the Read tool
Extract enhancement requirements
Identify affected areas of the codebase

Step 1.3: Ask Clarifying Questions

You MUST ask clarifying questions using AskUserQuestion tool:

Scope: What specific functionality should this add/change?
UI Changes: Any user interface changes needed?
API Changes: Any new endpoints or modifications?
Database Changes: Any schema changes required?
Testing: Specific test scenarios to cover?

Wait for user answers before proceeding.

Phase 2: Analyze Existing Codebase

Step 2.1: Detect Platform

Detect operating system

if [[ "$OSTYPE" == "msys" ]] || [[ "$OSTYPE" == "win32" ]] || [[ -n "$WINDIR" ]]; then PLATFORM="windows" else PLATFORM="unix" fi

Step 2.2: Discover Project Structure

Find project files

find . -type f ( -name ".py" -o -name ".ts" -o -name "*.js" ) | head -50 ls -la

Read package.json, pyproject.toml, or other config files to understand the stack.

Step 2.3: Identify Tech Stack

Determine:

Programming language
Framework (Express, FastAPI, Next.js, etc.)
Database (if any)
Testing framework
Project conventions

Step 2.4: Check for Existing Ralph Setup

Check for existing Ralph files

ls PRD.md ralph.db scripts/ralph*.sh dashboard.html 2>/dev/null

If Ralph is NOT set up:

Initialize ralph.db with schema
Create PRD.md if missing
Copy loop scripts from Ralph-Skill installation
Copy dashboard.html for web visualization

Copy required files if missing:

Unix:

Copy from personal skills location

RALPH_PATH=~/.claude/skills/ralph-new cp $RALPH_PATH/../../../templates/schema.sql templates/ 2>/dev/null cp $RALPH_PATH/../../../scripts/ralph*.sh scripts/ 2>/dev/null cp $RALPH_PATH/../../../templates/dashboard.html . 2>/dev/null chmod +x scripts/*.sh 2>/dev/null

Windows:

$ralphPath = "$env:USERPROFILE.claude\skills\ralph-new" Copy-Item "$ralphPath......\templates\schema.sql" templates\ -ErrorAction SilentlyContinue Copy-Item "$ralphPath......\scripts\ralph*.ps1" scripts\ -ErrorAction SilentlyContinue Copy-Item "$ralphPath......\templates\dashboard.html" . -ErrorAction SilentlyContinue

If files not found locally, download from GitHub:

curl -sO https://raw.githubusercontent.com/kroegha/Ralph-Skill/main/templates/dashboard.html curl -sO https://raw.githubusercontent.com/kroegha/Ralph-Skill/main/templates/schema.sql

Step 2.5: Read Existing PRD

cat PRD.md 2>/dev/null

Note the highest US-XXX number for new stories.

Phase 3: Fetch Relevant Documentation

Fetch Context7 documentation for technologies relevant to the enhancement.

Phase 4: Create Enhancement Document

Step 4.1: Create Enhancement Doc

mkdir -p docs/enhancements

Create docs/enhancements/ENH-XXX.md :

Enhancement: [Title]

Overview

[Brief description]

Requirements

[From user input]

Technical Approach

[How to implement]

Affected Files

[Files to modify]
[New files to create]

Testing Strategy

Unit tests: [what]
E2E tests: [Playwright scenarios]

Phase 5: Generate User Stories

Step 5.1: Create Task Breakdown

Break enhancement into user stories. Each MUST:

Be completable in ONE context window (~10 min)
Have clear acceptance criteria
Include Playwright test steps

Step 5.2: Update PRD.md

Append new user stories:

Enhancement: ENH-XXX - [Title]

US-XXX: [Story Title]

Description: As a [user], I want [feature] so that [benefit].

Acceptance Criteria:

[Criterion 1]
[Criterion 2]
All tests pass

Test Steps (Playwright):

[
  {"step": 1, "action": "navigate", "target": "/path"},
  {"step": 2, "action": "click", "target": "selector"},
  {"step": 3, "action": "verify", "target": "text", "expected": "result"}
]

### Phase 6: Update Database

**Step 6.1: Add Tasks to Database**

For each new user story:

```bash
sqlite3 ralph.db "INSERT INTO tasks (task_id, name, type, status) VALUES ('US-XXX', 'Story title', 'enhancement', 'planned');"

Step 6.2: Verify Database

sqlite3 ralph.db "SELECT task_id, name, status FROM tasks WHERE status='planned';"

Phase 7: Setup Testing for Enhancement

Create Playwright test file:

For Node.js:

// tests/e2e/enh-xxx.spec.ts
import { test, expect } from '@playwright/test';

test.describe('ENH-XXX: [Title]', () => {
  test('US-XXX: [Story]', async ({ page }) => {
    // Test implementation
  });
});

For Python:

# tests/e2e/test_enh_xxx.py
from playwright.sync_api import Page, expect

def test_us_xxx_story(page: Page):
    # Test implementation
    pass

Phase 8: START THE RALPH LOOP (AUTOMATIC)

CRITICAL: You MUST start implementing tasks automatically. Do NOT ask the user to run the loop.

Step 8.1: Implement the Inline Loop

Execute this loop until all enhancement tasks are complete:

WHILE there are pending enhancement tasks in ralph.db:
    1. Get next task:
       TASK_ID=$(sqlite3 ralph.db "SELECT task_id FROM tasks WHERE status='planned' AND type='enhancement' ORDER BY priority LIMIT 1;")

    2. If no task, check for in-progress:
       TASK_ID=$(sqlite3 ralph.db "SELECT task_id FROM tasks WHERE status='in-progress' ORDER BY started_at LIMIT 1;")

    3. If still no task, ALL DONE - exit loop

    4. Mark as in-progress:
       sqlite3 ralph.db "UPDATE tasks SET status='in-progress', started_at=CURRENT_TIMESTAMP WHERE task_id='$TASK_ID';"

    5. Read task details from PRD.md

    6. IMPLEMENT the task:
       - Write/modify code files
       - Follow existing project patterns
       - Create/update tests

    7. RUN tests:
       # Node.js
       npx playwright test tests/e2e/enh-xxx.spec.ts
       # OR Python
       pytest tests/e2e/test_enh_xxx.py

    8. IF tests pass:
       - sqlite3 ralph.db "UPDATE tasks SET status='completed', completed_at=CURRENT_TIMESTAMP WHERE task_id='$TASK_ID';"
       - Update PRD.md: change [ ] to [x] for this task
       - git add . &#x26;&#x26; git commit -m "Complete $TASK_ID: [description]"

    9. IF tests fail:
       - Append error to progress.txt with learnings
       - sqlite3 ralph.db "UPDATE tasks SET iteration_count=iteration_count+1 WHERE task_id='$TASK_ID';"
       - Check failure count:
         FAILURES=$(sqlite3 ralph.db "SELECT iteration_count FROM tasks WHERE task_id='$TASK_ID';")
         if [ $FAILURES -ge 3 ]; then
           sqlite3 ralph.db "UPDATE tasks SET status='failed' WHERE task_id='$TASK_ID';"
         fi
       - Try different approach on next iteration

    10. CONTINUE to next task
END WHILE

Step 8.2: Platform-Specific Commands

Windows (PowerShell):

$taskId = sqlite3 ralph.db "SELECT task_id FROM tasks WHERE status='planned' ORDER BY priority LIMIT 1;"
sqlite3 ralph.db "UPDATE tasks SET status='in-progress' WHERE task_id='$taskId';"
npx playwright test
git add . ; git commit -m "Complete ${taskId}"

Unix (Bash):

TASK_ID=$(sqlite3 ralph.db "SELECT task_id FROM tasks WHERE status='planned' ORDER BY priority LIMIT 1;")
sqlite3 ralph.db "UPDATE tasks SET status='in-progress' WHERE task_id='$TASK_ID';"
npx playwright test
git add . &#x26;&#x26; git commit -m "Complete $TASK_ID"

Step 8.3: Loop Until Complete

Continue until:

- All enhancement tasks are completed

- OR remaining tasks are failed
 (blocked)

When complete, output:

&#x3C;promise>COMPLETE&#x3C;/promise>

When blocked, output:

&#x3C;promise>FAILED&#x3C;/promise>

CROSS-PLATFORM COMMANDS REFERENCE

Action
Windows (PowerShell)
Unix (Bash)

Create directory
New-Item -ItemType Directory -Path "dir"

mkdir -p dir

Copy file
Copy-Item src dest

cp src dest

Check if file exists
Test-Path "file"

[[ -f file ]]

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"

COMPLETION REQUIREMENTS

You have NOT completed this skill until:

- All enhancement user stories are implemented

- All Playwright tests pass

- All enhancement tasks are marked complete in ralph.db

- Final commit is made

- &#x3C;promise>COMPLETE&#x3C;/promise>
 is output

DO NOT stop after setup. DO NOT ask user to run the loop. Implement everything automatically.

ralph-enhance

Safety Notice

Copy this and send it to your AI assistant to learn