Agent-Skills.md

Agent Skills: Ralph Enhance Project Skill

Add enhancements to an existing project with Ralph Loop automation. Use when adding features to existing code, enhancing a codebase, or when the user says "ralph enhance", "add feature", or "enhance".

UncategorizedID: kroegha/ralph-skill/ralph-enhance

Repository

kroegha/ralph-skill
kroegha
1

Install this agent skill to your local

pnpm dlx add-skill https://github.com/kroegha/Ralph-Skill/tree/HEAD/.claude/skills/ralph-enhance

Skill Files

Browse the full folder contents for ralph-enhance.

Download Skill

Loading file tree…

.claude/skills/ralph-enhance/SKILL.md

Skill Metadata

Name
ralph-enhance
Description
Add enhancements to an existing project with Ralph Loop automation. Use when adding features to existing code, enhancing a codebase, or when the user says "ralph enhance", "add feature", or "enhance".

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.