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:

1. Read each document using the Read tool
2. Extract enhancement requirements
3. Identify affected areas of the codebase

Step 1.3: Ask Clarifying Questions

You MUST ask clarifying questions using AskUserQuestion tool:

1. Scope: What specific functionality should this add/change?
2. UI Changes: Any user interface changes needed?
3. API Changes: Any new endpoints or modifications?
4. Database Changes: Any schema changes required?
5. 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):**
```json
[
  {"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 . && 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 . && 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:

<promise>COMPLETE</promise>

When blocked, output:

<promise>FAILED</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:

1. All enhancement user stories are implemented
2. All Playwright tests pass
3. All enhancement tasks are marked complete in ralph.db
4. Final commit is made
5. <promise>COMPLETE</promise> is output

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