ralph

Ralph PRD Converter

既存の PRD を prd.json に変換し、自律実行用の分離された Git ワークツリーを設定します。

---

作業内容

1. PRD（Markdown ファイルまたはテキスト）を受け取り、prd.json に変換します
2. Ralph が作業するための Git ワークツリーを作成します
3. ワークツリーに prd.json を保存し、進捗の追跡を初期化します

---

出力形式

{
  "project": "[Project Name]",
  "branchName": "ralph/[feature-name-kebab-case]",
  "description": "[Feature description from PRD title/intro]",
  "userStories": [
    {
      "id": "US-001",
      "title": "[Story title]",
      "description": "As a [user], I want [feature] so that [benefit]",
      "acceptanceCriteria": [
        "Criterion 1",
        "Criterion 2",
        "Typecheck passes"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}

---

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

各ストーリーは、Ralph の 1 回のイテレーション（1 つのコンテキストウィンドウ）で完了できる必要があります。

Ralph はイテレーションごとに新しい Amp インスタンスを起動し、前回の作業の記憶はありません。ストーリーが大きすぎると、LLM は完了前にコンテキストを使い切り、壊れたコードを生成します。

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

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

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

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

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

---

ストーリーの順序：依存関係を先に

ストーリーは優先順位順に実行されます。先行するストーリーが後続のストーリーに依存してはなりません。

正しい順序：

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

誤った順序：

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

---

受け入れ基準：検証可能であること

各基準は、曖昧なものではなく、Ralph が確認できるものでなければなりません。

良い基準（検証可能）：

• 「tasks テーブルに、デフォルト値が 'pending' の status カラムを追加する」
• 「フィルタードロップダウンに All、Active、Completed の選択肢がある」
• 「削除をクリックすると確認ダイアログが表示される」
• 「型チェックが通る」
• 「テストが通る（vitest-testing スキルを使用）」
• 「vitest-testing スキルを使用してテストを作成する」

悪い基準（曖昧）：

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

常に最後の基準として含める：

"Typecheck passes"

テスト可能なロジックを含むストーリーには、次も含めます：

"Tests pass (use vitest-testing skill)"

UI を変更するストーリーには、次も含めます：

"Verify in browser using dev-browser skill"

フロントエンドのストーリーは、視覚的に検証されるまで完了ではありません。Ralph は dev-browser スキルを使用してページを開き、UI を操作し、変更が正しく動作することを確認します。

---

変換ルール

1. 各ユーザーストーリーを 1 つの JSON エントリーにする
2. ID：連番（US-001、US-002 など）
3. 優先順位：依存関係の順序を優先し、その後にドキュメントの順序を適用
4. すべてのストーリー：passes: false と空の notes
5. branchName：機能名から導出し、ケバブケースにして ralph/ を先頭に付ける
6. 必ず追加する：「型チェックが通る」をすべてのストーリーの受け入れ基準に含める

---

大きな PRD の分割

PRD に大きな機能が含まれる場合は、分割してください。

元の内容：

「ユーザー通知システムを追加する」

分割後：

1. US-001：データベースに通知テーブルを追加する
2. US-002：通知を送信する通知サービスを作成する
3. US-003：ヘッダーに通知ベルアイコンを追加する
4. US-004：通知ドロップダウンパネルを作成する
5. US-005：既読にする機能を追加する
6. US-006：通知設定ページを追加する

それぞれが、個別に完了・検証できる、焦点を絞った変更です。

---

例

入力 PRD：

# Task Status Feature

Add ability to mark tasks with different statuses.

## Requirements
- Toggle between pending/in-progress/done on task list
- Filter list by status
- Show status badge on each task
- Persist status in database

出力 prd.json：

{
  "project": "TaskApp",
  "branchName": "ralph/task-status",
  "description": "Task Status Feature - Track task progress with status indicators",
  "userStories": [
    {
      "id": "US-001",
      "title": "Add status field to tasks table",
      "description": "As a developer, I need to store task status in the database.",
      "acceptanceCriteria": [
        "Add status column: 'pending' | 'in_progress' | 'done' (default 'pending')",
        "Generate and run migration successfully",
        "Typecheck passes",
        "Tests pass (use vitest-testing skill)"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    },
    {
      "id": "US-002",
      "title": "Display status badge on task cards",
      "description": "As a user, I want to see task status at a glance.",
      "acceptanceCriteria": [
        "Each task card shows colored status badge",
        "Badge colors: gray=pending, blue=in_progress, green=done",
        "Typecheck passes",
        "Verify in browser using dev-browser skill"
      ],
      "priority": 2,
      "passes": false,
      "notes": ""
    },
    {
      "id": "US-003",
      "title": "Add status toggle to task list rows",
      "description": "As a user, I want to change task status directly from the list.",
      "acceptanceCriteria": [
        "Each row has status dropdown or toggle",
        "Changing status saves immediately",
        "UI updates without page refresh",
        "Typecheck passes",
        "Verify in browser using dev-browser skill"
      ],
      "priority": 3,
      "passes": false,
      "notes": ""
    },
    {
      "id": "US-004",
      "title": "Filter tasks by status",
      "description": "As a user, I want to filter the list to see only certain statuses.",
      "acceptanceCriteria": [
        "Filter dropdown: All | Pending | In Progress | Done",
        "Filter persists in URL params",
        "Typecheck passes",
        "Verify in browser using dev-browser skill"
      ],
      "priority": 4,
      "passes": false,
      "notes": ""
    }
  ]
}

---

ワークツリーの設定

prd.json の生成後、Ralph が作業するための分離された Git ワークツリーを作成します。

1. ワークツリーを作成する

# From the repo root — create worktree with a new branch from main
git worktree add .claude/worktrees/ralph/<feature-name> -b ralph/<feature-name> main

<feature-name> はケバブケースの機能名です（branchName の ralph/ の後の部分）。

2. 依存関係をインストールし、環境変数を取得する

cd .claude/worktrees/ralph/<feature-name>
bun install
bun run env:pull

3. ファイルをワークツリーに保存する

prd.json をワークツリーの ralph ディレクトリに保存します：

.claude/worktrees/ralph/<feature-name>/scripts/ralph/prd.json

ワークツリーに progress.txt を作成して初期化します：

.claude/worktrees/ralph/<feature-name>/scripts/ralph/progress.txt

内容：

# Ralph Progress Log
Started: <current date>
---

4. Ralph の実行方法をユーザーに伝える

# From the main repo root
scripts/ralph/ralph-tree.sh ralph/<feature-name>

# With options
scripts/ralph/ralph-tree.sh ralph/<feature-name> --tool claude 15

---

保存前のチェックリスト

prd.json を作成する前に、以下を確認してください。

• 各ストーリーが1回のイテレーションで完了できる（十分に小さい）
• ストーリーが依存関係の順に並んでいる（スキーマからバックエンド、次にUI）
• すべてのストーリーに「型チェックが通る」という基準がある
• UI のストーリーに「dev-browser スキルを使ってブラウザーで確認する」という基準がある
• 受け入れ基準が検証可能である（曖昧でない）
• 後続のストーリーに依存するストーリーがない
• .claude/worktrees/ralph/<feature-name>/ にワークツリーが作成されている
• ワークツリーで bun install と bun run env:pull を実行している
• prd.json がワークツリーの scripts/ralph/ に保存されている
• progress.txt がワークツリーに初期化されている