ralph-tui-create-json

Ralph TUI - JSON タスクの作成

PRD を prd.json 形式に変換し、ralph-tui による自律実行に対応します。

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

⚠️ 重要： 出力は「name」と「userStories」をルートレベルに持つ、フラットな JSON オブジェクトでなければなりません。コンテンツを「prd」オブジェクトでラップしたり、「tasks」配列を使用したりしないでください。詳しくは、以下の「スキーマのアンチパターン」セクションを参照してください。

---

作業内容

PRD（Markdown ファイルまたはテキスト）を受け取り、prd.json ファイルを作成します。

1. PRD の「Quality Gates」セクションから品質ゲートを抽出します
2. PRD からユーザーストーリーを解析します
3. 各ストーリーの受け入れ基準に品質ゲートを追加します
4. ストーリー間の依存関係を設定します
5. ralph-tui run --prd <path> で実行できる状態で出力します

---

ステップ 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 などの妥当なデフォルトを使用します。

---

出力形式

JSON ファイルは、ルートレベルにフラットなオブジェクトを持たなければなりません。

{
  "name": "[Project name from PRD or directory]",
  "branchName": "ralph/[feature-name-kebab-case]",
  "description": "[Feature description from PRD]",
  "userStories": [
    {
      "id": "US-001",
      "title": "[Story title]",
      "description": "As a [user], I want [feature] so that [benefit]",
      "acceptanceCriteria": [
        "Criterion 1 from PRD",
        "Criterion 2 from PRD",
        "pnpm typecheck passes",
        "pnpm lint passes"
      ],
      "priority": 1,
      "passes": false,
      "notes": "",
      "dependsOn": []
    },
    {
      "id": "US-002",
      "title": "[UI Story that depends on US-001]",
      "description": "...",
      "acceptanceCriteria": [
        "...",
        "pnpm typecheck passes",
        "pnpm lint passes",
        "Verify in browser using dev-browser skill"
      ],
      "priority": 2,
      "passes": false,
      "notes": "",
      "dependsOn": ["US-001"]
    }
  ]
}

---

重要：スキーマのアンチパターン（使用禁止）

以下のパターンは無効であり、検証エラーの原因になります。

❌ 誤り：「Wrapper」オブジェクト

{
  "prd": {
    "name": "...",
    "userStories": [...]
  }
}

これはすべてを「prd」オブジェクトでラップしています。このようにしないでください。「name」と「userStories」フィールドはルートレベルになければなりません。

❌ 誤り：「userStories」の代わりに「tasks」を使用

{
  "name": "...",
  "tasks": [...]
}

配列の名前は**「tasks」ではなく「userStories」**です。

❌ 誤り：複雑なネスト構造

{
  "metadata": {...},
  "overview": {...},
  "migration_strategy": {
    "phases": [...]
  }
}

PRD でフェーズ／マイルストーン／スプリントが説明されていても、これらを単一の「userStories」配列にまとめなければなりません。

❌ 誤り：「passes」の代わりに「status」を使用

{
  "userStories": [{
    "id": "US-001",
    "status": "open"  // WRONG!
  }]
}

未完了のストーリーには"passes": false、完了したストーリーには"passes": trueを使用します。

✅ 正しい形式：ルートレベルのフラットな構造

{
  "name": "Android Kotlin Migration",
  "branchName": "ralph/kotlin-migration",
  "userStories": [
    {"id": "US-001", "title": "Create Scraper interface", "passes": false, "dependsOn": []},
    {"id": "US-002", "title": "Implement WeebCentralScraper", "passes": false, "dependsOn": ["US-001"]}
  ]
}

---

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

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

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

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

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

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

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

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

---

dependsOn による依存関係

dependsOn 配列を使用して、先に完了していなければならないストーリーを指定します。

{
  "id": "US-002",
  "title": "Create API endpoints",
  "dependsOn": ["US-001"],  // Won't be selected until US-001 passes
  ...
}

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

• US-001 が完了するまで、US-002 を「ブロック中」と表示します
• US-001 が未完了の間は、US-002 を実行対象に選択しません
• US-002 の作業時に、プロンプトに「Prerequisites: US-001」を含めます

依存関係の正しい順序：

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

---

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

各ストーリーの受け入れ基準には、次の内容を含めます。

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

良い基準（検証可能）：

• 「tasks テーブルに、デフォルト値が 'open' のstatusカラムを追加する」
• 「フィルタードロップダウンに、All、Open、Closed の選択肢がある」
• 「削除をクリックすると確認ダイアログが表示される」

悪い基準（曖昧）：

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

---

変換ルール

1. まず PRD から品質ゲートを抽出します
2. 各ユーザーストーリー → 1 つの JSON エントリー
3. ID：連番（US-001、US-002 など）
4. 優先度：依存関係の順序に基づいて設定します（1 = 最高）
5. dependsOn：このストーリーが必要とするストーリー ID の配列
6. すべてのストーリー：passes: false、notes は空にします
7. branchName：機能名から導出し、kebab-case にして、ralph/ を先頭に付けます
8. 受け入れ条件：ストーリーの条件に品質ゲートを追加します
9. UI ストーリー：UI 固有のゲート（ブラウザーでの検証）も追加します

---

出力先

デフォルト：./tasks/prd.json（PRD の Markdown ファイルと同じ場所）

これにより、PRD 関連ファイルを tasks/ ディレクトリにまとめられます。

別のパスを指定することもできます。ralph-tui は次のコマンドでそのパスを使用します。

ralph-tui run --prd ./path/to/prd.json

---

例

入力 PRD：

# PRD: Task Priority System

Add priority levels to tasks.

## 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 priority field to database
**Description:** As a developer, I need to store task priority.

**Acceptance Criteria:**
- [ ] Add priority column: 1-4 (default 2)
- [ ] Migration runs successfully

### US-002: Display priority badge on task cards
**Description:** As a user, I want to see task priority at a glance.

**Acceptance Criteria:**
- [ ] Badge shows P1/P2/P3/P4 with colors
- [ ] Badge visible without hovering

### US-003: Add priority filter dropdown
**Description:** As a user, I want to filter tasks by priority.

**Acceptance Criteria:**
- [ ] Filter dropdown: All, P1, P2, P3, P4
- [ ] Filter persists in URL

出力 prd.json：

{
  "name": "Task Priority System",
  "branchName": "ralph/task-priority",
  "description": "Add priority levels to tasks",
  "userStories": [
    {
      "id": "US-001",
      "title": "Add priority field to database",
      "description": "As a developer, I need to store task priority.",
      "acceptanceCriteria": [
        "Add priority column: 1-4 (default 2)",
        "Migration runs successfully",
        "pnpm typecheck passes",
        "pnpm lint passes"
      ],
      "priority": 1,
      "passes": false,
      "notes": "",
      "dependsOn": []
    },
    {
      "id": "US-002",
      "title": "Display priority badge on task cards",
      "description": "As a user, I want to see task priority at a glance.",
      "acceptanceCriteria": [
        "Badge shows P1/P2/P3/P4 with colors",
        "Badge visible without hovering",
        "pnpm typecheck passes",
        "pnpm lint passes",
        "Verify in browser using dev-browser skill"
      ],
      "priority": 2,
      "passes": false,
      "notes": "",
      "dependsOn": ["US-001"]
    },
    {
      "id": "US-003",
      "title": "Add priority filter dropdown",
      "description": "As a user, I want to filter tasks by priority.",
      "acceptanceCriteria": [
        "Filter dropdown: All, P1, P2, P3, P4",
        "Filter persists in URL",
        "pnpm typecheck passes",
        "pnpm lint passes",
        "Verify in browser using dev-browser skill"
      ],
      "priority": 3,
      "passes": false,
      "notes": "",
      "dependsOn": ["US-002"]
    }
  ]
}

---

ralph-tui での実行

prd.json を作成した後：

ralph-tui run --prd ./tasks/prd.json

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

1. prd.json からストーリーを読み込みます
2. passes: false で、ブロックする依存関係がないストーリーのうち、優先度が最も高いものを選択します
3. ストーリーの詳細と受け入れ条件を含むプロンプトを生成します
4. エージェントを実行してストーリーを実装します
5. 完了時に passes: true に設定します
6. すべてのストーリーが合格するまで繰り返します

---

保存前のチェックリスト

• PRD から品質ゲートを抽出した（見つからない場合はユーザーに確認した）
• 各ストーリーを 1 回のイテレーションで完了できる
• ストーリーが依存関係の順に並んでいる（スキーマ → バックエンド → UI）
• 各ストーリーの dependsOn が正しく設定されている
• すべてのストーリーの受け入れ条件に品質ゲートが追加されている
• UI ストーリーにブラウザーでの検証が含まれている（品質ゲートで指定されている場合）
• 受け入れ条件が検証可能である（曖昧でない）
• 循環依存がない