tolimarchuk/goalbuddy

GoalBuddy – 長期間にわたるAI支援型コーディングタスクの軽量オーケストレーション層

何であるか

• GoalBuddyはnpm経由で配布されるCLIツールであり、OpenAI CodexやAnthropic Claude CodeなどのLLM駆動型コーディングアシスタントを使用する際、リポジトリ内に小さなファイルベースの「ボード」を作成して、大規模なコーディング目標を整理します。
• ボードは チャーター (goal.md)、状態ファイル (state.yaml)、ノート、サブゴールフォルダ、および隠しディレクトリ .goalbuddy-board を格納します。これらは通常のソースコードの隣に存在するため、作業を一時停止・再開、または異なるエージェント間でシームレスに引き継ぐ際にコンテキストを失うことがありません。

動作方法

1. 実行の開始 – npx goalbuddy を実行するとツールがインストールされ、/goal-prep コマンドが表示されます。
2. ゴール準備 – $goal-prep（またはClaude内での/goal-prep）を実行すると、ボードが作成され、LLMハーネスが次に実行すべき正確なコマンドが表示されます。
3. ディスパッチ – goalbuddy dispatch <board> --to codex|claude-code は現在のタスクのプロンプトをレンダリングし、選択されたLLM CLIを非表示で呼び出し、返された レシート（作業のYAML証明）をキャプチャします。また、gitを使ってファイル変更がタスクで宣言された allowed_files の範囲内に収まっているかを検証します。
4. 再開／引き継ぎ – npx goalbuddy resume はすべての有効なボードを一覧表示し、各ハーネスの継続コマンドを示すため、CodexからClaude（またはその逆）に切り替える際に計画を再作成する必要がありません。
5. 検証ループ – ワーカーが完了後、ジャッジエージェントがレシートをオラクル（テストスイート、デモ、ベンチマーク、または人間の承認）と照合して検証します。ボードの state.yaml が結果で更新され、「意図 → オラクル → 表面 → ループ → 証明」のサイクルがREADMEに記載された通り完了します。

重要な概念

• ボード – リポジトリ内に永続的に存在する、目標の表現。
• レシート（v1） – プレーンYAML形式で、ハーネスに依存しない、LLMが行った作業の記録。自動検証可能。
• スカウト／ジャッジ／ワーカー – リポジトリをマッピングし、安全な作業スライスを選定し、実行するための組み込みエージェント役割。
• オラクル – 目標が本当に達成されたことを示す具体的なシグナル（テスト、デモ、ベンチマークなど）。
• サブゴール – 範囲が限定された作業の分岐用の深さ1の子ボード。親ボードからリンクされる。

なぜ重要なのか

• ツール間の継続性 – ボードが単なるファイルであるため、Codexで開始した目標は、翌日Claude Codeで再開可能。同じボード上で複数ベンダーの実行も可能。
• 安全性と監査可能性 – レシートは保存され、gitで検証され、後でジャッジによって監査されるため、LLMによって生成された大規模なコード変更の明確な履歴が確保されます。
• 最小限の実行時リソース – 実行時に生成される唯一のアーティファクトは goalbuddy npmパッケージのみ。その他のすべての内容はリポジトリ内にあり、ツールは軽量でバージョン管理が容易です。

一般的な使用例

• ステップバイステップで検証が必要な大規模リファクタリング。
• 複数のLLM駆動タスク（バグ修正、ドキュメント更新、バージョンアップ）を調整する必要があるリリース準備。
• 証拠（テスト失敗、ログなど）をレシートとして記録する必要があるバグ調査。
• それぞれのLLM呼び出し間でコンテキストを失う可能性のある、マルチプロンプトプロジェクト。

インストールと基本コマンド

# インストールして新しいボードを開始
npx goalbuddy

# ゴールの準備（ボード作成、次のコマンドを表示）
$goal-prep   # またはClaude内での /goal-prep

# 特定のハーネスでアクティブなタスクを実行
npx goalbuddy dispatch docs/goals/my-feature --to codex

# 既存のボードを一覧表示して再開
npx goalbuddy resume

# Codexのインストールを検証
npx goalbuddy doctor --target codex --goal-ready

# 最新バージョンに更新
npx goalbuddy update

さらに学ぶには

• 完全なドキュメントはリポジトリの docs/ ディレクトリにあります（レシート仕様やリリースプロセスを含む）。
• 実際のビジュアルボードは http://goalbuddy.localhost:<port>/<slug>/ で開き、タスク、レシート、サブゴールのリアルタイム更新を確認できます。
• プロジェクトのウェブサイト: https://goalbuddy.dev

ライセンス – MIT（オープンソース。自由に使用・改変可）