ultragoal

Ultragoal は、短い依頼を順序付けられた一連の目標に分割し、開始・チェックポイント・ブロッカー・失敗のイベントを永続的な追記専用台帳に記録します。また、計画と併せて Claude Code の `/goal` スラッシュコマンドをどのように進めるか、アクティブな Claude エージェントに伝えます。シェルから Claude の `/goal` の状態を変更するものではなく、変更することもできません。永続的なリポジトリの状態を保存し、アクティブなエージェントがセッション内で対応する必要がある、モデル向けの引き継ぎ情報を出力します。

<Use_When>

• 複数の Claude セッションやワークツリーにまたがるウルトラゴールを、永続的かつリポジトリ内で追跡したい場合
• 複数の順序付けられた「ストーリー」と、試行回数やストーリーごとの証拠が必要な規模の作業である場合
• 最終完了の条件として ai-slop-cleaner、検証、$code-review を必須にしたい場合
• セッションを再起動しても進捗が失われないよう、アクティブな Claude /goal の指示と台帳を連携させたい場合 </Use_When>

<Do_Not_Use_When>

• タスクが小規模な変更 1 件である場合 — 代わりに直接委任するか、ralph を使用してください
• アシスタントにシェルから /goal 自体を実行させたい場合 — それはできません。omc ultragoal は成果物を書き込み、引き継ぎテキストを出力するだけです
• 実行ループのない計画のみの成果物が必要な場合 — 代わりに plan を使用してください </Do_Not_Use_When>

<Why_This_Exists> Claude Code の /goal はセッション単位の Stop フックです。条件が満たされるまでセッションの停止をブロックし、成功すると自動的に解除されます。これは単一セッションでの実行に適した仕組みですが、セッション間で状態を保持できず、それだけでは最終レビューのゲートも強制できません。omc ultragoal は永続的な計画、台帳、ゲート機能を追加します。これにより、長期にわたる複数ステップの取り組みでも、セッションの再起動、新しいワークツリー、レビューの反復を経て状態を維持しながら、Claude /goal を活用してアクティブなエージェントの集中を保てます。 </Why_This_Exists>

<How_To_Use>

omc が PATH にないプラグインのみのインストール環境では、以下のコマンドと生成される引き継ぎ情報にある omc の部分を oh-my-claudecode.js に置き換えるか、 node <plugin-root>/bin/oh-my-claudecode.js を使用してください。

1. 短い依頼から計画を作成します。

   omc ultragoal create-goals --brief-file plan.md
   

   または、ストーリーを明示して作成します。

   omc ultragoal create-goals --brief "ship the migration" \
     --goal "Schema::Add new columns" \
     --goal "Backfill::Backfill rows in batches" \
     --goal "Cutover::Drop old columns and switch reads"
   

   デフォルトのモードは aggregate です（1 つの Claude /goal で実行全体をカバーします）。 各ストーリーに独自の /goal を設定する場合は、--claude-goal-mode per-story を渡してください。

   複数リポジトリのワークスペース／並列セッション： 同じワークスペース内の複数の Claude セッションで /ultragoal を同時に実行する必要がある場合は、--plan-id <stable-id> または --auto-plan-id を渡して、計画を共有の単一計画パスではなく .omc/ultragoal/plans/{planId}/ に書き込んでください。 このフラグを指定しないと、2 つのセッションが目標を作成した際に互いの内容を上書きしてしまいます。 --auto-plan-id は、依頼のタイトルから {epochMs}-{slug} を生成します。その後、 同じセッション内のすべてのサブコマンドに、同じ --plan-id <id> を引き継いでください。 必要に応じて omc ultragoal list-plans を使用すると、利用可能な planId を一覧表示できます。

</How_To_Use> 2. 次のストーリーを開始（または再開）します：

omc ultragoal complete-goals [<goal-id>]

ゴール ID を指定しない場合は、アクティブなストーリーを再開するか、最初の保留中ストーリーを開始するという既定の動作が維持されます。ゴール ID を指定すると、OMC はその名前の対象となるストーリーだけを対象とします（保留中のストーリーは順番を入れ替えて開始できます）。別のストーリーに切り替えることはありません。別のストーリーが進行中の場合、不明な ID の場合、完了済みまたはレビューでブロックされたストーリーの場合、あるいは --retry-failed を指定せずに失敗したストーリーを指定した場合は、状態を変更せずに拒否されます。指定したストーリーが進行中の場合、試行回数を変更せずに再開します。これにより、モデル向けの引き継ぎ情報が出力されます。アクティブな Claude エージェントはこれを読み、次の操作を行う必要があります：

• このセッションでネイティブの Claude /goal を設定します。スタンドアロンの Claude Code では、シェルもエージェントも設定できないため、ユーザーに /goal <aggregate objective> を入力するよう依頼し、完了を待ちます。--claude-goal-json（下記）は台帳の整合のみを行い、アクティブな /goal が確認されるまでツール呼び出しをブロックする PreToolUse /goal ガードの要件を満たしません。
• ストーリーに取り組みます。
• ストーリーが完了したら（最後のストーリーの場合は、品質ゲート全体を通過した後に）、アクティブな /goal の状態のスナップショットを共有し、checkpoint を呼び出します。

3. ストーリーをチェックポイントに記録します：

   omc ultragoal checkpoint --goal-id G001-... --status complete \
     --evidence "tests/files/PR evidence" \
     --claude-goal-json '{"goal":{"objective":"...","status":"active"}}'
   

   最後のストーリーでは、aiSlopCleaner、verification、codeReview の証拠（すべて問題なし）を含む --quality-gate-json も渡します。

4. 最終レビューで問題が見つかった場合は、完了としてマークしないでください。ブロッカーを記録します：

   omc ultragoal record-review-blockers --goal-id G00X-... \
     --title "Resolve final code-review blockers" \
     --objective "Fix the listed review findings and rerun final gates" \
     --evidence "<the review findings>" \
     --claude-goal-json '{"goal":{"objective":"...","status":"active"}}'
   

   これにより、新しいブロッカーストーリーが追加され、Claude /goal はアクティブなままになります。

5. 状態はいつでも確認できます：

   omc ultragoal status
   

</How_To_Use>

<Important_Limitations>

• シェルから Claude Code の /goal 状態を呼び出したり変更したりすることはできません。omc ultragoal は永続的な成果物のみを保存し、アクティブな Claude エージェントがセッション中に読み取って実行する手順を出力します。
• --claude-goal-json で渡されるスナップショットは、アクティブな /goal 状態を示すモデル提供の証拠です。OMC は、プランで期待される目標および台帳イベントとの文面上の整合性を検証しますが、Claude /goal の状態を独自に確認することはできません。これらは PreToolUse /goal ガードの要件を満たしません。このガードには、ホストから注入されたスナップショット、またはユーザーがセッション中に設定したネイティブの /goal が必要です。
• Claude /goal スラッシュコマンドの名前や構成が変更された場合、変更が必要なのは引き継ぎ文面だけです。整合処理のロジックはコマンド名に依存しません。 </Important_Limitations>

並列セッションに関する注意事項

• 複数リポジトリのワークスペースアンカー： 親ディレクトリに .omc-workspace マーカーを配置すると、複数のサブリポジトリにまたがるセッションで 1 つの .omc/ を共有できます。解決順序：OMC_STATE_DIR > .omc-workspace > git > cwd。docs/REFERENCE.md を参照してください。
• セッション ID の取得元： CLI コンテキストでは環境変数 OMC_SESSION_ID が優先され、フックコンテキストではフックペイロードの data.session_id が優先されます。
• プラン ID（該当する場合）： 同じワークスペース内で 2 つの実行を行うと、共有プラン成果物で競合します。異なるセッション ID を使用するか（フックペイロードの session_id は Claude Code セッションごとにすでに分離されています）、--plan-id を渡して並列の ultragoal 実行を別々の台帳に保持してください。
• 並列実行の判定： 対応しています（各セッションはそれぞれのセッション単位の状態を書き込みます）