ralph-tui-create-beads-rust

Ralph TUI - 创建 Beads（beads-rust）

使用 beads-rust（br CLI）将 PRD 转换为 beads（史诗 + 子任务），供 ralph-tui 自主执行。

**注意：**此技能使用 beads-rust 中的 br 命令。如果你安装的是原版 beads（bd），请改用 ralph-tui-create-beads 技能。

---

工作内容

使用 br 命令读取 PRD（Markdown 文件或文本）并创建 beads：

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

---

第 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 使用 br create 命令，并通过 HEREDOC 语法安全处理特殊字符：

# Create epic (link back to source PRD)
br 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)
br create \
  --parent=EPIC_ID \
  --title="[Story Title]" \
  --description="$(cat <<'EOF'
[Story description with acceptance criteria INCLUDING quality gates]
EOF
)" \
  --priority=[1-4]

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

---

故事大小：首要规则

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

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

合适大小的故事：

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

太大的故事（请拆分）：

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

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

---

故事排序：优先处理依赖项

故事按依赖顺序执行。前面的故事不能依赖后面的故事。

正确顺序：

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

错误顺序：

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

---

使用 br dep add 设置依赖关系

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

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

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

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

ralph-tui 将会：

• 将被阻塞的 beads 显示为“blocked”，直到依赖项完成
• 只要依赖项仍未完成，就不会选择该 bead 执行
• 在处理 bead 时，将依赖上下文纳入提示词

正确的依赖顺序：

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

---

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

每个 bead 的描述都应包含验收标准：

1. PRD 中的故事专属标准（该故事要完成什么）
2. PRD“质量门禁”部分中的质量门禁（附加在末尾）

好的标准（可验证）：

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

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

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

---

转换规则

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)
br 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)
br 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)
br 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
br dep add ralph-tui-002 ralph-tui-001

# US-003: UI story
br 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
br dep add ralph-tui-003 ralph-tui-002

---

同步变更

创建 beads 后，同步以导出为 JSONL（用于 Git 追踪）：

br sync --flush-only

此操作会将 SQLite 数据库导出到 .beads/issues.jsonl，以便进行版本控制。

---

输出位置

Beads 存储在：.beads/ 目录（SQLite 数据库 + JSONL 导出文件）

创建后，运行 ralph-tui：

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

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

ralph-tui 将：

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

---

创建 Beads 前的检查清单

• 已从 PRD 中提取质量门槛（如果缺少，则已询问用户）
• 每个故事都能在一次迭代中完成（规模足够小）
• 故事已按依赖关系排序（架构 → 后端 → UI）
• 每个 bead 的验收标准都已附加质量门槛
• UI 故事已包含浏览器验证（如果质量门槛中有要求）
• 验收标准可验证（不含模糊表述）
• 没有故事依赖后续故事（只依赖之前的故事）
• 创建 beads 后，已使用 br dep add 添加依赖
• 已运行 br sync --flush-only 以导出供 Git 追踪

---

与 beads（Go 版本）的区别

命令	beads（bd）	beads-rust（br）
创建	bd create	br create
依赖	bd dep add	br dep add
同步	bd sync	br sync --flush-only
关闭	bd close	br close
存储	.beads/beads.jsonl	.beads/*.db + JSONL 导出文件