Communitygithub.com

Ralph TUI - 建立 Beads (beads-rust)

將 PRD 轉換為 beads (epic + 子任務),以便使用 beads-rust (br CLI) 在 ralph-tui 中自動執行。當你有一份 PRD 並想將 ralph-tui 搭配 beads-rust 作為任務來源時使用。

Ralph TUI - 建立 Beads (beads-rust) 是什麼?

這個技能會將產品需求文件 (PRD) 轉換成 beads-rust 格式的結構化任務,供 ralph-tui 自主執行。它會分析 PRD,從需求文件中提取品質閘門 (Quality Gates),為功能建立一個 epic bead,並為每個使用者故事建立子 beads。每個 bead 的驗收標準會合併故事特定的標準和品質閘門,並根據依賴順序設定優先權 (schema → 後端 → UI)。該技能會強制要求故事必須足夠小,以便在單一 ralph-tui 迭代中完成,並使用 `br dep add` 指令設定明確的依賴關係。支援所有使用 beads-rust 的 ralph-tui 設定,並提供完整的轉換規則、範例和使用 `br sync --flush-only` 進行同步的檢查清單。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ComeOnOliver/skillshub/tree/HEAD/skills/aiskillstore/marketplace/subsy/ralph-tui-create-beads-rust

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Ralph TUI - 建立 Beads (beads-rust) 是做什麼的?

將 PRD 轉換為 beads(epic + 子任務),供 beads-rust(br CLI)在 ralph-tui 中自主執行。

注意: 此技能使用 beads-rust 的 br 指令。如果你安裝的是原始 beads(bd),請改用 ralph-tui-create-beads 技能。


任務

取得 PRD(Markdown 檔案或文字),並使用 br 指令建立 beads:

  1. 從 PRD 的「品質閘門」章節提取品質閘門
  2. 為該功能建立一個 epic bead
  3. 為每個使用者故事建立 子 beads(並附加品質閘門)
  4. 設定 beads 之間的 依賴關係(schema → 後端 → UI)
  5. 輸出供 ralph-tui run --tracker beads-rust 使用

第一步:提取品質閘門

在 PRD 中尋找「品質閘門」章節:

## 品質閘門

每個使用者故事都必須通過以下指令:
- `pnpm typecheck` - 型別檢查
- `pnpm lint` - 程式碼風格檢查

對於 UI 故事,也需包含:
- 使用 dev-browser 技能在瀏覽器中驗證

提取:

  • 通用閘門: 適用於所有故事的指令(例如 pnpm typecheck)
  • UI 閘門: 僅適用於 UI 故事的指令(例如瀏覽器驗證)

如果沒有品質閘門章節: 詢問使用者應該通過哪些指令,或使用合理的預設值,例如 npm run typecheck。


輸出格式

Beads 使用 br create 指令搭配 HEREDOC 語法,以安全處理特殊字元:

# 建立 epic(連結回原始 PRD)
br create --type=epic \
  --title="[功能名稱]" \
  --description="$(cat <<'EOF'
[來自 PRD 的功能描述]
EOF
)" \
  --external-ref="prd:./tasks/feature-name-prd.md"

# 建立子 bead(驗收標準中包含品質閘門)
br create \
  --parent=EPIC_ID \
  --title="[故事標題]" \
  --description="$(cat <<'EOF'
[故事描述,驗收標準 INCLUDING 品質閘門]
EOF
)" \
  --priority=[1-4]

關鍵: 務必使用 <<'EOF'(單引號)作為 HEREDOC 分隔符。這可以防止 shell 將描述中的反引號、$variables 和 () 解譯。


故事大小:首要規則

每個故事必須能在單一 ralph-tui 迭代中完成(約一個 agent 上下文視窗的大小)。

ralph-tui 每次迭代會產生全新的 agent 實例,且不保留先前工作的記憶。如果故事太大,agent 會在完成前就用完上下文。

大小合適的故事:

  • 新增資料庫欄位 + 遷移
  • 在現有頁面新增 UI 元件
  • 使用新邏輯更新 server action
  • 在清單中新增篩選下拉選單

太大的故事(請拆分):

  • 「建立整個儀表板」→ 拆分為:schema、查詢、UI 元件、篩選器
  • 「新增驗證功能」→ 拆分為:schema、中介軟體、登入 UI、session 處理
  • 「重構 API」→ 拆分為每個端點或模式一個故事

經驗法則: 如果你無法用 2-3 句話描述變更,那就是太大了。


故事排序:依賴優先

故事會依照依賴順序執行。較早的故事不應依賴較晚的故事。

正確順序:

  1. Schema/資料庫變更(遷移)
  2. Server actions / 後端邏輯
  3. 使用後端的 UI 元件
  4. 彙總資料的儀表板/摘要檢視

錯誤順序:

  1. ❌ UI 元件(依賴尚不存在的 schema)
  2. ❌ Schema 變更

使用 br dep add 設定依賴關係

使用 br dep add 指令指定哪些 beads 必須先完成:

# 先建立 beads
br create --parent=epic-123 --title="US-001:新增 schema" ...
br create --parent=epic-123 --title="US-002:建立 API" ...
br create --parent=epic-123 --title="US-003:建置 UI" ...

# 然後新增依賴關係(issue depends-on blocker)
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 <issue> <depends-on> — issue 依賴於(被 blocked by)depends-on。

ralph-tui 會:

  • 將被阻擋的 beads 顯示為「blocked」,直到依賴項完成
  • 在依賴項仍為開啟狀態時,絕不選取該 bead 執行
  • 在處理 bead 的提示中包含依賴上下文

正確的依賴順序:

  1. Schema/資料庫變更(無依賴)
  2. 後端邏輯(依賴 schema)
  3. UI 元件(依賴後端)
  4. 整合/打磨(依賴 UI)

驗收標準:品質閘門 + 故事特定

每個 bead 的描述應包含驗收標準,包括:

  1. 來自 PRD 的故事特定標準(此故事完成的事項)
  2. 來自 PRD 品質閘門章節的品質閘門(附加在結尾)

良好的標準(可驗證):

  • 「在 investor 資料表中新增 investorType 欄位,預設值為 'cold'」
  • 「篩選下拉選單具有選項:全部、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:好友推廣

新增將投資者標記為「好友」以進行溫暖推廣的功能。

## 品質閘門

每個使用者故事都必須通過以下指令:
- `pnpm typecheck` - 型別檢查
- `pnpm lint` - 程式碼風格檢查

對於 UI 故事,也需包含:
- 使用 dev-browser 技能在瀏覽器中驗證

## 使用者故事

### US-001:在 investor 資料表中新增 investorType 欄位
**描述:** 作為開發者,我需要將投資者分類為 'cold' 或 'friend'。

**驗收標準:**
- [ ] 新增 investorType 欄位:'cold' | 'friend'(預設 'cold')
- [ ] 生成並執行遷移成功

### US-002:在投資者清單列中新增類型切換開關
**描述:** 作為 Ryan,我想直接從清單切換投資者類型。

**驗收標準:**
- [ ] 每列都有 Cold | Friend 切換開關
- [ ] 切換時顯示確認對話框
- [ ] 確認後:更新資料庫中的類型

### US-003:按類型篩選投資者
**描述:** 作為 Ryan,我想篩選清單,只查看好友或 cold 的投資者。

**驗收標準:**
- [ ] 篩選下拉選單:全部 | Cold | Friend
- [ ] 篩選條件保留在 URL 參數中

輸出的 beads:

# 建立 epic(連結回原始 PRD)
br create --type=epic \
  --title="好友推廣追蹤" \
  --description="$(cat <<'EOF'
為 Deck 回饋進行溫暖推廣
EOF
)" \
  --external-ref="prd:./tasks/friends-outreach-prd.md"

# US-001:無依賴(第一個 - 建立 schema)
br create --parent=ralph-tui-abc \
  --title="US-001:在 investor 資料表中新增 investorType 欄位" \
  --description="$(cat <<'EOF'
作為開發者,我需要將投資者分類為 'cold' 或 'friend'。

## 驗收標準
- [ ] 新增 investorType 欄位:'cold' | 'friend'(預設 'cold')
- [ ] 生成並執行遷移成功
- [ ] pnpm typecheck 通過
- [ ] pnpm lint 通過
EOF
)" \
  --priority=1

# US-002:UI 故事(也包含瀏覽器驗證)
br create --parent=ralph-tui-abc \
  --title="US-002:在投資者清單列中新增類型切換開關" \
  --description="$(cat <<'EOF'
作為 Ryan,我想直接從清單切換投資者類型。

## 驗收標準
- [ ] 每列都有 Cold | Friend 切換開關
- [ ] 切換時顯示確認對話框
- [ ] 確認後:更新資料庫中的類型
- [ ] pnpm typecheck 通過
- [ ] pnpm lint 通過
- [ ] 使用 dev-browser 技能在瀏覽器中驗證
EOF
)" \
  --priority=2

# 新增依賴關係:US-002 依賴 US-001
br dep add ralph-tui-002 ralph-tui-001

# US-003:UI 故事
br create --parent=ralph-tui-abc \
  --title="US-003:按類型篩選投資者" \
  --description="$(cat <<'EOF'
作為 Ryan,我想篩選清單,只查看好友或 cold 的投資者。

## 驗收標準
- [ ] 篩選下拉選單:全部 | Cold | Friend
- [ ] 篩選條件保留在 URL 參數中
- [ ] pnpm typecheck 通過
- [ ] pnpm lint 通過
- [ ] 使用 dev-browser 技能在瀏覽器中驗證
EOF
)" \
  --priority=3

# 新增依賴關係:US-003 依賴 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:

# 處理特定 epic
ralph-tui run --tracker beads-rust --epic ralph-tui-abc

# 或讓它自動選取最佳任務
ralph-tui run --tracker beads-rust

ralph-tui 會:

  1. 處理指定 epic 中的 beads(或選取最佳可用任務)
  2. 完成時關閉每個 bead
  3. 所有子任務完成時關閉 epic
  4. 輸出 <promise>COMPLETE</promise> 表示 epic 已完成

建立 Beads 前的檢查清單

  • 已從 PRD 提取品質閘門(如果缺少則已詢問使用者)
  • 每個故事可在一次迭代中完成(夠小)
  • 故事已按依賴順序排序(schema → 後端 → UI)
  • 品質閘門已附加到每個 bead 的驗收標準中
  • UI 故事已包含瀏覽器驗證(如果品質閘門中有指定)
  • 驗收標準是可驗證的(不模糊)
  • 沒有故事依賴於較晚的故事(僅依賴較早的故事)
  • 建立 beads 後已使用 br dep add 新增依賴關係
  • 已執行 br sync --flush-only 以匯出供 git 追蹤

與 beads(Go 版本)的差異

指令beads (bd)beads-rust (br)
建立bd createbr create
依賴關係bd dep addbr dep add
同步bd syncbr sync --flush-only
關閉bd closebr close
儲存.beads/beads.jsonl.beads/*.db + JSONL 匯出

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ComeOnOliver/skillshub

Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Use when the user wants to build a presentation, convert a PPT/PPTX to web, or create slides for a talk/pitch. Helps non-designers discover their aesthetic through visual exploration rather than abstract choices.

ComeOnOliver/skillshub

Next.js 16+ 和 Turbopack — 增量打包、文件系统缓存、开发速度,以及何时使用 Turbopack 与 webpack。

ComeOnOliver/skillshub

SwiftUI architecture patterns, state management with @Observable, view composition, navigation, performance optimization, and modern iOS/macOS UI best practices.

ComeOnOliver/skillshub

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio, video), and create real time alerts for events from live streams or desktop capture.

ComeOnOliver/skillshub

AI-assisted video editing workflows for cutting, structuring, and augmenting real footage. Covers the full pipeline from raw capture through FFmpeg, Remotion, ElevenLabs, fal.ai, and final polish in Descript or CapCut. Use when the user wants to edit video, cut footage, create vlogs, or build video content.

ComeOnOliver/skillshub

Next.js 15 애플리케이션을 위한 프론트엔드 개발 가이드라인. React 19, TypeScript, Shadcn/ui, Tailwind CSS를 사용한 모던 패턴. Server Components, Client Components, App Router, 파일 구조, Shadcn/ui 컴포넌트, 성능 최적화, TypeScript 모범 사례 포함. 컴포넌트, 페이지, 기능 생성, 데이터 페칭, 스타일링, 라우팅, 프론트엔드 코드 작업 시 사용.

ComeOnOliver/skillshub

Provides Tamagui patterns for config v4, compiler optimization, styled context, and cross-platform styling. Must use when working with Tamagui projects (tamagui.config.ts, @tamagui imports).

ComeOnOliver/skillshub

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

ComeOnOliver/skillshub

Create high-converting, visually distinctive landing pages. Use when building marketing pages, product launches, SaaS homepages, or any single-page conversion-focused website. Guides section-by-section composition with anti-AI-slop principles.

ComeOnOliver/skillshub

Auto-loaded context for Portfolio Buddy 2 development. Use for ANY task involving: React 19 development, TypeScript, portfolio analysis features, metrics calculations, trading strategy comparison, or working with the Portfolio Buddy 2 codebase. Contains tech stack, known issues, and architectural constraints.

ComeOnOliver/skillshub

Next.js development tooling via MCP. Inspect routes, components, build info, and debug Next.js apps. Use when working on Next.js applications, debugging routing, or inspecting app structure. NOT for general React or non-Next.js projects.

ComeOnOliver/skillshub

Implement UI using Shadcn MCP (atoms/theme) and 21st.dev MCP (complex sections). Use when adding buttons, layouts, or generating landing pages.

ComeOnOliver/skillshub

A conceptual skill for building an API client in Next.js that handles JWT tokens

ComeOnOliver/skillshub

Best practices and patterns for Next.js App Router, Server Actions, and Routing in this project.

ComeOnOliver/skillshub

The Design System, Theme, and UX rules for the Physical AI Hub.

ComeOnOliver/skillshub

Comprehensive frontend development skill for building modern, performant web applications using ReactJS, NextJS, TypeScript, Tailwind CSS. Includes component scaffolding, performance optimization, bundle analysis, and UI best practices. Use when developing frontend features, optimizing performance, implementing UI/UX designs, managing state, or reviewing frontend code.

ComeOnOliver/skillshub

This document captures learnings from fixing keyboard navigation issues when floating components (Select, DropdownMenu, Popover) have CSS open/close animations.

ComeOnOliver/skillshub

Build Next.js 16 applications with correct patterns and distinctive design. Use when creating pages, layouts, dynamic routes, upgrading from Next.js 15, or implementing proxy.ts. Covers breaking changes (async params/searchParams, Turbopack, cacheComponents) and frontend aesthetics. NOT when building non-React or backend-only applications.

ComeOnOliver/skillshub

Comprehensive Framer Motion animation library for React. Covers motion components, variants, gestures, page transitions, and scroll animations. Use when adding animations to React/Next.js applications.

ComeOnOliver/skillshub

Build interfaces that resonate, not just render. This skill enforces bold, intentional

相關技能