ralph-tui-create-json

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ralph TUI - Create JSON Tasks

Ralph TUI - 创建JSON任务

Converts PRDs to prd.json format for ralph-tui autonomous execution.

Note: This skill is bundled with ralph-tui's JSON tracker plugin. Future tracker plugins (Linear, GitHub Issues, etc.) will bundle their own task creation skills.

⚠️ CRITICAL: The output MUST be a FLAT JSON object with "name" and "userStories" at the ROOT level. DO NOT wrap content in a "prd" object or use "tasks" array. See "Schema Anti-Patterns" section below.

将PRD转换为prd.json格式，供ralph-tui自主执行。

注意： 此技能随ralph-tui的JSON追踪器插件捆绑提供。未来的追踪器插件（如Linear、GitHub Issues等）将捆绑各自的任务创建技能。

⚠️ 关键提示： 输出必须是一个扁平的JSON对象，"name"和"userStories"字段位于根层级。不要将内容包裹在"prd"对象中，也不要使用"tasks"数组。请查看下方的「Schema反模式」章节。

The Job

任务内容

Take a PRD (markdown file or text) and create a prd.json file:

Extract Quality Gates from the PRD's "Quality Gates" section
Parse user stories from the PRD
Append quality gates to each story's acceptance criteria
Set up dependencies between stories
Output ready for
```
ralph-tui run --prd <path>
```

获取PRD（Markdown文件或文本）并创建prd.json文件：

从PRD的「质量门禁」部分提取质量门禁规则
解析PRD中的用户故事
将质量门禁规则附加到每个故事的验收标准中
配置故事之间的依赖关系
生成可直接用于
```
ralph-tui run --prd <path>
```
的输出文件

Step 1: Extract Quality Gates

步骤1：提取质量门禁规则

Look for the "Quality Gates" section in the PRD:

markdown

undefined

在PRD中查找「质量门禁」部分：

markdown

undefined

Quality Gates

These commands must pass for every user story:

```
pnpm typecheck
```
- Type checking
```
pnpm lint
```
- Linting

For UI stories, also include:

Verify in browser using dev-browser skill


Extract:
- **Universal gates:** Commands that apply to ALL stories (e.g., `pnpm typecheck`)
- **UI gates:** Commands that apply only to UI stories (e.g., browser verification)

**If no Quality Gates section exists:** Ask the user what commands should pass, or use a sensible default like `npm run typecheck`.

---

These commands must pass for every user story:

```
pnpm typecheck
```
- Type checking
```
pnpm lint
```
- Linting

For UI stories, also include:

Verify in browser using dev-browser skill


提取以下内容：
- **通用门禁：** 适用于所有故事的命令（例如 `pnpm typecheck`）
- **UI专属门禁：** 仅适用于UI故事的命令（例如浏览器验证）

**如果PRD中没有质量门禁部分：** 询问用户需要通过哪些命令，或使用合理的默认值（如 `npm run typecheck`）。

---

Output Format

输出格式

The JSON file MUST be a FLAT object at the root level:

json

{
  "name": "[Project name from PRD or directory]",
  "branchName": "ralph/[feature-name-kebab-case]",
  "description": "[Feature description from PRD]",
  "userStories": [
    {
      "id": "US-001",
      "title": "[Story title]",
      "description": "As a [user], I want [feature] so that [benefit]",
      "acceptanceCriteria": [
        "Criterion 1 from PRD",
        "Criterion 2 from PRD",
        "pnpm typecheck passes",
        "pnpm lint passes"
      ],
      "priority": 1,
      "passes": false,
      "notes": "",
      "dependsOn": []
    },
    {
      "id": "US-002",
      "title": "[UI Story that depends on US-001]",
      "description": "...",
      "acceptanceCriteria": [
        "...",
        "pnpm typecheck passes",
        "pnpm lint passes",
        "Verify in browser using dev-browser skill"
      ],
      "priority": 2,
      "passes": false,
      "notes": "",
      "dependsOn": ["US-001"]
    }
  ]
}

JSON文件必须是根层级的扁平对象：

json

{
  "name": "[Project name from PRD or directory]",
  "branchName": "ralph/[feature-name-kebab-case]",
  "description": "[Feature description from PRD]",
  "userStories": [
    {
      "id": "US-001",
      "title": "[Story title]",
      "description": "As a [user], I want [feature] so that [benefit]",
      "acceptanceCriteria": [
        "Criterion 1 from PRD",
        "Criterion 2 from PRD",
        "pnpm typecheck passes",
        "pnpm lint passes"
      ],
      "priority": 1,
      "passes": false,
      "notes": "",
      "dependsOn": []
    },
    {
      "id": "US-002",
      "title": "[UI Story that depends on US-001]",
      "description": "...",
      "acceptanceCriteria": [
        "...",
        "pnpm typecheck passes",
        "pnpm lint passes",
        "Verify in browser using dev-browser skill"
      ],
      "priority": 2,
      "passes": false,
      "notes": "",
      "dependsOn": ["US-001"]
    }
  ]
}

CRITICAL: Schema Anti-Patterns (DO NOT USE)

关键提示：Schema反模式（禁止使用）

The following patterns are INVALID and will cause validation errors:

以下格式无效，会导致验证错误：

❌ WRONG: Wrapper object

❌ 错误：使用包裹对象

json

{
  "prd": {
    "name": "...",
    "userStories": [...]
  }
}

This wraps everything in a "prd" object. DO NOT DO THIS. The "name" and "userStories" fields must be at the ROOT level.

json

{
  "prd": {
    "name": "...",
    "userStories": [...]
  }
}

这种格式将所有内容包裹在"prd"对象中。禁止这样做。 "name"和"userStories"字段必须位于根层级。

❌ WRONG: Using "tasks" instead of "userStories"

❌ 错误：使用"tasks"而非"userStories"

json

{
  "name": "...",
  "tasks": [...]
}

The array is called "userStories", not "tasks".

json

{
  "name": "...",
  "tasks": [...]
}

数组的正确名称是 "userStories"，而非"tasks"。

❌ WRONG: Complex nested structures

❌ 错误：复杂嵌套结构

json

{
  "metadata": {...},
  "overview": {...},
  "migration_strategy": {
    "phases": [...]
  }
}

Even if the PRD describes phases/milestones/sprints, you MUST flatten these into a single "userStories" array.

json

{
  "metadata": {...},
  "overview": {...},
  "migration_strategy": {
    "phases": [...]
  }
}

即使PRD中描述了阶段/里程碑/迭代，也必须将这些内容扁平化为单个"userStories"数组。

❌ WRONG: Using "status" instead of "passes"

❌ 错误：使用"status"而非"passes"

json

{
  "userStories": [{
    "id": "US-001",
    "status": "open"  // WRONG!
  }]
}

Use

"passes": false

for incomplete stories,

"passes": true

for completed.

json

{
  "userStories": [{
    "id": "US-001",
    "status": "open"  // WRONG!
  }]
}

未完成的故事使用

"passes": false

，已完成的故事使用

"passes": true

。

✅ CORRECT: Flat structure at root

✅ 正确：根层级扁平结构

json

{
  "name": "Android Kotlin Migration",
  "branchName": "ralph/kotlin-migration",
  "userStories": [
    {"id": "US-001", "title": "Create Scraper interface", "passes": false, "dependsOn": []},
    {"id": "US-002", "title": "Implement WeebCentralScraper", "passes": false, "dependsOn": ["US-001"]}
  ]
}

json

{
  "name": "Android Kotlin Migration",
  "branchName": "ralph/kotlin-migration",
  "userStories": [
    {"id": "US-001", "title": "Create Scraper interface", "passes": false, "dependsOn": []},
    {"id": "US-002", "title": "Implement WeebCentralScraper", "passes": false, "dependsOn": ["US-001"]}
  ]
}

Story Size: The #1 Rule

故事规模：首要规则

Each story must be completable in ONE ralph-tui iteration (~one agent context window).

Ralph-tui spawns a fresh agent instance per iteration with no memory of previous work. If a story is too big, the agent runs out of context before finishing.

每个故事必须能在一次ralph-tui迭代（约一个Agent上下文窗口）内完成。

Ralph-tui每次迭代会生成一个全新的Agent实例，不保留之前的工作记忆。如果故事规模过大，Agent会在完成前耗尽上下文。

Right-sized stories:

合适规模的故事：

Add a database column + migration
Add a UI component to an existing page
Update a server action with new logic
Add a filter dropdown to a list

添加数据库列+迁移
为现有页面添加UI组件
使用新逻辑更新服务器操作
为列表添加筛选下拉框

Too big (split these):

规模过大（需要拆分）：

"Build the entire dashboard" → Split into: schema, queries, UI components, filters
"Add authentication" → Split into: schema, middleware, login UI, session handling
"Refactor the API" → Split into one story per endpoint or pattern

Rule of thumb: If you can't describe the change in 2-3 sentences, it's too big.

"构建整个仪表盘" → 拆分为： schema、查询、UI组件、筛选器
"添加认证功能" → 拆分为：schema、中间件、登录UI、会话处理
"重构API" → 按每个端点或模式拆分为单个故事

经验法则： 如果你无法用2-3句话描述变更内容，说明故事规模过大。

Dependencies with

dependsOn

使用

dependsOn

配置依赖关系

Use the

dependsOn

array to specify which stories must complete first:

json

{
  "id": "US-002",
  "title": "Create API endpoints",
  "dependsOn": ["US-001"],  // Won't be selected until US-001 passes
  ...
}

Ralph-tui will:

Show US-002 as "blocked" until US-001 completes
Never select US-002 for execution while US-001 is open
Include "Prerequisites: US-001" in the prompt when working on US-002

Correct dependency order:

Schema/database changes (no dependencies)
Backend logic (depends on schema)
UI components (depends on backend)
Integration/polish (depends on UI)

使用

dependsOn

数组指定必须先完成的故事：

json

{
  "id": "US-002",
  "title": "Create API endpoints",
  "dependsOn": ["US-001"],  // 直到US-001完成后才会被选中
  ...
}

Ralph-tui会：

在US-001完成前，将US-002标记为「阻塞」状态
当US-001未完成时，永远不会选择US-002执行
处理US-002时，会在提示中包含「前置条件：US-001」

正确的依赖顺序：

Schema/数据库变更（无依赖）
后端逻辑（依赖Schema）
UI组件（依赖后端）
集成/优化（依赖UI）

Acceptance Criteria: Quality Gates + Story-Specific

验收标准：质量门禁+故事专属规则

Each story's acceptance criteria should include:

Story-specific criteria from the PRD (what this story accomplishes)
Quality gates from the PRD's Quality Gates section (appended at the end)

每个故事的验收标准应包含：

PRD中的故事专属规则（该故事要实现的内容）
PRD「质量门禁」部分的质量门禁规则（附加在末尾）

Good criteria (verifiable):

良好的验收标准（可验证）：

"Add
```
status
```
column to tasks table with default 'open'"
"Filter dropdown has options: All, Open, Closed"
"Clicking delete shows confirmation dialog"

"为tasks表添加
```
status
```
列，默认值为'open'"
"筛选下拉框包含选项：全部、未完成、已完成"
"点击删除按钮时显示确认对话框"

Bad criteria (vague):

糟糕的验收标准（模糊）：

❌ "Works correctly"
❌ "User can do X easily"
❌ "Good UX"
❌ "Handles edge cases"

❌ "正常工作"
❌ "用户可以轻松完成X操作"
❌ "良好的用户体验"
❌ "处理边缘情况"

Conversion Rules

转换规则

Extract Quality Gates from PRD first
Each user story → one JSON entry
IDs: Sequential (US-001, US-002, etc.)
Priority: Based on dependency order (1 = highest)
dependsOn: Array of story IDs this story requires
All stories:
```
passes: false
```
and empty
```
notes
```
branchName: Derive from feature name, kebab-case, prefixed with
```
ralph/
```
Acceptance criteria: Story criteria + quality gates appended
UI stories: Also append UI-specific gates (browser verification)

首先从PRD中提取质量门禁规则
每个用户故事对应一个JSON条目
ID：按顺序编号（US-001、US-002等）
优先级：基于依赖关系排序（1=最高优先级）
dependsOn：每个故事依赖的故事ID数组
所有故事：默认
```
passes: false
```
，
```
notes
```
为空
branchName：从功能名称派生，使用短横线分隔命名法，前缀为
```
ralph/
```
验收标准：故事专属规则+质量门禁规则附加在末尾
UI故事：额外附加UI专属门禁规则（如浏览器验证）

Output Location

输出位置

Default:

./tasks/prd.json

(alongside the PRD markdown files)

This keeps all PRD-related files together in the

tasks/

directory.

Or specify a different path - ralph-tui will use it with:

bash

ralph-tui run --prd ./path/to/prd.json

默认位置：

./tasks/prd.json

（与PRD Markdown文件放在一起）

这样可以将所有PRD相关文件统一放在

tasks/

目录中。

也可以指定其他路径，ralph-tui通过以下命令使用：

bash

ralph-tui run --prd ./path/to/prd.json

Example

示例

Input PRD:

markdown

undefined

输入PRD：

markdown

undefined

PRD: Task Priority System

Add priority levels to tasks.

Quality Gates

These commands must pass for every user story:

```
pnpm typecheck
```
- Type checking
```
pnpm lint
```
- Linting

For UI stories, also include:

Verify in browser using dev-browser skill

These commands must pass for every user story:

```
pnpm typecheck
```
- Type checking
```
pnpm lint
```
- Linting

For UI stories, also include:

Verify in browser using dev-browser skill

User Stories

US-001: Add priority field to database

Description: As a developer, I need to store task priority.

Acceptance Criteria:

Add priority column: 1-4 (default 2)
Migration runs successfully

Description: As a developer, I need to store task priority.

Acceptance Criteria:

Add priority column: 1-4 (default 2)
Migration runs successfully

US-002: Display priority badge on task cards

Description: As a user, I want to see task priority at a glance.

Acceptance Criteria:

Badge shows P1/P2/P3/P4 with colors
Badge visible without hovering

Description: As a user, I want to see task priority at a glance.

Acceptance Criteria:

Badge shows P1/P2/P3/P4 with colors
Badge visible without hovering

US-003: Add priority filter dropdown

Description: As a user, I want to filter tasks by priority.

Acceptance Criteria:

Filter dropdown: All, P1, P2, P3, P4
Filter persists in URL


**Output prd.json:**
```json
{
  "name": "Task Priority System",
  "branchName": "ralph/task-priority",
  "description": "Add priority levels to tasks",
  "userStories": [
    {
      "id": "US-001",
      "title": "Add priority field to database",
      "description": "As a developer, I need to store task priority.",
      "acceptanceCriteria": [
        "Add priority column: 1-4 (default 2)",
        "Migration runs successfully",
        "pnpm typecheck passes",
        "pnpm lint passes"
      ],
      "priority": 1,
      "passes": false,
      "notes": "",
      "dependsOn": []
    },
    {
      "id": "US-002",
      "title": "Display priority badge on task cards",
      "description": "As a user, I want to see task priority at a glance.",
      "acceptanceCriteria": [
        "Badge shows P1/P2/P3/P4 with colors",
        "Badge visible without hovering",
        "pnpm typecheck passes",
        "pnpm lint passes",
        "Verify in browser using dev-browser skill"
      ],
      "priority": 2,
      "passes": false,
      "notes": "",
      "dependsOn": ["US-001"]
    },
    {
      "id": "US-003",
      "title": "Add priority filter dropdown",
      "description": "As a user, I want to filter tasks by priority.",
      "acceptanceCriteria": [
        "Filter dropdown: All, P1, P2, P3, P4",
        "Filter persists in URL",
        "pnpm typecheck passes",
        "pnpm lint passes",
        "Verify in browser using dev-browser skill"
      ],
      "priority": 3,
      "passes": false,
      "notes": "",
      "dependsOn": ["US-002"]
    }
  ]
}

Description: As a user, I want to filter tasks by priority.

Acceptance Criteria:

Filter dropdown: All, P1, P2, P3, P4
Filter persists in URL


**输出prd.json：**
```json
{
  "name": "Task Priority System",
  "branchName": "ralph/task-priority",
  "description": "Add priority levels to tasks",
  "userStories": [
    {
      "id": "US-001",
      "title": "Add priority field to database",
      "description": "As a developer, I need to store task priority.",
      "acceptanceCriteria": [
        "Add priority column: 1-4 (default 2)",
        "Migration runs successfully",
        "pnpm typecheck passes",
        "pnpm lint passes"
      ],
      "priority": 1,
      "passes": false,
      "notes": "",
      "dependsOn": []
    },
    {
      "id": "US-002",
      "title": "Display priority badge on task cards",
      "description": "As a user, I want to see task priority at a glance.",
      "acceptanceCriteria": [
        "Badge shows P1/P2/P3/P4 with colors",
        "Badge visible without hovering",
        "pnpm typecheck passes",
        "pnpm lint passes",
        "Verify in browser using dev-browser skill"
      ],
      "priority": 2,
      "passes": false,
      "notes": "",
      "dependsOn": ["US-001"]
    },
    {
      "id": "US-003",
      "title": "Add priority filter dropdown",
      "description": "As a user, I want to filter tasks by priority.",
      "acceptanceCriteria": [
        "Filter dropdown: All, P1, P2, P3, P4",
        "Filter persists in URL",
        "pnpm typecheck passes",
        "pnpm lint passes",
        "Verify in browser using dev-browser skill"
      ],
      "priority": 3,
      "passes": false,
      "notes": "",
      "dependsOn": ["US-002"]
    }
  ]
}

Running with ralph-tui

使用ralph-tui运行

After creating prd.json:

bash

ralph-tui run --prd ./tasks/prd.json

Ralph-tui will:

Load stories from prd.json
Select the highest-priority story with
```
passes: false
```
and no blocking dependencies
Generate a prompt with story details + acceptance criteria
Run the agent to implement the story
Mark
```
passes: true
```
on completion
Repeat until all stories pass

创建prd.json后：

bash

ralph-tui run --prd ./tasks/prd.json

Ralph-tui会：

从prd.json加载故事
选择优先级最高、
```
passes: false
```
且无阻塞依赖的故事
生成包含故事详情+验收标准的提示词
运行Agent实现该故事
完成后标记
```
passes: true
```
重复直到所有故事标记为完成

Checklist Before Saving

保存前检查清单

Extracted Quality Gates from PRD (or asked user if missing)
Each story completable in one iteration
Stories ordered by dependency (schema → backend → UI)
```
dependsOn
```
correctly set for each story
Quality gates appended to every story's acceptance criteria
UI stories have browser verification (if specified in Quality Gates)
Acceptance criteria are verifiable (not vague)
No circular dependencies

已从PRD提取质量门禁规则（如果缺失则询问用户）
每个故事可在一次迭代内完成
故事按依赖关系排序（schema → 后端 → UI）
每个故事的
```
dependsOn
```
配置正确
质量门禁规则已附加到每个故事的验收标准中
UI故事包含浏览器验证规则（如果质量门禁中指定）
验收标准可验证（非模糊描述）
无循环依赖

ralph-tui-create-json

Original

Translation

Ralph TUI - Create JSON Tasks

Ralph TUI - 创建JSON任务

The Job

任务内容

Step 1: Extract Quality Gates

步骤1：提取质量门禁规则

Quality Gates

Quality Gates

Output Format

输出格式

CRITICAL: Schema Anti-Patterns (DO NOT USE)

关键提示：Schema反模式（禁止使用）

❌ WRONG: Wrapper object

❌ 错误：使用包裹对象

❌ WRONG: Using "tasks" instead of "userStories"

❌ 错误：使用"tasks"而非"userStories"

❌ WRONG: Complex nested structures

❌ 错误：复杂嵌套结构

❌ WRONG: Using "status" instead of "passes"

❌ 错误：使用"status"而非"passes"

✅ CORRECT: Flat structure at root

✅ 正确：根层级扁平结构

Story Size: The #1 Rule

故事规模：首要规则

Right-sized stories:

合适规模的故事：

Too big (split these):

规模过大（需要拆分）：

Dependencies with dependsOn

使用dependsOn配置依赖关系

Acceptance Criteria: Quality Gates + Story-Specific

验收标准：质量门禁+故事专属规则

Good criteria (verifiable):

良好的验收标准（可验证）：

Bad criteria (vague):

糟糕的验收标准（模糊）：

Conversion Rules

转换规则

Output Location

输出位置

Example

示例

PRD: Task Priority System

PRD: Task Priority System

Quality Gates

Quality Gates

User Stories

User Stories

US-001: Add priority field to database

US-001: Add priority field to database

US-002: Display priority badge on task cards

US-002: Display priority badge on task cards

US-003: Add priority filter dropdown

US-003: Add priority filter dropdown

Running with ralph-tui

使用ralph-tui运行

Checklist Before Saving

保存前检查清单

Dependencies with
`dependsOn`

使用
`dependsOn`
配置依赖关系