ralph-tui-create-beads-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 を作成します。

1. PRD の「Quality Gates」セクションから品質ゲートを抽出します
2. 機能のエピック Bead を作成します
3. 各ユーザーストーリーの子 Bead を作成します（品質ゲートを追加します）
4. Bead 間の依存関係を設定します（スキーマ → バックエンド → UI）
5. ralph-tui run --tracker beads-rust ですぐに実行できる形式で出力します

---

ステップ 1：品質ゲートの抽出

PRD の「Quality Gates」セクションを確認します。

## 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 ストーリーのみに適用されるコマンド（例：ブラウザーでの検証）

「Quality Gates」セクションがない場合： どのコマンドを通す必要があるかユーザーに確認するか、npm run typecheck のような適切な既定値を使用します。

---

出力形式

Beads では、特殊文字を安全に扱えるように HEREDOC 構文を使った br create コマンドを使用します。

# 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'（シングルクォート付き）を使用してください。これにより、説明内のバッククォート、$variables、() がシェルによって解釈されるのを防げます。

---

ストーリーのサイズ：最重要ルール

各ストーリーは、ralph-tui の 1 回のイテレーション（エージェントのコンテキストウィンドウ 1 つ分ほど）で完了できる必要があります。

ralph-tui はイテレーションごとに新しいエージェントインスタンスを起動し、前回の作業の記憶はありません。ストーリーが大きすぎると、エージェントは完了前にコンテキストを使い切ります。

適切なサイズのストーリー：

• データベースのカラムとマイグレーションを追加する
• 既存ページに UI コンポーネントを追加する
• 新しいロジックでサーバーアクションを更新する
• リストにフィルタードロップダウンを追加する

大きすぎるストーリー（分割してください）：

• 「ダッシュボード全体を構築する」→ スキーマ、クエリー、UI コンポーネント、フィルターに分割します
• 「認証を追加する」→ スキーマ、ミドルウェア、ログイン UI、セッション処理に分割します
• 「API をリファクタリングする」→ エンドポイントまたはパターンごとに 1 つのストーリーに分割します

目安： 変更内容を 2～3 文で説明できない場合は、大きすぎます。

---

ストーリーの順序：依存関係を優先する

ストーリーは依存関係の順に実行されます。先行するストーリーが後続のストーリーに依存してはいけません。

正しい順序：

1. スキーマ／データベースの変更（マイグレーション）
2. サーバーアクション／バックエンドロジック
3. バックエンドを使用する UI コンポーネント
4. データを集約するダッシュボード／サマリービュー

誤った順序：

1. ❌ UI コンポーネント（まだ存在しないスキーマに依存している）
2. ❌ スキーマの変更

---

br dep add による依存関係の設定

br dep add コマンドを使って、先に完了する必要がある Bead を指定します。

# 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 に依存します（つまり、depends-on によってブロックされます）。

ralph-tui は次のように動作します。

• 依存関係が完了するまで、ブロックされている Bead を「blocked」として表示します
• 依存関係が未完了の間、その Bead を実行対象として選択しません
• Bead の作業時に、プロンプトに依存関係のコンテキストを含めます

正しい依存関係の順序：

1. スキーマ／データベースの変更（依存関係なし）
2. バックエンドロジック（スキーマに依存）
3. UI コンポーネント（バックエンドに依存）
4. 統合／仕上げ（UI に依存）

---

受け入れ基準：品質ゲート＋ストーリー固有の基準

各 Bead の説明には、次の受け入れ基準を含めます。

1. PRD に記載されたストーリー固有の基準（このストーリーで実現する内容）
2. PRD の「Quality Gates」セクションに記載された品質ゲート（末尾に追加）

良い基準（検証可能）：

• 「investor テーブルに、デフォルト値が 'cold' の investorType カラムを追加する」
• 「フィルタードロップダウンの選択肢が All、Cold、Friend である」
• 「トグルをクリックすると確認ダイアログが表示される」

悪い基準（曖昧）：

• ❌ 「正しく動作する」
• ❌ 「ユーザーが X を簡単に実行できる」
• ❌ 「優れた UX」
• ❌ 「エッジケースに対応する」

---

変換ルール

1. まず PRD から品質ゲートを抽出する
2. 各ユーザーストーリーを 1 つのビードにする
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: 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

---

変更の同期

ビードを作成したら、JSONL にエクスポートするために同期します（Git で追跡するため）。

br sync --flush-only

これにより、SQLite データベースが .beads/issues.jsonl にエクスポートされ、バージョン管理できるようになります。

---

出力先

ビードは .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

ralph-tui は次の処理を行います。

1. 指定されたエピック内のビードに取り組む（または、利用可能なタスクから最適なものを選択する）
2. 完了した各ビードをクローズする
3. すべての子タスクが完了したら、エピックをクローズする
4. エピックが完了すると <promise>COMPLETE</promise> を出力する

---

ビードを作成する前のチェックリスト

• PRD から品質ゲートを抽出した（見つからない場合はユーザーに確認した）
• 各ストーリーを 1 回のイテレーションで完了できる（十分に小さい）
• ストーリーが依存関係の順序で並んでいる（スキーマ → バックエンド → UI）
• すべてのビードの受け入れ基準に品質ゲートを追加した
• UI ストーリーにブラウザーでの検証が含まれている（品質ゲートで指定されている場合）
• 受け入れ基準が検証可能である（曖昧ではない）
• 後続のストーリーに依存するストーリーがない（依存先は前のストーリーのみ）
• ビード作成後、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 エクスポート