ultragoal

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

<Purpose> Ultragoal breaks a brief into an ordered set of goals, records start/checkpoint/blocker/failure events in a durable append-only ledger, and tells the active Claude agent how to drive the Claude Code `/goal` slash command alongside the plan. It does not — and cannot — mutate Claude `/goal` state from the shell; it persists durable repo state and prints a model-facing handoff that the active agent must act on in-session. </Purpose>

<Use_When>

The user wants a durable, repo-native way to track an ultragoal across multiple Claude sessions or worktrees
The work is large enough to warrant multiple ordered "stories" with attempt counts and per-story evidence
The user wants the final completion gated behind ai-slop-cleaner + verification + $code-review
The user wants the active Claude
```
/goal
```
directive coordinated with the ledger so that a session restart does not lose progress </Use_When>

<Do_Not_Use_When>

The task is a single small change — use direct delegation or
```
ralph
```
instead
The user wants the assistant to literally invoke
```
/goal
```
itself from the shell — that is not possible;
```
omc ultragoal
```
only writes artifacts and prints handoff text
The user wants a planning-only artifact with no execution loop — use
```
plan
```
instead </Do_Not_Use_When>

<Why_This_Exists> Claude Code

/goal

is a session-scoped Stop hook: it blocks the session from stopping until a condition holds, and auto-clears on success. That is a great single-session execution primitive, but it loses state across sessions and does not by itself enforce a final review gate.

omc ultragoal

adds a durable plan, ledger, and gating layer so a long multi-step initiative can survive session restarts, fresh worktrees, and review iterations while still leveraging Claude

/goal

to keep the active agent focused. </Why_This_Exists>

<How_To_Use>

Create a plan from a brief:
```
omc ultragoal create-goals --brief-file plan.md
```
Or with explicit stories:
```
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"
```
The default mode is
```
aggregate
```
(one Claude
```
/goal
```
covers the run). Pass
```
--claude-goal-mode per-story
```
if you want each story to have its own
```
/goal
```
.
Multi-repo workspaces / parallel sessions: when several Claude sessions in the same workspace need to run
```
/ultragoal
```
concurrently, pass either
```
--plan-id <stable-id>
```
or
```
--auto-plan-id
```
so the plan is written to
```
.omc/ultragoal/plans/{planId}/
```
instead of the shared single-plan path. Without that flag, two sessions creating goals would clobber each other.
```
--auto-plan-id
```
derives
```
{epochMs}-{slug}
```
from the brief title. Then thread the same
```
--plan-id <id>
```
through every subsequent subcommand in that session. Use
```
omc ultragoal list-plans
```
to enumerate available planIds when needed.
Start (or resume) the next story:
```
omc ultragoal complete-goals
```
This prints a model-facing handoff. The active Claude agent must read it and:
- Set the native Claude
```
/goal
```
  for this session — in standalone Claude Code neither the shell nor the agent can do it, so ask the user to type
```
/goal <aggregate objective>
```
  and wait.
```
--claude-goal-json
```
  (below) reconciles the ledger only and does not satisfy the PreToolUse
```
/goal
```
  guard, which blocks tool calls until it observes an active
```
/goal
```
  .
- Work the story.
- When the story is complete (and for the final story, after the full quality gate), share back a snapshot of the active
```
/goal
```
  state and call
```
checkpoint
```
  .

Checkpoint a story:

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

For the final story, also pass

--quality-gate-json

containing

aiSlopCleaner

verification

, and

codeReview

evidence (all clean).

If the final review is not clean, do NOT mark complete. Record blockers:

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"}}'

This appends a new blocker story and keeps the Claude

/goal

active.

Inspect state at any time:
```
omc ultragoal status
```

</How_To_Use>

<Important_Limitations>

The shell cannot invoke or mutate Claude Code
```
/goal
```
state.
```
omc ultragoal
```
only persists durable artifacts and prints instructions that the active Claude agent reads and acts on in-session.
Snapshots passed via
```
--claude-goal-json
```
are model-supplied proof of the active
```
/goal
```
state; OMC validates them for textual consistency with the plan's expected objective and ledger event, but it cannot independently observe Claude
```
/goal
```
state. They do not satisfy the PreToolUse
```
/goal
```
guard, which requires an actual active
```
/goal
```
— a host-injected snapshot or the native
```
/goal
```
the user set in-session.
If the Claude
```
/goal
```
slash command is renamed or restructured, only the handoff wording needs to change; the reconciliation logic is name-agnostic. </Important_Limitations>

<Purpose> Ultragoal会将任务简报拆解为有序的目标集合，在持久化的追加式账本中记录开始/检查点/阻塞/失败事件，并告知当前的Claude代理如何结合计划使用Claude Code的`/goal`斜杠命令。它无法（也不能）从Shell端修改Claude的`/goal`状态；它仅持久化仓库状态，并打印供模型查看的交接说明，由当前代理在会话内执行。 </Purpose>

<Use_When>

用户需要一种持久化、仓库原生的方式，跨多个Claude会话或工作树跟踪ultragoal
工作规模足够大，需要多个有序的“任务单元”，并记录尝试次数和每个任务单元的证据
用户希望最终完成需经过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 "完成迁移部署" \
  --goal "Schema::添加新列" \
  --goal "Backfill::分批回填数据行" \
  --goal "Cutover::删除旧列并切换读取源"
```
默认模式为
```
aggregate
```
（一个Claude
```
/goal
```
覆盖整个运行过程）。如果希望每个任务单元都有独立的
```
/goal
```
，请传递
```
--claude-goal-mode per-story
```
参数。
多仓库工作区/并行会话：当同一工作区中的多个Claude会话需要同时运行
```
/ultragoal
```
时，请传递
```
--plan-id <稳定ID>
```
或
```
--auto-plan-id
```
参数，这样计划会被写入
```
.omc/ultragoal/plans/{planId}/
```
目录，而非共享的单计划路径。如果没有该参数，两个创建目标的会话会互相覆盖。
```
--auto-plan-id
```
会根据简报标题生成
```
{epochMs}-{slug}
```
格式的ID。之后在该会话的所有后续子命令中都要传递相同的
```
--plan-id <id>
```
参数。必要时可使用
```
omc ultragoal list-plans
```
命令枚举可用的planId。
启动（或恢复）下一个任务单元：
```
omc ultragoal complete-goals
```
这会打印供模型查看的交接说明。当前的Claude代理必须阅读并执行以下操作：
- 设置当前会话的原生Claude
```
/goal
```
  ——在独立的Claude Code中，Shell和代理都无法完成此操作，因此需要让用户输入
```
/goal <聚合目标>
```
  并等待。下文的
```
--claude-goal-json
```
  仅用于协调账本，无法满足PreToolUse
```
/goal
```
  防护要求，该防护会阻止工具调用，直到检测到活跃的
```
/goal
```
  。
- 执行任务单元。
- 任务单元完成后（最终任务单元需在通过完整质量关卡后），分享当前
```
/goal
```
  状态的快照并调用
```
checkpoint
```
  。

为任务单元创建检查点：

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

对于最终任务单元，还需传递包含

aiSlopCleaner

、

verification

和

codeReview

证据（全部通过）的

--quality-gate-json

参数。

如果最终审核未通过，请勿标记为完成。记录阻塞项：

omc ultragoal record-review-blockers --goal-id G00X-... \
  --title "解决最终代码审核阻塞项" \
  --objective "修复列出的审核问题并重新运行最终关卡" \
  --evidence "<审核问题内容>" \
  --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>