ultragoal

用途

ultragoal 用于为大型、多步骤的工作提供一种持久、仓库原生的跟踪方式。当一项工作大到需要拆分为多个有序的“故事（story）”，并且需要记录每个故事的尝试次数与证据时，可以使用它。它让一个长期的多步计划能够跨越会话重启、新的 worktree 以及多轮评审迭代而保留状态，同时仍然借助 Claude /goal 让当前活动的智能体保持专注。

主要能力

• 从简要说明（brief）或显式故事列表创建目标计划。
• 将计划与账本工件持久化到 .omc/ultragoal 下。
• 为当前会话打印面向模型的交接文本（handoff）。
• 支持聚合模式（一个 Claude /goal 覆盖整轮运行）与逐故事模式（每个故事各自拥有 /goal）。
• 支持多仓库工作区与并行会话：通过 --plan-id 或 --auto-plan-id 将计划写入 .omc/ultragoal/plans/{planId}/，避免多个会话互相覆盖。
• 支持检查点（checkpoint）、记录评审阻塞项（record-review-blockers）以及随时查看状态。
• 最终完成可被 ai-slop-cleaner + 验证 + $code-review 质量门禁所约束。

使用方式

从简要文件创建计划：

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>]

不带 goal id 时，保持默认行为：恢复活动故事或启动第一个待处理故事。带 goal id 时，OMC 精确指向该具名且符合条件的故事（待处理故事可以乱序启动）；它绝不会落到另一个故事。若存在不同的活动故事、未知 id、已完成或评审阻塞的故事，或未带 --retry-failed 的失败故事，都会被拒绝且不改变状态。进行中的具名故事会被恢复且不改变其尝试次数。此命令会打印面向模型的交接文本。活动 Claude 智能体必须读取它并：

1. 为本会话设置原生 Claude /goal —— 在独立 Claude Code 中，shell 和智能体都无法做到，因此需请用户输入 /goal <aggregate objective> 并等待。--claude-goal-json（见下）只对账本进行协调，并不满足 PreToolUse /goal 守卫，该守卫会阻止工具调用直到观察到活动的 /goal。
2. 推进该故事。
3. 当故事完成时（对于最后一个故事，需在完整质量门禁之后），回传活动 /goal 状态的快照并调用 checkpoint。

检查点一个故事：

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。

若最终评审不干净，不要标记完成。记录阻塞项：

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

适用场景

• 用户希望以持久、仓库原生的方式跨多个 Claude 会话或 worktree 跟踪一个 ultragoal。
• 工作大到需要多个有序故事，并带有尝试次数与逐故事证据。
• 用户希望最终完成被 ai-slop-cleaner + 验证 + $code-review 门禁约束。
• 用户希望活动 Claude /goal 指令与账本协调，使会话重启不丢失进度。

限制

• 不适用场景：单个小改动（应使用直接委派或 ralph）；用户希望助手从 shell 字面调用 /goal（不可能，omc ultragoal 只写工件并打印交接文本）；用户只想要无执行循环的纯规划工件（应使用 plan）。
• shell 无法调用或改变 Claude Code /goal 状态。omc ultragoal 只持久化工件并打印指令，由活动 Claude 智能体在会话内读取并执行。
• 通过 --claude-goal-json 传入的快照是模型提供的活动 /goal 状态证明；OMC 会校验其与计划预期目标和账本事件的文本一致性，但无法独立观察 Claude /goal 状态。它们不满足 PreToolUse /goal 守卫，该守卫需要实际活动的 /goal —— 由宿主注入的快照或用户在会话内设置的原生 /goal。
• 若 Claude /goal 斜杠命令被重命名或重构，只需修改交接措辞；对账逻辑与名称无关。
• 并行会话注意事项：多仓库工作区锚点——在父目录放置 .omc-workspace 标记，使跨子仓库的多个会话共享一个 .omc/。解析顺序：OMC_STATE_DIR > .omc-workspace > git > cwd。详见 docs/REFERENCE.md。会话 id 来源：CLI 上下文中 OMC_SESSION_ID 环境变量优先；hook 上下文中 hook 载荷 data.session_id 优先。计划 id（适用时）：同一工作区中的两次运行会在共享计划工件上冲突。使用不同的会话 ID（hook 载荷 session_id 已按 Claude Code 会话隔离），或传入 --plan-id 让并行 ultragoal 运行使用各自独立的账本。并行结论：支持（每个会话写入自己的会话级状态）。