ralph-enhance

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ralph Enhance Project Skill

Ralph 项目增强技能

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

借助完整的Ralph Loop自动化、PRD更新、Playwright测试及所有任务自动执行功能，为现有项目添加增强功能。

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

阶段1：收集增强需求

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.

步骤1.1：获取用户输入

询问用户想要的增强内容：

你想要添加什么增强功能？你可以：
- 用文字描述
- 提供包含需求的文档路径
- 提供包含规格说明的URL

步骤1.2：读取所有输入文档

如果用户提供了文档：

使用读取工具读取每个文档
提取增强需求
确定代码库中受影响的区域

步骤1.3：提出澄清问题

你必须使用AskUserQuestion工具提出澄清问题：

范围：此功能需要添加/修改哪些具体功能？
UI变更：是否需要进行用户界面变更？
API变更：是否需要新增或修改接口？
数据库变更：是否需要进行 schema 变更？
测试：需要覆盖哪些特定测试场景？

等待用户答复后再继续。

Phase 2: Analyze Existing Codebase

阶段2：分析现有代码库

Step 2.1: Detect Platform

bash

undefined

步骤2.1：检测平台

bash

undefined

Detect operating system

检测操作系统

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


**Step 2.2: Discover Project Structure**

```bash

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


**步骤2.2：探索项目结构**

```bash

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**

```bash

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


读取package.json、pyproject.toml或其他配置文件以了解技术栈。

**步骤2.3：确定技术栈**

确定以下内容：
- 编程语言
- 框架（Express、FastAPI、Next.js等）
- 数据库（如有）
- 测试框架
- 项目约定

**步骤2.4：检查现有Ralph设置**

```bash

Check for existing Ralph files

检查现有Ralph文件

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:**
```bash

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


如果未设置Ralph：
- 使用schema.sql初始化ralph.db
- 若缺少PRD.md则创建该文件
- 从Ralph-Skill安装目录复制循环脚本
- 复制dashboard.html用于Web可视化

**复制缺失的必要文件：**

**Unix系统：**
```bash

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:**
```powershell
$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:

bash

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

bash

cat PRD.md 2>/dev/null

Note the highest US-XXX number for new stories.


**Windows系统：**
```powershell
$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

如果本地未找到文件，从GitHub下载：

bash

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

步骤2.5：读取现有PRD

bash

cat PRD.md 2>/dev/null

记录最高的US-XXX编号，用于创建新的用户故事。

Phase 3: Fetch Relevant Documentation

阶段3：获取相关文档

Fetch Context7 documentation for technologies relevant to the enhancement.

获取与增强功能相关的Context7文档。

Phase 4: Create Enhancement Document

阶段4：创建增强文档

Step 4.1: Create Enhancement Doc

bash

mkdir -p docs/enhancements

Create

docs/enhancements/ENH-XXX.md

markdown

undefined

步骤4.1：创建增强文档

bash

mkdir -p docs/enhancements

创建

docs/enhancements/ENH-XXX.md

：

markdown

undefined

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]

undefined

单元测试：[测试内容]
端到端测试：[Playwright测试场景]

undefined

Phase 5: Generate User Stories

阶段5：生成用户故事

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:

markdown

---

步骤5.1：任务拆分

将增强功能拆分为用户故事。每个用户故事必须：

可在一个上下文窗口内完成（约10分钟）
具备明确的验收标准
包含Playwright测试步骤

步骤5.2：更新PRD.md

追加新的用户故事：

markdown

---

Enhancement: ENH-XXX - [Title]

增强功能：ENH-XXX - [标题]

US-XXX: [Story Title]

US-XXX：[故事标题]

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"}
]

undefined

描述：作为[用户角色]，我希望[功能]，以便[收益]。

验收标准：

[标准1]
[标准2]
所有测试通过

测试步骤（Playwright）：

json

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

undefined

Phase 6: Update Database

阶段6：更新数据库

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

bash

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

步骤6.1：向数据库添加任务

为每个新用户故事执行：

bash

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

步骤6.2：验证数据库

bash

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

Phase 7: Setup Testing for Enhancement

阶段7：为增强功能设置测试

Create Playwright test file:

For Node.js:

typescript

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

python

undefined

创建Playwright测试文件：

Node.js项目：

typescript

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

test.describe('ENH-XXX: [Title]', () => {
  test('US-XXX: [Story]', async ({ page }) => {
    // 测试实现代码
  });
});

Python项目：

python

undefined

tests/e2e/test_enh_xxx.py

from playwright.sync_api import Page, expect

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

undefined

from playwright.sync_api import Page, expect

def test_us_xxx_story(page: Page): # 测试实现代码 pass

undefined

Phase 8: START THE RALPH LOOP (AUTOMATIC)

阶段8：启动RALPH循环（自动执行）

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

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

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>

重要提示：你必须自动开始执行任务。请勿要求用户运行循环。

步骤8.1：实现内置循环

执行以下循环，直至所有增强任务完成：

WHILE ralph.db中存在待处理的增强任务:
    1. 获取下一个任务:
       TASK_ID=$(sqlite3 ralph.db "SELECT task_id FROM tasks WHERE status='planned' AND type='enhancement' ORDER BY priority LIMIT 1;")

    2. 如果没有任务，检查进行中的任务:
       TASK_ID=$(sqlite3 ralph.db "SELECT task_id FROM tasks WHERE status='in-progress' ORDER BY started_at LIMIT 1;")

    3. 如果仍无任务，全部完成 - 退出循环

    4. 标记为进行中:
       sqlite3 ralph.db "UPDATE tasks SET status='in-progress', started_at=CURRENT_TIMESTAMP WHERE task_id='$TASK_ID';"

    5. 从PRD.md读取任务详情

    6. 实现任务:
       - 编写/修改代码文件
       - 遵循现有项目模式
       - 创建/更新测试

    7. 运行测试:
       # Node.js
       npx playwright test tests/e2e/enh-xxx.spec.ts
       # 或Python
       pytest tests/e2e/test_enh_xxx.py

    8. 如果测试通过:
       - sqlite3 ralph.db "UPDATE tasks SET status='completed', completed_at=CURRENT_TIMESTAMP WHERE task_id='$TASK_ID';"
       - 更新PRD.md: 将此任务的[ ]改为[x]
       - git add . && git commit -m "Complete $TASK_ID: [description]"

    9. 如果测试失败:
       - 将错误及经验教训追加到progress.txt
       - sqlite3 ralph.db "UPDATE tasks SET iteration_count=iteration_count+1 WHERE task_id='$TASK_ID';"
       - 检查失败次数:
         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
       - 在下一次循环中尝试不同的实现方式

    10. 继续下一个任务
END WHILE

步骤8.2：平台特定命令

Windows（PowerShell）：

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）：

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"

步骤8.3：循环直至完成

持续执行，直至：

所有增强任务标记为
```
completed
```
或剩余任务标记为
```
failed
```
（受阻）

完成后输出：

<promise>COMPLETE</promise>

受阻时输出：

<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"`

操作	Windows（PowerShell）	Unix（Bash）
创建目录	`New-Item -ItemType Directory -Path "dir"`	`mkdir -p dir`
复制文件	`Copy-Item src dest`	`cp src dest`
检查文件是否存在	`Test-Path "file"`	`[[ -f file ]]`
运行SQLite	`sqlite3 ralph.db "query"`	`sqlite3 ralph.db "query"`
运行Playwright	`npx playwright test`	`npx playwright test`
Git提交	`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
```
<promise>COMPLETE</promise>
```
is output

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

满足以下条件后，此技能才算完成：

所有增强用户故事已实现
所有Playwright测试通过
所有增强任务在ralph.db中标记为完成
已提交最终Git版本
已输出
```
<promise>COMPLETE</promise>
```

请勿在设置完成后停止。请勿要求用户运行循环。自动完成所有实现工作。