ralph-tui-create-beads

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ralph TUI - Create Beads

Ralph TUI - 创建Beads

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

Note: This skill is bundled with ralph-tui's Beads tracker plugin. Future tracker plugins (Linear, GitHub Issues, etc.) will bundle their own task creation skills.

将PRD转换为适用于ralph-tui自主执行的beads（epic + 子任务）。

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

The Job

核心任务

Take a PRD (markdown file or text) and create beads in

.beads/beads.jsonl

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

接收PRD（markdown文件或文本）并在

.beads/beads.jsonl

中创建beads：

提取质量门禁：从PRD的“Quality Gates”部分提取相关内容
创建epic bead：为该功能创建一个epic类型的bead
创建子beads：为每个用户故事创建子bead，并附加质量门禁
设置依赖关系：在beads之间建立依赖（Schema → 后端 → UI）
生成可直接用于
```
ralph-tui run --tracker beads
```
的输出

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

---

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

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

---

Output Format

输出格式

Beads use

bd create

command with HEREDOC syntax to safely handle special characters:

bash

undefined

Beads使用

bd create

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

bash

undefined

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"

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]


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

---

bd 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解释描述中的反引号、`$变量`和`()`。

---

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.

“构建整个仪表盘” → 拆分为：Schema、查询、UI组件、筛选器
“添加认证功能” → 拆分为：Schema、中间件、登录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

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

正确顺序：

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

错误顺序：

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

Dependencies with

bd dep add

使用

bd dep add

设置依赖

Use the

bd dep add

command to specify which beads must complete first:

bash

undefined

使用

bd dep add

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

bash

undefined

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


**Syntax:** `bd 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)

---

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>` —— 前者依赖于后者（被后者阻塞）。

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

**正确的依赖顺序：**
1. Schema/数据库变更（无依赖）
2. 后端逻辑（依赖Schema）
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中提取Quality Gates内容
每个用户故事对应一个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

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

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

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

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

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

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"

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

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

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.

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

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.

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

Add dependency: US-003 depends on US-002

bd dep add ralph-tui-003 ralph-tui-002

---

bd dep add ralph-tui-003 ralph-tui-002

---

Output Location

输出位置

Beads are written to:

.beads/beads.jsonl

After creation, run ralph-tui:

bash

undefined

Beads将被写入：

.beads/beads.jsonl

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

bash

undefined

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


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
```
bd dep add
```
after creating beads

已从PRD中提取质量门禁（如果缺失则询问用户）
每个故事都能在一次迭代内完成（粒度足够小）
故事按依赖顺序排列（Schema → 后端 → UI）
每个bead的验收标准都附加了质量门禁
UI故事包含浏览器验证（如果Quality Gates中指定）
验收标准可验证（不模糊）
没有故事依赖于后续的故事（仅依赖前序故事）
创建beads后使用
```
bd dep add
```
添加了依赖关系 ",

ralph-tui-create-beads

Original

Translation

Ralph TUI - Create Beads

Ralph TUI - 创建Beads

The Job

核心任务

Step 1: Extract Quality Gates

步骤1：提取质量门禁

Quality Gates

Quality Gates

Output Format

输出格式

Create epic (link back to source PRD)

Create epic (link back to source PRD)

Create child bead (with quality gates in acceptance criteria)

Create child bead (with quality gates in acceptance criteria)

Story Size: The #1 Rule

故事粒度：首要规则

Right-sized stories:

合适的故事粒度：

Too big (split these):

粒度太大（需要拆分）：

Story Ordering: Dependencies First

故事排序：依赖优先

Dependencies with bd dep add

使用bd dep add设置依赖

Create the beads first

Create the beads first

Then add dependencies (issue depends-on blocker)

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: Friends Outreach

Quality Gates

Quality Gates

User Stories

User Stories

US-001: Add investorType field to investor table

US-001: Add investorType field to investor table

US-002: Add type toggle to investor list rows

US-002: Add type toggle to investor list rows

US-003: Filter investors by type

US-003: Filter investors by type

Create epic (link back to source PRD)

Create epic (link back to source PRD)

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

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

Acceptance Criteria

Acceptance Criteria

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

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

Acceptance Criteria

Acceptance Criteria

Add dependency: US-002 depends on US-001

Add dependency: US-002 depends on US-001

US-003: UI story

US-003: UI story

Acceptance Criteria

Acceptance Criteria

Add dependency: US-003 depends on US-002

Add dependency: US-003 depends on US-002

Output Location

输出位置

Work on a specific epic

Work on a specific epic

Or let it pick the best task automatically

Or let it pick the best task automatically

Checklist Before Creating Beads

Dependencies with
`bd dep add`

使用
`bd dep add`
设置依赖