企业官网建设流程全解析

oh-my-claudecode 的 ultragoal 怎么在没有活动执行循环时维护持久化目标账本？

【免费下载链接】oh-my-claudecodeTeams-first Multi-agent orchestration for Claude Code项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-claudecode

在 oh-my-claudecode（OMC）里，omc ultragoal是一个持久化多目标工作流：它把一份 brief 拆成有序 stories，把开始/检查点/失败事件记进只追加的账本（ledger），并打印给活动 Claude agent 读的交接文本（handoff）。当你当前会话里没有活动执行循环——/goal不可用、或者 Ralph / Team / autopilot 已经占用续作权——时，文档给出的路径是只维护.omc/ultragoal/下的计划与审计轨迹，不要求 Claude Code 激活/goal。docs/REFERENCE.md 把这种形态称为 "Artifact-only Ultragoal"：Track goal state without starting another active loop。

前提只有一个：在目标仓库的工作目录下可以运行omcCLI，下文命令都在仓库根目录执行。

什么情况下用无循环的账本维护

docs/REFERENCE.md 的 Goal Workflow 一节对目标型请求给出三选一的决定性策略：

• refuse：Ralph、Team、autopilot 或其他 Stop-hook 循环已经活动，新的/goal会争抢续作权；
• adopt_existing：Claude Code/goal已活动，且 OMC 工作流能在不改变循环归属的前提下为同一条件附加证据；
• artifact_only：/goal因 hooks / trust / settings 不可用，或用户只需要持久化的规划、检查点和证据捕获。

artifact_only就是"没有活动执行循环"对应的分支。docs/design/CLAUDE_CODE_GOAL_ADAPTER.md 的可用性矩阵列出了典型条件：hook-disabling 设置阻断/goal、受管 hooks 阻止/goal、工作区未被信任、能力无法判定——这些情况下适配器的行为是 "Write the durable goal ledger and handoff artifact only. Do not ask Claude Code to activate/goal"。

docs/shared/mode-selection-guide.md 的快速决策表里也有一条对应项："Durable goal ledger without starting another loop → artifact-only Ultragoal"。

两种情况不要走这条路：单次小改动（文档建议直接委派或ralph）、只想要规划产物而没有执行动作（用plan）。

持久化账本长什么样

默认（单计划）布局，见 docs/ultragoal.md：

.omc/ultragoal/ brief.md The free-text brief used to seed the plan goals.json The structured plan (version 1) with stories and mode ledger.jsonl Append-only audit trail of plan/goal events

使用--plan-id或--auto-plan-id后，这三个文件改写到.omc/ultragoal/plans/{planId}/下。

goals.json中每个 story 的状态是pending、in_progress、complete、failed或review_blocked之一；计划还带一个claudeGoalMode：

• aggregate（默认）：一个 Claude/goal覆盖整个 ultragoal 运行，OMC 的G001/G002… 只是账本里的簿记条目；
• per_story：每个 story 对应自己的/goal指令，适合 story 很大、希望逐个清掉的情况。

ledger.jsonl记录的事件类型包括plan_created、goal_started、goal_resumed、goal_completed、goal_failed、goal_retried、goal_added、goal_review_blocked、final_review_failed、aggregate_completed（定义见 src/ultragoal/artifacts.ts）。goal id 形如G001-<slug>，slug 是标题小写、连字符化并截断后的结果。

第一步：创建计划

创建命令的完整签名（src/cli/commands/ultragoal.ts 的帮助文本）：

omc ultragoal create-goals [--brief <text> | --brief-file <path> | --from-stdin] [--goal <title::objective>]... [--claude-goal-mode <aggregate|per-story>] [--plan-id <id> | --auto-plan-id] [--force] [--json]

skills/ultragoal/SKILL.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"

--goal里::前面是标题、后面是目标；不写::时整段文本同时充当标题和目标。不传--goal时，计划从 brief 的列表项或段落自动派生。默认模式是aggregate；想让每个 story 有独立/goal时显式加--claude-goal-mode per-story。

按上面的例子，生成的 goal id 是G001-schema、G002-backfill、G003-cutover。成功时 OMC 写入.omc/ultragoal/三个文件，并在账本记一条plan_created。若goals.json已存在，默认拒绝覆盖，报错：

Refusing to overwrite existing .omc/ultragoal/goals.json; pass --force to recreate it.

重建必须显式加--force，这一点在账本已存在、想重新播种时尤其要注意。

第二步：开始或恢复一个 story

omc ultragoal complete-goals omc ultragoal complete-goals G002-backfill omc ultragoal complete-goals --retry-failed

不带 goal id 时保持默认行为：恢复活动 story，或开始第一个 pending story。带 goal id 时精确指向那个符合条件的 story（pending story 可以乱序开始），不会落到别的 story 上。已完成、review-blocked、未知 id、以及未加--retry-failed的 failed story 都会被拒绝且不改变任何状态；恢复一个 in_progress 的 story 不会增加它的 attempt 计数。

成功开始后的落盘效果：story 状态变为in_progress、attempt+1，账本追加goal_started（恢复时是goal_resumed）。命令同时打印 model-facing handoff——它告诉活动 agent 如何设置/goal、何时清掉、回传什么快照。artifact-only 场景下按适配器契约，你不需要请求 Claude Code 激活/goal，真正落到仓库里的是账本和工件本身。

第三步：记录检查点

检查点要求该 story 处于in_progress且是计划的活动 story，否则会被拒绝，提示先 "start or resume the active ultragoal before checkpointing it"。

记录失败（这一步不需要/goal快照）：

omc ultragoal checkpoint --goal-id G002-backfill --status failed \ --evidence "<failure evidence>"

--evidence文本会存进 story 的failureReason，账本追加goal_failed。之后用omc ultragoal complete-goals --retry-failed重试，账本记goal_retried。

记录完成（complete检查点必须过--claude-goal-json一致性校验）：

omc ultragoal checkpoint --goal-id G002-backfill --status complete \ --evidence "tests/files/PR evidence" \ --claude-goal-json '<快照 JSON 或路径>'

--claude-goal-json接受内联 JSON 或 JSON 文件路径，docs/ultragoal.md 给出的可接受形状是：

{ "goal": { "objective": "...", "status": "active|complete|cancelled" } } { "objective": "...", "status": "complete" } { "goal": { "condition": "...", "status": "cleared" } }

其中...替换为计划的 objective 文本与实际状态；condition是objective的同义词（Claude/goal把指令叫 "condition"），cleared按cancelled处理。一致性要求随模式变化：per_story模式快照状态必须是complete；aggregate模式非最终 story 用active即可，最终 story 要求complete。OMC 不读取 Claude 内部状态，它只校验快照、计划的预期 objective、待记账事件三者之间的文本一致性——快照被视为 model 提供的权威证明。

最终 story 的complete检查点强制校验--quality-gate-json：

{ "aiSlopCleaner": { "status": "passed", "evidence": "..." }, "verification": { "status": "passed", "commands": ["..."], "evidence": "..." }, "codeReview": { "recommendation": "APPROVE", "architectStatus": "CLEAR", "evidence": "..." } }

对应要求：ai-slop-cleaner必须对变更文件跑过（即使结果是 no-op）且status为passed；verification.commands必须是非空数组；codeReview必须APPROVE+CLEAR。如果最终 review 不干净，不要强行标记完成，而是记录 blockers：

omc ultragoal record-review-blockers --goal-id G003-cutover \ --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"}}'

这条命令把当前 story 标记为review_blocked、追加一个新的 blocker story，账本依次记final_review_failed、goal_added、goal_review_blocked，让后续迭代有明确的落点。

运行中途要补 story，用：

omc ultragoal add-goal --title "Backfill guard" --objective "<objective text>" [--evidence "<text>"]

新 story 以pending状态追加，账本记goal_added。

并行会话：避免互相覆盖计划

同一个共享.omc/的工作区里，两个会话都跑create-goals会互相覆盖单计划路径。解决办法是在create-goals时传--plan-id <stable-id>或--auto-plan-id（两者互斥），计划改写到.omc/ultragoal/plans/{planId}/；--auto-plan-id从 brief 标题派生{epochMs}-{slug}，两个并行会话不会撞 id。后续子命令在只有一个计划时自动解析；存在多个计划时必须显式传--plan-id，否则报错：

Multiple ultragoal plans exist; pass --plan-id <id>. Available plans: <id1>, <id2>

omc ultragoal list-plans [--json]可以枚举当前所有 plan id；plan id 允许字符是字母数字开头，后接字母、数字、点、下划线、连字符。

怎么验证账本状态

omc ultragoal status [--plan-id <id>] [--json]

status输出计划摘要：story 总数及按pending/in_progress/complete/failed/review_blocked的分项计数、是否记录了 aggregate 完成、活动 story id。ledger.jsonl是只追加文件，可以逐行读取核对plan_created、goal_started、goal_completed等事件是否按时间落账。整个计划在没有pending/in_progress/failedstory、且最近一个非review_blockedstory 为complete（或已记录 aggregate 完成）时视为完成。

如果还没创建过计划，status会直接给出可执行的修复提示，这本身也是一个快速检查点：

No ultragoal plan found at .omc/ultragoal/goals.json. Run `omc ultragoal create-goals ...` first.

跑完create-goals后再执行status不再报这个错、且.omc/ultragoal/下出现三个文件，就说明计划创建成功。

边界

• Shell 命令无法直接调用、设置或清除/goal——它是会话级、面向模型的指令，只能由活动 agent 在会话内执行。ultragoal 写的是持久化工件，handoff 文本是写给活动 agent 的指令。
• --claude-goal-json只核对账本一致性，不满足 PreToolUse/goal守卫（该守卫在观察到活动/goal之前会阻断工具调用）。
• 若未来 Claude 的/goal工具改名，只有 handoff 文本与快照字段名需要更新，一致性逻辑本身与名称无关（name-agnostic）。

【免费下载链接】oh-my-claudecodeTeams-first Multi-agent orchestration for Claude Code项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-claudecode