ralph

Ralph 機能のセットアップ

依存関係を持つ Ralph 対応タスクを作成する、対話型の機能計画です。

---

作業内容

2 つのモードがあります：

モード 1：新しい機能

1. 機能について対話する — 明確化のための質問をします
2. 小さなタスクに分割する — それぞれを 1 回のイテレーションで完了できるようにします
3. task_list タスクを作成する — dependsOn を持つ親タスクとサブタスクを作成します
4. Ralph ファイルをセットアップする — 親 ID を保存し、progress.txt をリセットします

モード 2：既存のタスク

1. 既存の親タスクを見つける — 検索するか、ユーザーに指定してもらいます
2. 構造を確認する — サブタスクに適切な dependsOn が設定されているか確認します
3. Ralph ファイルをセットアップする — 親 ID を parent-task-id.txt に保存します
4. 状況を表示する — どのタスクが着手可能か、完了済みか、ブロックされているかを示します

どちらのモードが必要か、ユーザーに尋ねてください：

Are you:
1. Starting a new feature (I'll help you plan and create tasks)
2. Using existing tasks (I'll set up Ralph to run them)

---

ステップ 1：機能を理解する

まず、ユーザーに機能について尋ねてください。決めつけずに、必ず尋ねてください：

What feature are you building?

次に、明確化のための質問をします：

• ユーザーにとっての目標は何ですか？
• コードベースのどの部分に影響しますか？（データベース、UI、API など）
• 従うべき既存のパターンはありますか？
• 完成時にどのようになっていればよいですか？

タスクに分割するのに十分な詳細が得られるまで質問を続けてください。

---

ステップ 2：タスクに分割する

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

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

適切なサイズのタスク：

• データベースのカラムとマイグレーションを追加する
• 単一の UI コンポーネントを作成する
• 1 つのサーバーアクションを実装する
• 既存のリストにフィルターを追加する
• 1 つのモジュールのテストを書く

大きすぎるタスク（分割してください）：

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

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

---

ステップ 3：依存関係に基づいて順序を決める

タスクは dependsOn に基づいて実行されます。依存先のタスクを開始する前に、先行タスクを完了する必要があります。

一般的な順序：

1. スキーマ／データベースの変更（マイグレーション）
2. サーバーアクション／バックエンドロジック
3. バックエンドを使用する UI コンポーネント
4. 統合テスト／E2E テスト

dependsOn を使ってこれを表現します：

Task 1: Schema (no dependencies)
Task 2: Server action (dependsOn: [task-1])
Task 3: UI component (dependsOn: [task-2])
Task 4: Tests (dependsOn: [task-3])

互いに依存しない並列タスクには、同じ依存関係を設定できます。

---

ステップ 4：タスクを作成する

まず、親タスクを作成します：

task_list create
  title: "[Feature Name]"
  description: "[One-line description of the feature]"
  repoURL: "https://github.com/snarktank/untangle"

返されたタスク ID を保存してください — サブタスクの作成に必要です。

次に、parentID と dependsOn を指定してサブタスクを作成します：

task_list create
  title: "[Task title - action-oriented]"
  description: "[Detailed description with:
    - What to implement
    - Files to create/modify
    - Acceptance criteria
    - How to verify (typecheck, tests, browser)]"
  parentID: "<parent-task-id>"
  dependsOn: ["<previous-task-id>"]  // omit for first task
  repoURL: "https://github.com/snarktank/untangle"

タスクの説明形式：

今後の Ralph イテレーションが、背景情報なしで作業を引き継げるような説明を書いてください：

Implement category name to ID mapping for expenses.

**What to do:**
- Create function mapExpenseCategoryNameToId(name, isChildExpense)
- Query item_category table with category_type filter
- Add alias mapping for common synonyms (rent → Rent or Mortgage)

**Files:**
- workflows/tools/upsert-expense.ts

**Acceptance criteria:**
- Function returns category ID for valid names
- Returns null for unknown categories
- npm run typecheck passes

**Notes:**
- Follow pattern from upsert-income.ts
- EXPENSE type for family, CHILD_EXPENSE for child

---

ステップ 5：Ralph ファイルをセットアップする

すべてのタスクを作成した後、「Final Setup (Required for Both Modes)」セクションの共通セットアップ手順を実行してください。

これにより、次のことが確実に行われます：

• 親タスク ID が scripts/ralph/parent-task-id.txt に保存されます
• 前回の progress.txt に内容がある場合、アーカイブされます
• Codebase Patterns を保持した、新しい progress.txt が作成されます

---

ステップ 6：セットアップを確認する

作成した内容をユーザーに示します：

✅ Ralph is ready!

**Parent task:** [title] (ID: [id])

**Subtasks:**
1. [Task 1 title] - no dependencies
2. [Task 2 title] - depends on #1
3. [Task 3 title] - depends on #2
...

**To start Ralph:** Say "run ralph" or "start the loop" - I'll use handoff to execute the first ready task, and each task will hand off to the next until complete.

---

## Mode 2: Setting Up Existing Tasks

If the user already has tasks created, help them set up Ralph to run them.

### Find the parent task:

**First, check if a parent task is already saved:**

```bash
cat scripts/ralph/parent-task-id.txt

このファイルが存在し、タスク ID が含まれている場合は、それを使用してください！タスクを取得して有効性を確認します：

task_list action: "get", taskID: "<id-from-file>"

保存済みの親タスクがない場合に限り、ユーザーに尋ねてください：

What's the parent task? You can give me:
- The task ID directly
- A search term and I'll find it
- Or say "list recent" to see recent tasks

タスクを検索する場合は、コンテキストのオーバーフローを避けるため、必ず limit を使用してください：

task_list list
  repoURL: "https://github.com/snarktank/untangle"
  limit: 10

サブタスクの存在を確認する：

親 ID が分かったら、サブタスクを確認します（必ず limit を使用してください）：

task_list list
  parentID: "<parent-task-id>"
  limit: 10

サブタスクが見つからない場合、親タスク自体が作業内容であり、コンテナではない可能性があります。次のように尋ねてください：

This task has no subtasks. Is this:
1. A parent task with subtasks I should find differently?
2. The actual work task (I should create it as a parent with this as the first subtask)?

依存関係を確認する：

サブタスクを確認し、次の点を検証します：

• dependsOn は正しく設定されていますか？
• 循環依存はありませんか？
• Ralph が開始できるよう、最初のタスク（複数可）に依存関係が設定されていませんか？

依存関係が不足している場合は、修正を提案してください：

These tasks don't have dependencies set. Should I:
1. Add dependencies based on their order?
2. Leave them parallel (Ralph picks any ready task)?

Ralph ファイルをセットアップする：

以下の「Final Setup (Required for Both Modes)」セクションにある共通セットアップ手順を実行してください。

状況を表示する：

✅ Ralph is ready to use existing tasks!

**Parent task:** [title] (ID: [id])

**Status:**
- ✅ Completed: 3 tasks
- 🔄 Ready to work: 2 tasks  
- ⏳ Blocked: 5 tasks (waiting on dependencies)

**Next task Ralph will pick:**
[Task title] - [brief description]

**To start Ralph:** Say "run ralph" or "start the loop"

---

## Final Setup (Required for Both Modes)

**ALWAYS run these steps after creating tasks OR setting up existing tasks:**

### 1. Save parent task ID:

```bash
echo "<parent-task-id>" > scripts/ralph/parent-task-id.txt

保存されたことを確認してください：

cat scripts/ralph/parent-task-id.txt

2. progress.txt をアーカイブする必要があるか確認します：

現在の progress.txt を読み込みます：

cat scripts/ralph/progress.txt

次の場合はアーカイブします：

• ヘッダー以外の内容がある（以前の機能開発で得た知見）
• 以前の機能が現在の機能と異なる

アーカイブコマンド：

DATE=$(date +%Y-%m-%d)
FEATURE="previous-feature-name-here"
mkdir -p scripts/ralph/archive/$DATE-$FEATURE
cp scripts/ralph/progress.txt scripts/ralph/archive/$DATE-$FEATURE/
echo "Archived to scripts/ralph/archive/$DATE-$FEATURE/"

3. progress.txt をリセットします：

前回の実行から役立つ Codebase Patterns を保持してから、リセットします：

cat > scripts/ralph/progress.txt << 'EOF'
# Ralph Progress Log
Started: [current date]

## Codebase Patterns
[Copy any patterns from previous run that are still relevant]
---
EOF

4. セットアップが完了していることを確認します：

# Confirm parent ID is saved
cat scripts/ralph/parent-task-id.txt

# Confirm progress.txt is reset
head -10 scripts/ralph/progress.txt

# List subtasks to confirm they exist
# (use task_list list with parentID)

4 つすべての手順を完了してから、Ralph を実行できます。

---

各タスクの受け入れ基準

各タスクの説明には、検証可能な受け入れ基準を必ず含めてください：

良い基準（検証可能）：

• 「投資家テーブルに、デフォルト値が 'cold' の investorType 列を追加する」
• 「フィルターのドロップダウンに All、Cold、Friend の選択肢がある」
• 「npm run typecheck が成功する」
• 「npm test -- path/to/test.ts が成功する」

悪い基準（曖昧）：

• ❌ 「正しく動作する」
• ❌ 「優れた UX」
• ❌ 「エッジケースに対応する」

必ず含める：

npm run typecheck passes

テスト可能なロジックを含むタスクの場合：

npm test passes

UI／ブラウザーのタスクの場合：

機能テスト（外観ではなく動作を確認する場合）：

Use Chrome DevTools MCP with take_snapshot to read page content (NOT screenshots)

• take_snapshot は、Ralph が読み取って検証できるテキスト形式で a11y ツリーを返します
• take_screenshot は、Ralph が機能チェックに使用できない画像を返します
• スクリーンショットは、視覚的な外観や使い勝手をテストする場合にのみ使用します

視覚テスト（外観を確認する場合）：

Use take_screenshot to capture and verify visual appearance

---

会話例

ユーザー： 法務エージェントに経費追跡機能を追加するため、Ralph をセットアップしてください

アシスタント： どのような機能を開発していますか？

ユーザー： Grace（法務チャットエージェント）が、会話中にユーザーが言及した経費を作成、更新、削除できるようにしたいです。

アシスタント： 了解しました。法務エージェント向けの経費 upsert ツールですね。いくつか質問があります：

1. パターンとして参考にできる、法務エージェントの既存ツールはありますか？
2. 経費には異なる種類（家族向けと子ども向け）がありますか？
3. 経費の一覧表示も必要ですか、それとも CRUD だけでよいですか？
4. タスクの完了処理は必要ですか？

ユーザー： upsert-income.ts を参考にしてください。はい、家族向けと子ども向けの経費があり（テーブルは別です）。はい、一覧表示も必要です。APP_EXPENSES_ENTERED タスクを完了にしてください。

アシスタント： 承知しました。次のように分けることを提案します：

1. ツールの骨組みを作成 - Zod スキーマと基本構造
2. カテゴリーマッピング - 「家賃」などの名前をカテゴリー ID にマッピング
3. 金額の解析 - 通貨形式に対応し、$0 を許可
4. 重複検出 - 作成前に確認
5. 家族向け経費の作成 - expense テーブルに挿入
6. 子ども向け経費の作成 - child_expense テーブルに挿入
7. 更新アクション - 既存の経費を変更
8. 削除アクション - 経費を削除
9. 一覧表示アクション - 合計額とともにすべての経費を表示
10. タスク完了処理 - APP_EXPENSES_ENTERED を完了にする
11. ツールの登録 - 法務チャットのワークフローに追加
12. UI の進捗インジケーター - ツール使用中に進捗を表示
13. ユニットテスト - ヘルパー関数をテスト
14. E2E テスト - チャットインターフェース経由でテスト

この内容でよいですか？タスクの追加や削除はありますか？

ユーザー： よさそうです。タスクを作成してください

アシスタント： ［親タスクを作成してから、依存関係を設定したサブタスクを作成し、parent-task-id.txt を保存します］

✅ Ralph の準備ができました！

親タスク： Legal Agent Expense Upsert Tool（ID: task-abc123）

サブタスク： 依存関係付きで 14 件のタスクを作成しました

開始するには： 「run ralph」または「start the loop」と入力してください

---

Ralph が完了するまでの流れ

すべてのサブタスクが完了すると：

1. Ralph は 親タスク を completed にします
2. 「✅ ビルドが完了しました - すべてのタスクが終了しました！」と報告します
3. 完了した内容を要約します

重要： Ralph は、コンテキストのオーバーフローを避けるため、タスクの照会時に limit: 5 を使用します。サブタスクが多い場合は、複数回のイテレーションに分けて処理します。

---

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

• 機能について話し合い、スコープを把握した
• 各タスクを1回のイテレーションで完了できる（十分に小さい）
• タスクを依存関係の順に並べた（スキーマ → バックエンド → UI → テスト）
• すべてのタスクの説明に「npm run typecheck passes」が含まれている
• UI タスクの説明にブラウザーでの検証が含まれている
• Ralph がコンテキストなしで実装できるだけの詳細が説明に記載されている
• 親タスク ID を scripts/ralph/parent-task-id.txt に保存した
• progress.txt に内容があった場合、前回の実行をアーカイブした

---

フェーズ 2：実行ループ

セットアップが完了すると、Ralph は自律ループを実行し、タスクを1つずつ実装します。

---

ループのワークフロー

0. 親タスク ID を取得する

まず、この機能の範囲を定める親タスク ID を読み込みます。

cat scripts/ralph/parent-task-id.txt

このファイルが存在しない場合は、作業対象の親タスクをユーザーに確認してください。

新機能かどうかを確認します： 親タスク ID を scripts/ralph/progress.txt のヘッダーにある ID と比較します。異なる場合（または progress.txt が存在しない場合）は、新機能です。progress.txt をリセットします。

# Build Progress Log
Started: [today's date]
Feature: [parent task title]

## Codebase Patterns
(Patterns discovered during this feature build)

---

これにより、各機能をまっさらな状態で開始できます。progress.txt は、現在の機能専用の短期メモリです。

1. 対応可能なタスクを確認する（入れ子になった階層に対応）

タスク階層には複数のレベル（親 → コンテナー → リーフタスク）がある場合があります。以下の方法ですべての子孫タスクを見つけます。

ステップ 1：リポジトリ内のすべてのタスクを取得する

task_list action: "list", repoURL: "<repo-url>", ready: true, status: "open", limit: 10

重要： タスク数が多い場合にコンテキストがあふれないよう、必ず limit（5～10）を指定してください。

ステップ 2：子孫タスクの集合を作成する 親タスク ID から始めて、子孫にあたるすべてのタスクを集めます。

1. parentID が親タスク ID と一致するタスク（直接の子）を見つける
2. 見つかった各子タスクについて、その子タスクを再帰的に検索する
3. 子孫が見つからなくなるまで続ける

ステップ 3：作業可能なタスクに絞り込む 子孫タスクの集合から、次の条件を満たすタスクを選びます。

• ready: true（すべての依存関係が満たされている）
• status: "open"
• リーフタスク（子タスクがない）—実際の作業項目

最重要： 他のタスクをグループ化するためだけに存在するコンテナタスクはスキップしてください。あるタスクを parentID とする他のタスクがある場合、そのタスクはコンテナタスクです。

2. 対応可能なタスクがない場合

すべての子孫タスクが完了しているか確認します。

• repoURL: "<repo-url>" を指定して task_list list を照会します（ready によるフィルターなし）。
• 手順 1 と同じ再帰的な方法で、子孫タスクの集合全体を作成します。
• 子孫タスクの集合に含まれるすべてのリーフタスクが completed の場合：
  1. progress.txt をアーカイブします。

     DATE=$(date +%Y-%m-%d)
     FEATURE="feature-name-here"
     mkdir -p scripts/ralph/archive/$DATE-$FEATURE
     mv scripts/ralph/progress.txt scripts/ralph/archive/$DATE-$FEATURE/
     

  2. 空のテンプレートで新しい progress.txt を作成する
  3. parent-task-id.txt をクリアする：echo "" > scripts/ralph/parent-task-id.txt
  4. コミットする：git add scripts/ralph && git commit -m "chore: archive progress for [feature-name]"
  5. 親タスクを completed にする
  6. 停止し、「✅ ビルド完了 — すべてのタスクが終了しました！」と報告する
• ブロックされているタスクがある場合：どのタスクが、なぜブロックされているかを報告する

3. 対応可能なタスクがある場合

次のタスクを選択します：

• 直前に完了した作業に関連するタスク（同じモジュール／領域、依存する作業）を優先する
• それまでのコンテキストがない場合は、最初の対応可能なタスクを選ぶ

タスクを実行します：

次の目標を指定して handoff ツールを使用します。

Implement and verify task [task-id]: [task-title].

[task-description]

FIRST: Read scripts/ralph/progress.txt - check the "Codebase Patterns" section for important context from previous iterations.

When complete:

1. Run quality checks: `npm run typecheck` and `npm test`
   - If either fails, FIX THE ISSUES and re-run until both pass
   - Do NOT proceed until quality checks pass

2. Update AGENTS.md files if you learned something important:
   - Check for AGENTS.md in directories where you edited files
   - Add learnings that future developers/agents should know (patterns, gotchas, dependencies)
   - This is LONG-TERM memory - things anyone editing this code should know
   - Do NOT add task-specific details or temporary notes

3. Update progress.txt (APPEND, never replace) - this is SHORT-TERM memory for the current feature:

[Date] - [Task Title]

スレッド：[current thread URL] タスク ID：[task-id]

• 実装した内容
• 変更したファイル
• 今後のイテレーションに向けた学び：
  • 発見したパターン
  • 遭遇した注意点
  • 役立つコンテキスト

---

4. If you discovered a reusable pattern for THIS FEATURE, add it to the `## Codebase Patterns` section at the TOP of progress.txt

5. Commit all changes with message: `feat: [Task Title]`

6. Mark task as completed: `task_list action: "update", taskID: "[task-id]", status: "completed"`

7. Invoke the ralph skill to continue the loop

---

進捗ファイルの形式

# Build Progress Log
Started: [date]
Feature: [feature name]
Parent Task: [parent-task-id]

## Codebase Patterns
(Patterns discovered during this feature build)

---

## [Date] - [Task Title]
Thread: https://ampcode.com/threads/[thread-id]
Task ID: [id]
- What was implemented
- Files changed
- **Learnings for future iterations:**
  - Patterns discovered
  - Gotchas encountered
---

注： 親タスク ID が異なる新機能を開始する際は、progress.txt を完全にリセットしてください。長期的な学びは progress.txt ではなく、AGENTS.md ファイルに記録してください。

---

タスクの発見

作業中に以下を見つけた場合は、積極的に新しいタスクを作成してください。

• 失敗するテストやテストの不足
• リファクタリングが必要なコード
• 不足しているエラーハンドリング
• ドキュメントの不足
• コード内の TODO や FIXME
• ビルド／lint の警告
• パフォーマンスの問題

すぐに task_list action: "create" を使用してください。適切な dependsOn の関係を設定してください。

---

ブラウザーでの検証

UI タスクでは、適切な検証方法を指定してください。

機能テスト（見た目ではなく動作を確認）：

Use agent-browser with snapshot -i to read page content

• agent-browser snapshot -i は、検証可能な参照情報付きのインタラクティブ要素を返します
• 用途：ボタンの存在、テキストの表示、フォームの動作
• 例：ボタンの存在を確認するには、agent-browser snapshot -i | grep "Submit" を実行します

ビジュアルテスト（見た目を確認）：

Use agent-browser screenshot to capture and verify visual appearance

• agent-browser screenshot tmp/result.png はスクリーンショットを保存します
• 用途：レイアウト、色、スタイル、アニメーション

---

品質要件

タスクを完了としてマークする前に、以下を確認してください。

• npm run typecheck が成功すること
• npm test が成功すること
• 変更がコミットされていること
• 進捗が記録されていること

---

停止条件

実行可能なタスクがなく、すべてのタスクが完了したら、以下を行ってください。

1. 「✅ ビルドが完了しました。すべてのタスクが終了しました！」と出力します
2. 完了した作業を要約します

---

重要な注意事項

• タスクを一覧表示する際は、依存関係が満たされているタスクのみを取得するため、必ず ready: true を指定してください
• コンテキストの過剰な消費を避けるため、タスクの一覧表示では必ず limit: 5-10 を指定してください
• 引き継ぎのたびに、クリーンなコンテキストで新しいスレッドが開始されます
• Progress.txt は各イテレーション間のメモリです。常に最新の状態に保ってください
• コンテキストの継続性を高めるため、直前に完了した作業と同じ領域のタスクを優先してください
• 引き継ぎの目標には、progress.txt の更新、コミット、このスキルの再呼び出しの指示を必ず含めてください