ralph-tui-create-beads-rust

用途

该技能面向拥有 PRD（markdown 文件或文本）并希望用 ralph-tui 进行自主执行的场景，把 PRD 转化为 beads（一个 epic 加若干子任务），使用 beads-rust 的 br 命令行工具。注意：如果安装的是原版 beads（bd），应改用 ralph-tui-create-beads 技能。创建出的 bead 可直接供 ralph-tui run --tracker beads-rust 使用。

主要能力

提取质量门禁：从 PRD 的“Quality Gates”章节读取命令，区分为适用于所有故事的通用门禁（如 pnpm typecheck、pnpm lint）与仅适用于 UI 故事的 UI 门禁（如在浏览器中验证）。若 PRD 没有该章节，则询问用户应通过哪些命令，或使用合理默认值（如 npm run typecheck）。
创建 epic：用 br create --type=epic 为特性建立 epic，并通过 --external-ref 链接回源 PRD。
创建子 bead：为每个用户故事创建子 bead，验收标准中追加质量门禁。
设置依赖：用 br dep add 指定先后依赖，ralph-tui 会把被阻塞的 bead 显示为“blocked”，在依赖未完成前不会选中执行，并在提示中携带依赖上下文。

使用方式

beads 通过 br create 配合 HEREDOC 语法创建，以安全处理特殊字符。关键要求：始终使用 <<'EOF'（单引号）作为 HEREDOC 分隔符，防止 shell 解释描述中的反引号、$变量和圆括号。

创建 epic 示例：

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

创建子 bead 示例：

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

添加依赖：

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。

创建完成后同步导出以便 Git 跟踪：

br sync --flush-only

beads 存放于 .beads/ 目录（SQLite 数据库 + JSONL 导出）。之后可运行：

# 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 会在指定 epic 内工作（或自动选择最佳可用任务），完成后关闭每个 bead，所有子任务完成后关闭 epic，并在 epic 完成时输出 <promise>COMPLETE</promise>。

故事大小与顺序规则

每个故事必须能在一次 ralph-tui 迭代内完成。ralph-tui 每次迭代都会启动全新的智能体实例，不记得之前的工作；故事过大时，智能体会在完成前耗尽上下文。合适大小示例：添加数据库列与迁移、在既有页面添加 UI 组件、更新服务端 action 逻辑、给列表添加筛选下拉。过大需拆分的示例：“构建整个仪表盘”“添加认证”“重构 API”。经验法则：若无法用 2-3 句话描述改动，就说明太大。

故事按依赖顺序执行，前置故事不得依赖后续故事。正确顺序：schema/数据库变更 → 服务端 action/后端逻辑 → 使用后端的 UI 组件 → 聚合数据的仪表盘/汇总视图。转换规则：先提取质量门禁；每个用户故事对应一个 bead；第一个故事无依赖；后续故事依赖其前置；优先级依据依赖顺序再依文档顺序（0=critical，2=medium，4=backlog）；所有故事状态为 "open"；验收标准为故事标准加追加的质量门禁；UI 故事额外追加浏览器验证门禁。

验收标准应可验证。好的示例：“在 investor 表添加 investorType 列，默认 'cold'”“筛选下拉选项为 All、Cold、Friend”“点击切换显示确认对话框”。差的示例：“工作正常”“用户能轻松完成 X”“良好的 UX”“处理边界情况”。

适用场景

已写好 PRD 并希望交给 ralph-tui 自主执行时；需要把大特性拆分为可独立完成与验证的多个用户故事时；希望用依赖关系控制执行顺序（schema → backend → UI）时。

限制

仅适用于 ralph-tui 执行与 beads-rust（br）环境；若使用原版 beads（bd），应改用其他技能。命令差异对照：创建 bd create vs br create；依赖 bd dep add vs br dep add；同步 bd sync vs br sync --flush-only；关闭 bd close vs br close；存储 .beads/beads.jsonl vs .beads/*.db + JSONL export。若 PRD 缺少 Quality Gates 章节，技能会询问或使用默认命令。创建 beads 前应完成检查清单：已提取质量门禁、每个故事可在一次迭代完成、故事按依赖排序、质量门禁已追加至每个 bead、UI 故事含浏览器验证、验收标准可验证、无故事依赖后续故事、依赖已通过 br dep add 添加、已运行 br sync --flush-only。

技能介绍

用途

主要能力

使用方式

故事大小与顺序规则

适用场景

限制