ralph-tui-create-json

Ralph TUI - 创建 JSON 任务

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

注意： 此技能随 ralph-tui 的 JSON 跟踪器插件打包。未来的跟踪器插件（Linear、GitHub Issues 等）将打包各自的任务创建技能。

⚠️ 重要： 输出必须是一个扁平 JSON 对象，且 "name" 和 "userStories" 位于根级别。不要将内容包装在 "prd" 对象中，也不要使用 "tasks" 数组。请参阅下方的“Schema 反模式”部分。

---

任务

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

1. 提取质量门禁：从 PRD 的“Quality Gates”部分提取
2. 从 PRD 中解析用户故事
3. 将质量门禁追加到每个故事的验收标准中
4. 设置故事之间的依赖关系
5. 输出可直接用于 ralph-tui run --prd <path> 的文件

---

第 1 步：提取质量门禁

在 PRD 中查找“Quality Gates”部分：

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

提取：

• 通用门禁： 适用于所有故事的命令（例如，pnpm typecheck）
• UI 门禁： 仅适用于 UI 故事的命令（例如，浏览器验证）

如果不存在 Quality Gates 部分： 询问用户应通过哪些命令，或采用合理的默认命令，例如 npm run typecheck。

---

输出格式

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

---

重要：Schema 反模式（不要使用）

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

❌ 错误：包装对象

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

这会将所有内容包装在 "prd" 对象中。不要这样做。 "name" 和 "userStories" 字段必须位于根级别。

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

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

数组名称是 "userStories"，而不是 "tasks"。

❌ 错误：复杂的嵌套结构

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

即使 PRD 描述了阶段／里程碑／冲刺，也必须将其展平为单个 "userStories" 数组。

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

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

未完成的故事使用 "passes": false，已完成的故事使用 "passes": true。

✅ 正确：根级别的扁平结构

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

---

故事规模：首要规则

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

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

合适规模的故事：

• 添加一个数据库列和迁移
• 为现有页面添加一个 UI 组件
• 使用新逻辑更新一个服务端操作
• 为列表添加一个筛选下拉菜单

规模过大的故事（请拆分）：

• “构建整个仪表板” → 拆分为：架构、查询、UI 组件、筛选器
• “添加身份验证” → 拆分为：架构、中间件、登录 UI、会话处理
• “重构 API” → 按端点或模式拆分，每个故事负责一个

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

---

使用 dependsOn 设置依赖关系

使用 dependsOn 数组指定必须先完成哪些故事：

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

Ralph-tui 将：

• 在 US-001 完成前，将 US-002 显示为“受阻”
• 在 US-001 仍未完成时，绝不会选择 US-002 执行
• 处理 US-002 时，在提示词中加入“Prerequisites: US-001”

正确的依赖顺序：

1. 架构／数据库变更（无依赖）
2. 后端逻辑（依赖架构）
3. UI 组件（依赖后端）
4. 集成／完善（依赖 UI）

---

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

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

1. 故事专属标准： 来自 PRD（说明此故事要完成什么）
2. 质量门禁： 来自 PRD 的 Quality Gates 部分（追加在末尾）

优秀的标准（可验证）：

• “在 tasks 表中添加 status 列，默认值为 'open'”
• “筛选下拉菜单包含以下选项：All、Open、Closed”
• “点击删除后显示确认对话框”

不佳的标准（含糊不清）：

• ❌ “运行正常”
• ❌ “用户可以轻松完成 X”
• ❌ “用户体验良好”
• ❌ “能够处理边缘情况”

---

转换规则

1. 先从 PRD 中提取质量门槛
2. 每个用户故事对应一个 JSON 条目
3. ID：按顺序编号（US-001、US-002 等）
4. 优先级：根据依赖顺序确定（1 = 最高）
5. dependsOn：此故事所依赖的故事 ID 数组
6. 所有故事：passes: false，且 notes 为空
7. branchName：根据功能名称生成，采用 kebab-case，并以 ralph/ 为前缀
8. 验收标准：故事标准 + 附加的质量门槛
9. UI 故事：还要附加 UI 专属门槛（浏览器验证）

---

输出位置

默认位置：./tasks/prd.json（与 PRD Markdown 文件放在同一目录）

这样所有与 PRD 相关的文件都会集中放在 tasks/ 目录中。

也可以指定其他路径，ralph-tui 将使用以下路径：

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

---

示例

输入 PRD：

# 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

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

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

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

输出 prd.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"]
    }
  ]
}

---

使用 ralph-tui 运行

创建 prd.json 后：

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

Ralph-tui 将会：

1. 从 prd.json 加载故事
2. 选择优先级最高、passes: false 且没有阻塞依赖的故事
3. 根据故事详情和验收标准生成提示词
4. 运行 Agent 来实现故事
5. 完成后将 passes 标记为 true
6. 重复此过程，直到所有故事都通过

---

保存前检查清单

• 已从 PRD 中提取质量门槛（如缺失，则已询问用户）
• 每个故事都能在一次迭代中完成
• 故事已按依赖顺序排列（schema → 后端 → UI）
• 已为每个故事正确设置 dependsOn
• 已将质量门槛附加到每个故事的验收标准中
• UI 故事已包含浏览器验证（如果质量门槛中有此要求）
• 验收标准可验证（不含模糊表述）
• 不存在循环依赖