ralph-tui-create-beads-rust：使用Rust CLI将PRD转换为可执行任务

ralph-tui-create-beads-rust by subsy/ralph-tui

587 周安装量

2,200 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/subsy/ralph-tui --skill ralph-tui-create-beads-rust

项目管理自动化 Rust

🇨🇳中文介绍

Ralph TUI - 创建 Beads (beads-rust)

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

注意： 此技能使用 beads-rust 的 br 命令。如果您安装的是原始 beads (bd)，请使用 ralph-tui-create-beads 技能。

任务说明

获取一个 PRD（markdown 文件或文本）并使用 br 命令创建 beads：

从 PRD 的"质量门"部分提取质量门
为功能创建一个史诗 bead
为每个用户故事创建子 beads（并附加质量门）
在 beads 之间设置依赖关系（模式 → 后端 → UI）
输出结果供 ralph-tui run --tracker beads-rust 使用

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

步骤 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]

关键： 始终对 HEREDOC 分隔符使用 <<'EOF'（单引号）。这可以防止 shell 解释描述中的反引号、$variables 和 ()。

故事规模：首要规则

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

ralph-tui 每次迭代都会生成一个新的代理实例，没有先前工作的记忆。如果一个故事太大，代理会在完成之前耗尽上下文。

规模合适的故事：

添加数据库列 + 迁移
在现有页面上添加 UI 组件
使用新逻辑更新服务器操作
向列表添加过滤器下拉菜单

规模过大（需要拆分这些）：

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

经验法则： 如果你不能用 2-3 句话描述这个变更，那就太大了。

故事排序：依赖优先

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

模式/数据库变更（迁移）
服务器操作 / 后端逻辑
使用后端的 UI 组件
聚合数据的仪表板/摘要视图

❌ UI 组件（依赖于尚不存在的模式）
❌ 模式变更

使用 `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。

在依赖项完成之前，将阻塞的 beads 显示为"已阻塞"
在其依赖项未完成时，永远不会选择 bead 执行
在处理 bead 时，在提示中包含依赖关系上下文

正确的依赖顺序：

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

验收标准：质量门 + 故事特定

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

来自 PRD 的故事特定标准（此故事完成的内容）
来自 PRD 质量门部分的质量门（附加在末尾）

好的标准（可验证）：

"向投资者表添加 investorType 列，默认值为 'cold'"
"过滤器下拉菜单选项：全部、冷、朋友"
"点击切换显示确认对话框"

不好的标准（模糊）：

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

首先从 PRD 提取质量门
每个用户故事 → 一个 bead
第一个故事：无依赖（创建基础）
后续故事：依赖于其前驱（UI 依赖于后端等）
优先级：基于依赖顺序，然后是文档顺序（0=关键，2=中等，4=待办）
所有故事：status: "open"
验收标准：故事标准 + 附加的质量门
UI 故事：同时附加 UI 特定门（浏览器验证）

如果 PRD 包含大型功能，请拆分它们：

"添加朋友外联跟踪，使用不同的消息传递"

US-001：向数据库添加 investorType 字段
US-002：向投资者列表 UI 添加类型切换
US-003：创建朋友特定的阶段进展逻辑
US-004：创建朋友消息模板
US-005：为朋友连接任务生成
US-006：按类型添加过滤器
US-007：更新新投资者表单
US-008：更新仪表板计数

每个都是一个可以独立完成和验证的聚焦变更。

# 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

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

处理指定史诗内的 beads（或选择最佳可用任务）
完成时关闭每个 bead
所有子项完成后关闭史诗
史诗完成后输出 <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 导出

🇺🇸English

Ralph TUI - Create Beads (beads-rust)

Converts PRDs to beads (epic + child tasks) for ralph-tui autonomous execution using beads-rust (br CLI).

Note: This skill uses the br command from beads-rust. If you have the original beads (bd) installed instead, use the ralph-tui-create-beads skill.

The Job

Take a PRD (markdown file or text) and create beads using br commands:

Extract Quality Gates from the PRD's "Quality Gates" section
Create an epic bead for the feature
Create child beads for each user story (with quality gates appended)
Set up dependencies between beads (schema → backend → UI)
Output ready for ralph-tui run --tracker beads-rust

Step 1: Extract Quality Gates

Look for the "Quality Gates" section in the 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

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.

Output Format

Beads use br create command with HEREDOC syntax to safely handle special characters:

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

CRITICAL: Always use <<'EOF' (single-quoted) for the HEREDOC delimiter. This prevents shell interpretation of backticks, $variables, and () in descriptions.

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.

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

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.

Story Ordering: Dependencies First

Stories execute in dependency order. Earlier stories must not depend on later ones.

Correct order:

Schema/database changes (migrations)
Server actions / backend logic
UI components that use the backend
Dashboard/summary views that aggregate data

Wrong order:

❌ UI component (depends on schema that doesn't exist yet)
❌ Schema change

Dependencies with `br dep add`

Use the br dep add command to specify which beads must complete first:

# 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

Syntax: br dep add <issue> <depends-on> — the issue depends on (is blocked by) depends-on.

ralph-tui will:

Show blocked beads as "blocked" until dependencies complete
Never select a bead for execution while its dependencies are open
Include dependency context in the prompt when working on a bead

Correct dependency order:

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

Acceptance Criteria: Quality Gates + Story-Specific

Each bead's description should include acceptance criteria with:

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

Good criteria (verifiable):

"Add investorType column to investor table with default 'cold'"
"Filter dropdown has options: All, Cold, Friend"
"Clicking toggle shows confirmation dialog"

Bad criteria (vague):

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

Conversion Rules

Extract Quality Gates from PRD first
Each user story → one bead
First story : No dependencies (creates foundation)
Subsequent stories : Depend on their predecessors (UI depends on backend, etc.)
Priority : Based on dependency order, then document order (0=critical, 2=medium, 4=backlog)
All stories : status: "open"
Acceptance criteria : Story criteria + quality gates appended
UI stories : Also append UI-specific gates (browser verification)

Splitting Large PRDs

If a PRD has big features, split them:

Original:

"Add friends outreach track with different messaging"

Split into:

US-001: Add investorType field to database
US-002: Add type toggle to investor list UI
US-003: Create friend-specific phase progression logic
US-004: Create friend message templates
US-005: Wire up task generation for friends
US-006: Add filter by type
US-007: Update new investor form
US-008: Update dashboard counts

Each is one focused change that can be completed and verified independently.

Example

Input 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

Output 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

Syncing Changes

After creating beads, sync to export to JSONL (for git tracking):

br sync --flush-only

This exports the SQLite database to .beads/issues.jsonl for version control.

Output Location

Beads are stored in: .beads/ directory (SQLite DB + JSONL export)

After creation, run 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 will:

Work on beads within the specified epic (or select the best available task)
Close each bead when complete
Close the epic when all children are done
Output <promise>COMPLETE</promise> when epic is done

Checklist Before Creating Beads

Extracted Quality Gates from PRD (or asked user if missing)
Each story is completable in one iteration (small enough)
Stories are ordered by dependency (schema → backend → UI)
Quality gates appended to every bead's acceptance criteria
UI stories have browser verification (if specified in Quality Gates)
Acceptance criteria are verifiable (not vague)
No story depends on a later story (only earlier stories)
Dependencies added with br dep add after creating beads
Ran br sync --flush-only to export for git tracking

Differences from beads (Go version)

Command	beads (`bd`)	beads-rust (`br`)
Create	`bd create`	`br create`
Dependencies	`bd dep add`	`br dep add`
Sync	`bd sync`	`br sync --flush-only`

Weekly Installs

587

Repository

subsy/ralph-tui

GitHub Stars

2.2K

First Seen

Jan 21, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

claude-code459

opencode192

codex140

cursor87

gemini-cli80

github-copilot77

Google Sheets 费用追踪器创建指南 - 使用 Google Workspace CLI 自动化记账

6,000 周安装