ralph-tui-create-beads-rust

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ralph TUI - Create Beads (beads-rust)

Ralph TUI - 创建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.

使用beads-rust（

br

CLI）将PRD转换为beads（epic + 子任务），供ralph-tui自主执行。

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

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

接收PRD（markdown文件或文本）并使用

br

命令创建beads：

从PRD的"Quality Gates"部分提取质量门禁
为该功能创建一个epic bead
为每个用户故事创建子beads（附加质量门禁）
设置beads之间的依赖关系（架构 → 后端 → UI）
生成可直接用于
```
ralph-tui run --tracker beads-rust
```
的输出

Step 1: Extract Quality Gates

步骤1：提取质量门禁

Look for the "Quality Gates" section in the PRD:

markdown

undefined

在PRD中查找"Quality Gates"部分：

markdown

undefined

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`.

---

每个用户故事必须通过以下命令：

```
pnpm typecheck
```
- 类型检查
```
pnpm lint
```
- 代码检查

对于UI故事，还需包含：

使用dev-browser技能在浏览器中验证


提取：
- **通用门禁：** 适用于所有故事的命令（例如`pnpm typecheck`）
- **UI门禁：** 仅适用于UI故事的命令（例如浏览器验证）

**如果没有Quality Gates部分：** 询问用户需要通过哪些命令，或使用合理的默认值，如`npm run typecheck`。

---

Output Format

输出格式

Beads use

br create

command with HEREDOC syntax to safely handle special characters:

bash

undefined

Beads使用

br create

命令结合HEREDOC语法来安全处理特殊字符：

bash

undefined

Create epic (link back to source PRD)

创建epic（关联到源PRD）

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

br create --type=epic
--title="[功能名称]"
--description="$(cat <<'EOF' [来自PRD的功能描述] EOF )"
--external-ref="prd:./tasks/feature-name-prd.md"

Create child bead (with quality gates in acceptance criteria)

创建子bead（验收标准中包含质量门禁）

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.

---

br create
--parent=EPIC_ID
--title="[故事标题]"
--description="$(cat <<'EOF' [包含质量门禁的故事描述和验收标准] EOF )"
--priority=[1-4]


> **关键：** 始终使用`<<'EOF'`（单引号）作为HEREDOC分隔符。这可以防止shell解析描述中的反引号、`$变量`和`()`。

---

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.

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

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

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

添加数据库列 + 迁移
为现有页面添加UI组件
使用新逻辑更新服务器动作
为列表添加筛选下拉框

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.

"构建整个仪表盘" → 拆分为：架构、查询、UI组件、筛选器
"添加认证功能" → 拆分为：架构、中间件、登录UI、会话处理
"重构API" → 按每个端点或模式拆分为一个故事

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

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

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

正确顺序：

架构/数据库变更（迁移）
服务器动作/后端逻辑
使用后端的UI组件
聚合数据的仪表盘/汇总视图

错误顺序：

❌ UI组件（依赖尚未存在的架构）
❌ 架构变更

Dependencies with

br dep add

使用

br dep add

设置依赖

Use the

br dep add

command to specify which beads must complete first:

bash

undefined

使用

br dep add

命令指定哪些beads必须先完成：

bash

undefined

Create the beads first

先创建beads

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" ...

br create --parent=epic-123 --title="US-001: 添加架构" ... br create --parent=epic-123 --title="US-002: 创建API" ... br create --parent=epic-123 --title="US-003: 构建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:**
1. Schema/database changes (no dependencies)
2. Backend logic (depends on schema)
3. UI components (depends on backend)
4. Integration/polish (depends on UI)

---

br dep add ralph-tui-002 ralph-tui-001 # US-002依赖US-001 br dep add ralph-tui-003 ralph-tui-002 # US-003依赖US-002


**语法：** `br dep add <任务> <依赖任务>` —— 该任务依赖于（被）依赖任务阻塞。

ralph-tui会：
- 在依赖完成前，将被阻塞的beads标记为"blocked"
- 永远不会在依赖未完成时选择该bead执行
- 在处理bead时，将依赖上下文包含在提示中

**正确的依赖顺序：**
1. 架构/数据库变更（无依赖）
2. 后端逻辑（依赖架构）
3. UI组件（依赖后端）
4. 集成/优化（依赖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)

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

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

Good criteria (verifiable):

良好的标准（可验证）：

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

"为investor表添加
```
investorType
```
列，默认值为'cold'"
"筛选下拉框包含选项：全部、Cold、Friend"
"点击切换按钮显示确认对话框"

Bad criteria (vague):

糟糕的标准（模糊）：

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

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

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)

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

Splitting Large PRDs

拆分大型PRD

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.

如果PRD包含大型功能，需要拆分：

原始内容：

"添加好友拓展跟踪功能，包含不同的消息模板"

拆分后：

US-001: 为数据库添加investorType字段
US-002: 为投资者列表UI添加类型切换按钮
US-003: 创建好友特定的阶段推进逻辑
US-004: 创建好友消息模板
US-005: 为好友任务生成功能接线
US-006: 添加按类型筛选功能
US-007: 更新新投资者表单
US-008: 更新仪表盘统计

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

Example

示例

Input PRD:

markdown

undefined

输入PRD：

markdown

undefined

PRD: Friends Outreach

PRD: 好友拓展

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

每个用户故事必须通过以下命令：

```
pnpm typecheck
```
- 类型检查
```
pnpm lint
```
- 代码检查

对于UI故事，还需包含：

使用dev-browser技能在浏览器中验证

User Stories

用户故事

US-001: Add investorType field to investor table

US-001: 为investor表添加investorType字段

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

描述： 作为开发者，我需要将投资者分类为'cold'或'friend'。

验收标准：

添加investorType列：'cold' | 'friend'（默认'cold'）
生成并成功运行迁移

US-002: Add type toggle to investor list rows

US-002: 为投资者列表行添加类型切换按钮

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

描述： 作为Ryan，我希望直接从列表中切换投资者类型。

验收标准：

每行都有Cold | Friend切换按钮
切换时显示确认对话框
确认后：更新数据库中的类型

US-003: Filter investors by type

US-003: 按类型筛选投资者

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:**
```bash

描述： 作为Ryan，我希望筛选列表以仅查看好友或冷接触投资者。

验收标准：

筛选下拉框：全部 | Cold | Friend
筛选条件保留在URL参数中


**输出beads：**
```bash

Create epic (link back to source PRD)

创建epic（关联到源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"

br create --type=epic
--title="好友拓展跟踪"
--description="$(cat <<'EOF' 用于反馈收集的温暖拓展 EOF )"
--external-ref="prd:./tasks/friends-outreach-prd.md"

US-001: No deps (first - creates schema)

US-001: 无依赖（第一个故事 - 创建架构）

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'.

br create --parent=ralph-tui-abc
--title="US-001: 为investor表添加investorType字段"
--description="$(cat <<'EOF' 作为开发者，我需要将投资者分类为'cold'或'friend'。

Acceptance Criteria

验收标准

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

添加investorType列：'cold' | 'friend'（默认'cold'）
生成并成功运行迁移
pnpm typecheck通过
pnpm lint通过 EOF )"
--priority=1

US-002: UI story (gets browser verification too)

US-002: UI故事（还需浏览器验证）

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.

br create --parent=ralph-tui-abc
--title="US-002: 为投资者列表行添加类型切换按钮"
--description="$(cat <<'EOF' 作为Ryan，我希望直接从列表中切换投资者类型。

Acceptance Criteria

验收标准

Add dependency: US-002 depends on US-001

添加依赖：US-002依赖US-001

br dep add ralph-tui-002 ralph-tui-001

US-003: UI story

US-003: UI故事

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.

br create --parent=ralph-tui-abc
--title="US-003: 按类型筛选投资者"
--description="$(cat <<'EOF' 作为Ryan，我希望筛选列表以仅查看好友或冷接触投资者。

Acceptance Criteria

验收标准

Add dependency: US-003 depends on US-002

添加依赖：US-003依赖US-002

br dep add ralph-tui-003 ralph-tui-002

---

br dep add ralph-tui-003 ralph-tui-002

---

Syncing Changes

同步变更

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

bash

br sync --flush-only

This exports the SQLite database to

.beads/issues.jsonl

for version control.

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

bash

br sync --flush-only

这会将SQLite数据库导出到

.beads/issues.jsonl

以进行版本控制。

Output Location

输出位置

Beads are stored in:

.beads/

directory (SQLite DB + JSONL export)

After creation, run ralph-tui:

bash

undefined

Beads存储在：

.beads/

目录（SQLite数据库 + JSONL导出）

创建完成后，运行ralph-tui：

bash

undefined

Work on a specific epic

处理特定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:
1. Work on beads within the specified epic (or select the best available task)
2. Close each bead when complete
3. Close the epic when all children are done
4. Output `<promise>COMPLETE</promise>` when epic is done

---

ralph-tui run --tracker beads-rust


ralph-tui会：
1. 处理指定epic中的beads（或选择最佳可用任务）
2. 完成后关闭每个bead
3. 所有子bead完成后关闭epic
4. 当epic完成时输出`<promise>COMPLETE</promise>`

---

Checklist Before Creating Beads

创建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

从PRD中提取了质量门禁（如果缺失则询问用户）
每个故事都能在一次迭代内完成（足够小）
故事按依赖顺序排列（架构 → 后端 → UI）
质量门禁附加到每个bead的验收标准中
UI故事包含浏览器验证（如果Quality Gates中指定）
验收标准可验证（不模糊）
没有故事依赖后续故事（仅依赖前面的故事）
创建beads后使用
```
br dep add
```
添加了依赖
运行
```
br sync --flush-only
```
以导出用于git跟踪

Differences from beads (Go version)

与beads（Go版本）的差异

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`
Close	`bd close`	`br close`
Storage	`.beads/beads.jsonl`	`.beads/*.db` + JSONL export

命令	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导出

ralph-tui-create-beads-rust

Original

Translation

Ralph TUI - Create Beads (beads-rust)

Ralph TUI - 创建Beads（beads-rust）

The Job

任务内容

Step 1: Extract Quality Gates

步骤1：提取质量门禁

Quality Gates

Quality Gates

Output Format

输出格式

Create epic (link back to source PRD)

创建epic（关联到源PRD）

Create child bead (with quality gates in acceptance criteria)

创建子bead（验收标准中包含质量门禁）

Story Size: The #1 Rule

故事规模：首要规则

Right-sized stories:

合适规模的故事：

Too big (split these):

过大的故事（需要拆分）：

Story Ordering: Dependencies First

故事排序：依赖优先

Dependencies with br dep add

使用br dep add设置依赖

Create the beads first

先创建beads

Then add dependencies (issue depends-on blocker)

然后添加依赖（任务依赖于前置任务）

Acceptance Criteria: Quality Gates + Story-Specific

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

Good criteria (verifiable):

良好的标准（可验证）：

Bad criteria (vague):

糟糕的标准（模糊）：

Conversion Rules

转换规则

Splitting Large PRDs

拆分大型PRD

Example

示例

PRD: Friends Outreach

PRD: 好友拓展

Quality Gates

Quality Gates

User Stories

用户故事

US-001: Add investorType field to investor table

US-001: 为investor表添加investorType字段

US-002: Add type toggle to investor list rows

US-002: 为投资者列表行添加类型切换按钮

US-003: Filter investors by type

US-003: 按类型筛选投资者

Create epic (link back to source PRD)

创建epic（关联到源PRD）

US-001: No deps (first - creates schema)

US-001: 无依赖（第一个故事 - 创建架构）

Acceptance Criteria

验收标准

US-002: UI story (gets browser verification too)

US-002: UI故事（还需浏览器验证）

Acceptance Criteria

验收标准

Add dependency: US-002 depends on US-001

添加依赖：US-002依赖US-001

US-003: UI story

US-003: UI故事

Acceptance Criteria

验收标准

Add dependency: US-003 depends on US-002

添加依赖：US-003依赖US-002

Syncing Changes

同步变更

Output Location

输出位置

Work on a specific epic

处理特定epic

Or let it pick the best task automatically

Dependencies with
`br dep add`

使用
`br dep add`
设置依赖