Ultragoal

Ultragoal Workflow

Use when the user asks for ultragoal, create-goals, complete-goals, durable multi-goal planning, or sequential execution over Codex /goal.

Purpose

ultragoal turns a brief into repo-native artifacts and then drives a Codex goal safely through goal tools. New plans default to a stable pointer-style aggregate Codex goal for the whole durable plan in .omx/ultragoal/goals.json, including later accepted/appended stories under the original brief constraints, while OMX tracks G001/G002 story progress in the ledger. Ultragoal does not call Codex /goal clear; before multiple sequential ultragoal runs in one Codex session/thread, manually run /goal clear in the Codex UI so the previous completed aggregate goal does not block or confuse the next create_goal.

• .omx/ultragoal/brief.md
• .omx/ultragoal/goals.json
• .omx/ultragoal/ledger.jsonl (checkpoint and structured steering audit events)

Existing aggregate plans with the legacy enumerated objective are migrated to the stable pointer objective on read, persisted to goals.json, retained in codexObjectiveAliases for already-active hidden Codex goal reconciliation, and audited with an aggregate_objective_migrated ledger entry.

State/HUD Phase Contract

Ultragoal is both a tracked workflow skill and the Autopilot durable-implementation child phase. Keep the phase/HUD contract explicit at workflow boundaries:

• Standalone $ultragoal activation: ensure .omx/state[/sessions/<session>]/ultragoal-state.json exists with mode:"ultragoal", active:true, and a non-empty current_phase such as planning before or while goals are created. This state is a lightweight HUD/runtime declaration; .omx/ultragoal/goals.json and ledger.jsonl remain the durable goal source of truth.
• During execution: update current_phase to the smallest accurate phase (planning, executing, verifying, reviewing, checkpointing, or blocked) when the visible workflow phase changes.
• Inside active Autopilot: keep mode:"autopilot" active and set the supervised phase to current_phase:"ultragoal"; do not start a peer Autopilot replacement. Ultragoal's own mode state may still exist as child-phase detail, but Autopilot owns the parent phase.
• On handoff to code-review: persist implementation/test/ledger evidence under Autopilot handoff_artifacts.ultragoal, then set Autopilot current_phase:"code-review".
• On completion/blocker: set standalone Ultragoal active:false,current_phase:"complete" only when all durable goals are complete; otherwise keep it active with a blocker/review-blocked phase and ledger evidence.

Minimal standalone phase declaration:

omx state write --input '{"mode":"ultragoal","active":true,"current_phase":"planning"}' --json

Minimal Autopilot child-phase declaration:

omx state write --input '{"mode":"autopilot","active":true,"current_phase":"ultragoal"}' --json

Create goals

1. Run one of:
   • omx ultragoal create-goals --brief "<brief>"
   • omx ultragoal create-goals --brief-file <path>
   • cat <brief> | omx ultragoal create-goals --from-stdin
   • omx ultragoal create-goals --codex-goal-mode per-story --brief "<brief>" only when one Codex goal context per story is explicitly preferred
2. Inspect .omx/ultragoal/goals.json and refine if needed.

Complete goals

Loop until omx ultragoal status reports all goals complete:

1. Run omx ultragoal complete-goals.
2. Read the printed handoff.
3. Call get_goal.
4. If no active Codex goal exists, call create_goal with the printed payload. In aggregate mode, if the same aggregate Codex objective is already active, continue the current OMX story without creating a new Codex goal.
5. Complete the current OMX story only.
6. Run a completion audit against the story objective and real artifacts/tests.
7. In aggregate mode, do not call update_goal for intermediate stories; checkpoint with a fresh get_goal snapshot whose aggregate objective is still active. On the final story only, first run the mandatory final cleanup/review gate below; call update_goal({status: "complete"}) only after that gate is clean, then call get_goal again for a fresh complete snapshot.
8. Checkpoint the durable ledger with that snapshot. Intermediate aggregate checkpoints use only --codex-goal-json; final clean checkpoints also require --quality-gate-json: omx ultragoal checkpoint --goal-id <id> --status complete --evidence "<evidence>" --codex-goal-json <get_goal-json-or-path> [--quality-gate-json <quality-gate-json-or-path>]
9. If blocked or failed, checkpoint failure: omx ultragoal checkpoint --goal-id <id> --status failed --evidence "<blocker/evidence>"
10. For non-terminal blockers, use blocked checkpoints:

• legacy different completed goal: omx ultragoal checkpoint --goal-id <id> --status blocked --evidence "<completed legacy Codex goal blocks create_goal in this thread>" --codex-goal-json <get_goal-json-or-path>
• matching native Codex blocked status: omx ultragoal checkpoint --goal-id <id> --status blocked --evidence "<blocker evidence>" --codex-goal-json <matching-blocked-get_goal-json-or-path>

11. Resume failed goals with omx ultragoal complete-goals --retry-failed.

Dynamic steering

Use omx ultragoal steer when real findings or blockers prove the current story decomposition should change while the aggregate objective and constraints stay fixed. Steering is explicit-only and evidence-backed; broad natural-language requests are rejected instead of guessed.

Allowed mutation kinds are:

• add_subgoal
• split_subgoal
• reorder_pending
• revise_pending_wording
• annotate_ledger
• mark_blocked_superseded

Examples:

omx ultragoal steer --kind add_subgoal --title "Investigate blocker" --objective "Validate the blocker and report evidence." --evidence "log/test output" --rationale "The blocker changes the safe execution order." --json
omx ultragoal steer --directive-json ./steering.json --json

Steering invariants:

• Do not edit the aggregate Codex objective, original brief constraints, quality gates, or completion status. The aggregate objective is a stable pointer to .omx/ultragoal/goals.json and .omx/ultragoal/ledger.jsonl, not an enumeration of initial goal ids.
• Do not hard-delete goals, auto-complete work, weaken verification, or silently mutate .omx/ultragoal.
• Accepted and rejected attempts append structured audit entries to .omx/ultragoal/ledger.jsonl.
• Superseded goals remain in goals.json with steering metadata and are skipped for scheduling.
• Blocked goals without replacements are skipped for scheduling but still block final completion until later explicit steering replaces or supersedes them.

UserPromptSubmit uses the same steering API only for structured directives such as OMX_ULTRAGOAL_STEER: { ... }, omx.ultragoal.steer: { ... }, or omx ultragoal steer: { ... }. Normal prose does not mutate state, and repeated prompt-submit directives dedupe by prompt signature or idempotency key.