ralph-tui-create-beads

Ralph TUI - Beads の作成

PRD を Beads（エピック＋子タスク）に変換し、ralph-tui による自律実行に使用します。

Note: このスキルは、ralph-tui の Beads トラッカープラグインに同梱されています。今後のトラッカープラグイン（Linear、GitHub Issues など）には、それぞれ独自のタスク作成スキルが同梱されます。

---

タスク

PRD（Markdown ファイルまたはテキスト）を受け取り、.beads/beads.jsonl に Beads を作成します。

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

---

ステップ 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 構文を使用して bd create コマンドを実行します。

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

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

重要： HEREDOC の区切り文字には、必ず <<'EOF'（シングルクォート付き）を使用してください。これにより、説明文に含まれるバッククォート、$variables、() がシェルによって解釈されるのを防げます。

---

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

各ストーリーは、ralph-tui の 1 回のイテレーション（エージェントのコンテキストウィンドウ 1 回分）で完了できなければなりません。

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

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

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

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

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

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

---

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

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

正しい順序：

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

誤った順序：

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

---

bd dep add による依存関係

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

# 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

構文： bd dep add <issue> <depends-on> — issue は depends-on に依存します（depends-on によってブロックされます）。

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

• 依存関係が完了するまで、ブロックされた Beads を「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 つの 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: 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

出力 beads：

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

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

## 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)
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
- [ ] 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
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.

## 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
bd dep add ralph-tui-003 ralph-tui-002

---

出力先

Beads は .beads/beads.jsonl に書き込まれます。

作成後、ralph-tui を実行します。

# 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 は次の処理を行います。

1. 指定された epic 内の bead に取り組みます（または、実行可能なタスクの中から最適なものを選択します）
2. 完了した bead をそれぞれクローズします
3. 子項目がすべて完了したら epic をクローズします
4. epic が完了すると <promise>COMPLETE</promise> を出力します

---

Beads 作成前のチェックリスト

• PRD から品質ゲートを抽出した（見つからない場合はユーザーに確認した）
• 各ストーリーを 1 回のイテレーションで完了できる（十分に小さい）
• ストーリーが依存関係の順に並んでいる（スキーマ → バックエンド → UI）
• すべての bead の受け入れ条件に品質ゲートを追加した
• UI ストーリーにブラウザーでの検証が含まれている（品質ゲートで指定されている場合）
• 受け入れ条件を検証できる（曖昧ではない）
• 後続のストーリーに依存するストーリーがない（先行するストーリーのみに依存する）
• bead 作成後、bd dep add で依存関係を追加した