<Use_When>
- 使用者想要一個持久化的、與倉庫原生整合的方式，來跨多個 Claude 會話或工作樹追蹤一個超目標
- 工作量大到需要多個有序的「故事」，並包含嘗試次數和每個故事的證據
- 使用者希望最終完成需通過 ai-slop-cleaner + 驗證 + $code-review 的門檻
- 使用者希望將活動中的 Claude
/goal指令與分類帳協調，以便會話重啟時不會遺失進度 </Use_When>
<Do_Not_Use_When>
- 任務是單一的小變更——請改用直接委派或
ralph - 使用者希望助手直接從 shell 呼叫
/goal——這是不可能的；omc ultragoal只寫入工件並輸出交接文字 - 使用者只想要一個純規劃的工件，不包含執行循環——請改用
plan</Do_Not_Use_When>
<Why_This_Exists>
Claude Code 的 /goal 是一個基於會話的停止鉤子：它會阻止會話在條件滿足前停止，並在成功時自動清除。這是一個很好的單一會話執行原語，但它會跨會話遺失狀態，且本身不強制執行最終的審查門禁。omc ultragoal 添加了一個持久化的計劃、分類帳和門控層，使長期的多步驟計劃能夠在會話重啟、新的工作樹和審查迭代中存活，同時仍利用 Claude /goal 來保持活動中的代理專注。
</Why_This_Exists>
<How_To_Use>
-
從簡報建立計劃：
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（一個 Claude/goal涵蓋整個執行）。 如果希望每個故事都有各自的/goal，請傳入--claude-goal-mode per-story。多倉庫工作空間 / 並行會話： 當同一個工作空間中的多個 Claude 會話需要同時執行
/ultragoal時，請傳入--plan-id <stable-id>或--auto-plan-id，以便將計劃寫入.omc/ultragoal/plans/{planId}/，而不是共享的單一計劃路徑。 如果沒有該旗標，兩個建立目標的會話會互相覆蓋。--auto-plan-id會從簡報標題推導出{epochMs}-{slug}。然後在同一個會話的所有後續子命令中重複使用相同的--plan-id <id>。 需要時，可使用omc ultragoal list-plans來列舉可用的 planId。 -
開始（或恢復）下一個故事：
omc ultragoal complete-goals [<goal-id>]如果不提供目標 ID，則保持預設行為：恢復活動中的故事或開始第一個待處理的故事。如果提供目標 ID，OMC 會精確定位該命名的合格故事（一個待處理的故事可以按順序啟動）；它永遠不會回退到另一個故事。如果活動中的故事不同、ID 未知、已完成、處於審查阻塞狀態，或是失敗的故事但未使用
--retry-failed，則會被拒絕而不修改狀態。如果命名的故事正在進行中，則恢復該故事而不增加嘗試次數。這會輸出一段模型可讀的交接文字。活動中的 Claude 代理必須讀取它，然後：- 為此會話設定原生的 Claude
/goal——在獨立的 Claude Code 中，shell 和代理都無法做到，因此需要請使用者輸入/goal <aggregate objective>並等待。--claude-goal-json（如下）僅協調分類帳，不能滿足 PreToolUse 的/goal保護機制，該機制會阻止工具呼叫，直到偵測到活動中的/goal。 - 執行該故事。
- 當故事完成時（對於最終故事，在完成完整的品質門禁後），分享當前
/goal狀態的快照，並呼叫checkpoint。
- 為此會話設定原生的 Claude
-
為故事建立檢查點：
omc ultragoal checkpoint --goal-id G001-... --status complete \ --evidence "tests/files/PR evidence" \ --claude-goal-json '{"goal":{"objective":"...","status":"active"}}'對於最終故事，同時傳入
--quality-gate-json，其中包含aiSlopCleaner、verification和codeReview的證據（全部通過）。 -
如果最終審查未通過，請勿標記為完成。記錄障礙：
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處於活動狀態。 -
隨時檢查狀態：
omc ultragoal status
</How_To_Use>
<Important_Limitations>
- Shell 無法呼叫或更改 Claude Code 的
/goal狀態。omc ultragoal只持久化工件並輸出活動中的 Claude 代理可在會話中讀取並執行操作的指示。 - 透過
--claude-goal-json傳入的快照是模型提供的活動中/goal狀態的證明；OMC 會驗證其文字與計劃的預期目標和分類帳事件一致，但無法獨立觀察 Claude/goal的狀態。這些快照不能滿足 PreToolUse 的/goal保護機制，該機制需要一個實際活動中的/goal——無論是主機注入的快照還是使用者在會話中設定的原生/goal。 - 如果 Claude
/goal斜線命令被重新命名或重構，只需要更改交接文字的措辭；協調邏輯與名稱無關。 </Important_Limitations>
並行會話注意事項
- 多倉庫工作空間錨點： 在上層目錄放置一個
.omc-workspace標記，以便多個跨子倉庫的會話共享同一個.omc/。解析順序：OMC_STATE_DIR > .omc-workspace > git > cwd。請參閱docs/REFERENCE.md。 - 會話 ID 來源： 在 CLI 環境中，
OMC_SESSION_ID環境變數優先；在鉤子環境中，data.session_id優先。 - 計劃 ID（適用時）： 同一個工作空間中的兩個執行會在共享的計劃工件上發生衝突。請使用不同的會話 ID（鉤子 payload 的 session_id 對每個 Claude Code 會話而言已經是隔離的），或傳入
--plan-id來讓並行的 ultragoal 執行使用各自獨立的分類帳。 - 並行結論： 支援（每個會話寫入自己的會話範圍狀態）。