ralph-tui-create-beads

Ralph TUI - 创建 Beads

将 PRD 转换为 Beads（史诗任务 + 子任务），供 ralph-tui 自主执行。

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

---

任务

接收 PRD（Markdown 文件或文本），并在 .beads/beads.jsonl 中创建 Beads：

1. 提取质量门禁：从 PRD 的“质量门禁”部分提取
2. 为该功能创建一个史诗任务 Bead
3. 为每个用户故事创建子任务 Bead（并附加质量门禁）
4. 设置 Bead 之间的依赖关系（架构 → 后端 → UI）
5. 输出可直接用于 ralph-tui run --tracker beads 的内容

---

步骤 1：提取质量门禁

查找 PRD 中的“质量门禁”部分：

## 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 故事的命令（例如浏览器验证）

如果不存在质量门禁部分： 询问用户应通过哪些命令，或使用合理的默认命令，例如 npm run typecheck。

---

输出格式

Beads 使用 bd create 命令，并通过 HEREDOC 语法安全地处理特殊字符：

# Create epic (link back to source PRD)
bd create --type=epic \
  --title="[Feature Name]" \
  --description="$(cat <<'EOF'
[Feature description from PRD]
EOF
)" \
  --external-ref="prd:./tasks/feature-name-prd.md"

# Create child bead (with quality gates in acceptance criteria)
bd create \
  --parent=EPIC_ID \
  --title="[Story Title]" \
  --description="$(cat <<'EOF'
[Story description with acceptance criteria INCLUDING quality gates]
EOF
)" \
  --priority=[1-4]

重要： HEREDOC 分隔符始终使用 <<'EOF'（单引号）。这样可避免 Shell 解释描述中的反引号、$variables 和 ()。

---

故事规模：首要规则

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

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

合适规模的故事：

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

太大（请拆分）：

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

经验法则： 如果无法用 2-3 句话描述这项改动，那它就太大了。

---

故事排序：依赖优先

故事按依赖顺序执行。较早的故事不得依赖较晚的故事。

正确顺序：

1. 架构/数据库改动（迁移）
2. 服务端操作/后端逻辑
3. 使用后端的 UI 组件
4. 汇总数据的仪表板/摘要视图

错误顺序：

1. ❌ UI 组件（依赖尚不存在的架构）
2. ❌ 架构改动

---

使用 bd dep add 设置依赖关系

使用 bd dep add 命令指定必须先完成哪些 Bead：

# Create the beads first
bd create --parent=epic-123 --title="US-001: Add schema" ...
bd create --parent=epic-123 --title="US-002: Create API" ...
bd create --parent=epic-123 --title="US-003: Build UI" ...

# Then add dependencies (issue depends-on blocker)
bd dep add ralph-tui-002 ralph-tui-001  # US-002 depends on US-001
bd dep add ralph-tui-003 ralph-tui-002  # US-003 depends on US-002

语法： bd dep add <issue> <depends-on> — issue 依赖于（即被阻塞于）depends-on。

ralph-tui 将：

• 在被阻塞的 Bead 依赖项完成前，将其显示为“blocked”
• 只要依赖项仍未关闭，就不会选择该 Bead 执行
• 在处理某个 Bead 时，将依赖关系上下文纳入提示词

正确的依赖顺序：

1. 架构/数据库改动（无依赖）
2. 后端逻辑（依赖于架构）
3. UI 组件（依赖于后端）
4. 集成/润色（依赖于 UI）

---

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

每个 Bead 的描述都应包含验收标准，其中包括：

1. PRD 中的故事专属标准（该故事要实现的内容）
2. PRD“质量门禁”部分中的质量门禁（附加在末尾）

好的标准（可验证）：

• “为 investor 表添加 investorType 列，默认值为 'cold'”
• “筛选下拉菜单包含以下选项：All、Cold、Friend”
• “点击切换按钮时显示确认对话框”

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

• ❌ “正常工作”
• ❌ “用户可以轻松完成 X”
• ❌ “良好的 UX”
• ❌ “处理边缘情况”

---

转换规则

1. 先从 PRD 中提取质量门槛
2. 每个用户故事 → 一个 bead
3. 第一个故事：无依赖（奠定基础）
4. 后续故事：依赖于前置故事（UI 依赖后端等）
5. 优先级：先按依赖顺序，再按文档顺序（0＝关键，2＝中等，4＝待处理）
6. 所有故事：status: "open"
7. 验收标准：故事标准 + 附加质量门槛
8. UI 故事：还要附加 UI 专属门槛（浏览器验证）

---

拆分大型 PRD

如果 PRD 包含大型功能，请将其拆分：

原始内容：

“添加好友拓展流程，并使用不同的消息内容”

拆分为：

1. US-001：向数据库添加 investorType 字段
2. US-002：向投资人列表 UI 添加类型切换开关
3. US-003：创建好友专属阶段推进逻辑
4. US-004：创建好友消息模板
5. US-005：接入好友任务生成
6. US-006：添加按类型筛选
7. US-007：更新新建投资人表单
8. US-008：更新仪表板计数

每项都是一个聚焦的更改，可独立完成并验证。

---

示例

输入 PRD：

# PRD: Friends Outreach

Add ability to mark investors as "friends" for warm outreach.

## 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 investorType field to investor table
**Description:** As a developer, I need to categorize investors as 'cold' or 'friend'.

**Acceptance Criteria:**
- [ ] Add investorType column: 'cold' | 'friend' (default 'cold')
- [ ] Generate and run migration successfully

### US-002: Add type toggle to investor list rows
**Description:** As Ryan, I want to toggle investor type directly from the list.

**Acceptance Criteria:**
- [ ] Each row has Cold | Friend toggle
- [ ] Switching shows confirmation dialog
- [ ] On confirm: updates type in database

### US-003: Filter investors by type
**Description:** As Ryan, I want to filter the list to see just friends or cold.

**Acceptance Criteria:**
- [ ] Filter dropdown: All | Cold | Friend
- [ ] Filter persists in URL params

输出 beads：

# Create epic (link back to source PRD)
bd create --type=epic \
  --title="Friends Outreach Track" \
  --description="$(cat <<'EOF'
Warm outreach for deck feedback
EOF
)" \
  --external-ref="prd:./tasks/friends-outreach-prd.md"

# US-001: No deps (first - creates schema)
bd create --parent=ralph-tui-abc \
  --title="US-001: Add investorType field to investor table" \
  --description="$(cat <<'EOF'
As a developer, I need to categorize investors as 'cold' or 'friend'.

## Acceptance Criteria
- [ ] Add investorType column: 'cold' | 'friend' (default 'cold')
- [ ] Generate and run migration successfully
- [ ] pnpm typecheck passes
- [ ] pnpm lint passes
EOF
)" \
  --priority=1

# US-002: UI story (gets browser verification too)
bd create --parent=ralph-tui-abc \
  --title="US-002: Add type toggle to investor list rows" \
  --description="$(cat <<'EOF'
As Ryan, I want to toggle investor type directly from the list.

## Acceptance Criteria
- [ ] Each row has Cold | Friend toggle
- [ ] Switching shows confirmation dialog
- [ ] On confirm: updates type in database
- [ ] pnpm typecheck passes
- [ ] pnpm lint passes
- [ ] Verify in browser using dev-browser skill
EOF
)" \
  --priority=2

# Add dependency: US-002 depends on US-001
bd dep add ralph-tui-002 ralph-tui-001

# US-003: UI story
bd create --parent=ralph-tui-abc \
  --title="US-003: Filter investors by type" \
  --description="$(cat <<'EOF'
As Ryan, I want to filter the list to see just friends or cold.

## Acceptance Criteria
- [ ] Filter dropdown: All | Cold | Friend
- [ ] Filter persists in URL params
- [ ] pnpm typecheck passes
- [ ] pnpm lint passes
- [ ] Verify in browser using dev-browser skill
EOF
)" \
  --priority=3

# Add dependency: US-003 depends on US-002
bd dep add ralph-tui-003 ralph-tui-002

---

输出位置

Beads 写入：.beads/beads.jsonl

创建后，运行 ralph-tui：

# Work on a specific epic
ralph-tui run --tracker beads --epic ralph-tui-abc

# Or let it pick the best task automatically
ralph-tui run --tracker beads

ralph-tui 将会：

1. 处理指定 epic 中的 beads（或选择最佳可用任务）
2. 完成每个 bead 后将其关闭
3. 所有子项完成后关闭 epic
4. epic 完成后输出 <promise>COMPLETE</promise>

---

创建 Beads 前的检查清单

• 已从 PRD 中提取质量门槛（如果缺失，或已询问用户）
• 每个故事都能在一次迭代中完成（规模足够小）
• 故事按依赖关系排序（架构 → 后端 → UI）
• 每个 bead 的验收标准都已附加质量门槛
• UI 故事包含浏览器验证（如果质量门槛中有要求）
• 验收标准可验证（不含模糊表述）
• 没有故事依赖后续故事（仅依赖更早的故事）
• 创建 beads 后，使用 bd dep add 添加依赖