ultragoal · git:20261102.c48e6e7 · 2026-11-02 · sha256 697885a357877b5b

ultragoal git:20261102.c48e6e7A

Immutable. This exact content never changes and is served at /api/v1/blob/697885a357877b5b.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_pbash54utl2rdl45/697885a357877b5ba74e1bbb05036ce00a27ef4be901261f126d120a8f04f911.json

Then /plugin install ultragoal@markdownregistry-pbash54utl2rdl45 in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
name: ultragoal
description: "[oh-my-agy] Create and execute durable repo-native multi-goal plans with a goals.json + ledger.jsonl audit trail, sequential completion, review gates, and resume. Use for $ultragoal, 'create-goals', 'complete-goals', durable multi-goal execution, or the Autopilot execution stage."
---

# Ultragoal Workflow

## When to use

Use for `$ultragoal`, `create-goals`, `complete-goals`, durable multi-goal planning, or sequential execution of an approved plan/spec. Also used as Autopilot's execution stage.

Codex's hidden `/goal` state (`get_goal`/`create_goal`/`update_goal`) does not exist for agents in Antigravity. The **repo ledger is the single source of truth**. Antigravity's `/goal` slash command is user-triggered. You may suggest it for very long runs, but never depend on it.

## Durable artifacts (leader-owned)

- `.omagy/ultragoal/brief.md`: the source brief (spec or plan text, or a pointer to it).
- `.omagy/ultragoal/goals.json`: the plan.
- `.omagy/ultragoal/ledger.jsonl`: append-only audit trail, one JSON object per line.

`goals.json` schema:
```json
{
  "version": 1,
  "objective": "<one-line aggregate objective>",
  "source": ".omagy/specs/deep-interview-<slug>.md | .omagy/plans/prd-<slug>.md | inline",
  "created_at": "<ISO>",
  "updated_at": "<ISO>",
  "invariants": ["<architecture/domain invariant that must hold at the end>"],
  "goals": [
    {
      "id": "G1",
      "title": "<short title>",
      "objective": "<verifiable objective>",
      "rigor": "light|heavy",
      "acceptance": ["<testable criterion>"],
      "status": "pending|in_progress|complete|blocked|failed|superseded",
      "depends_on": [],
      "product_failures": 0,
      "evidence": null
    }
  ]
}
```

**Goal rigor classification (`rigor`, ported from OmO `ulw-execute`)**:
- `"light"`: narrow change inside an existing module/pattern with no schema, auth, security, or public API contract change. Verified by targeted tests + acceptance check.
- `"heavy"`: cross-cutting change, new boundary/schema/auth/security surface, or state machine change. Requires targeted tests + at least 1 adversarial probe + independent `verifier` (`AdversarialVerify`) check before checkpointing.

Ledger entry shape (append; never rewrite earlier lines):
```json
{"at":"<ISO>","goal_id":"G1","event":"created|started|checkpoint|blocked|failed|steer|review-blockers|final-gate","status":"<status>","evidence":"<commands + exit codes / file refs>","note":"<optional>"}
```

Append a ledger line using the crash-resilient newline-isolated hook helper (`sh <plugin>/hooks/run.sh append-jsonl .omagy/ultragoal/ledger.jsonl '<json>'`, which prepends `\n` if a prior crash left a torn tail and refuses symlinks, ported from OMX 0.21.33 PR #3893), or by reading the file and writing it back with the new line added on its own newline. Read the ledger tolerantly (`sh <plugin>/hooks/run.sh read-jsonl .omagy/ultragoal/ledger.jsonl` or line-by-line JSON parsing that skips malformed torn lines).

## Operational steps: create

1. Read the brief: the deep-interview spec, ralplan PRD/test-spec, or the user's inline brief. Copy it or point to it from `brief.md`.
2. Decompose it into right-sized, independently verifiable goals with testable acceptance criteria and explicit dependencies. Carry spec non-goals, decision boundaries, and invariants into `goals.json`.
3. Write `goals.json`, append `created` ledger entries, and show the user a compact goal table (plus `[oh-my-agy HUD](sidecar://oh-my-agy/hud/)` once if the HUD sidecar is enabled).
4. Standalone: write `.omagy/state/ultragoal-state.json` (`mode:"ultragoal"`, `active:true`, `current_phase:"planning"`). Inside Autopilot: keep the Autopilot state and set its `current_phase:"ultragoal"`.

## Operational steps: execute

Repeat until every goal is `complete` (or `superseded`):

1. Pick the first `pending` goal whose dependencies are complete. Set it `in_progress`, append `started`, and set the phase to `executing`.
2. Implement the goal: solo, or via an `executor` subagent for a bounded slice, or via `$team` when parallel lanes are justified.
   - **Zero-Context-Bleed Brief & Review Handoffs**: extract per-goal briefs via `sh <plugin>/hooks/run.sh goal-brief .omagy/ultragoal/goals.json <goal_id>` and package commit ranges via `sh <plugin>/hooks/run.sh review-package <workspace> <base_sha> <head_sha>` so subagents read file paths instead of inline prompt dumps.
   - **4-State Worker Routing & Model Escalation**: handle worker returns deterministically:
     - `COMPLETED`: proceed to step 3 verification.
     - `COMPLETED_WITH_CONCERNS`: inspect the reported concern (e.g., file growth or fragile edge case); either log a `Ruling:` (`event:"steer"`, `kind:"ruling"`) with `cost_if_wrong` or run a targeted fix pass before checkpointing.
     - `NEEDS_CONTEXT`: supply the missing interface/context via `send_message` to the same worker conversation ID without incrementing `product_failures`.
     - `BLOCKED`: if a worker on `Model: "flash"` or `"inherit"` stalls after 2 attempts on a complex implementation slice, escalate the retry to a higher model tier (`flash -> inherit -> pro`).
3. Audit the goal against real artifacts (`current_phase:"verifying"`):
   - For `"rigor": "light"`, run targeted tests and acceptance checks directly.
   - For `"rigor": "heavy"`, form a `DoneClaim` (changed files, commands + exit codes, criterion mapping) and validate it (via the `verifier` subagent when independent confirmation is warranted) using the `AdversarialVerify` contract:
     - `verdict`: `"confirmed" | "false-positive" | "needs-fix" | "needs-human-review"`
     - `failure_class`: `"none" | "product" | "harness"`
4. Checkpoint: when `verdict` is `"confirmed"` (or `"light"` checks pass), set the goal `status:"complete"` with `evidence`, then append a `checkpoint` ledger line containing commands and exit codes. Refresh `updated_at` in state.
5. **Failure triage (`product` vs `harness`), unavailable verification & blocked-goal cascade (ported from OMX `v0.21.42` `#3964` & OmO `ulw-execute`)**:
   - **Unavailable verification never fabricates completion (OMX `#3964`)**: if the required test runner, verifier subagent, or external environment is unavailable or indeterminate, never mark the goal `complete` and never fabricate passing evidence. Record a truthful non-terminal `blocked` ledger entry (`event:"blocked"`, `status:"blocked"`, `note:"verification-unavailable:<reason>"`) and keep the goal `in_progress` or `blocked` until verification can actually run.
   - If verification fails with `failure_class: "harness"` (test runner setup, missing fixture, port/env glitch), run up to 1 bounded harness-repair attempt without incrementing `product_failures`.
   - If verification fails with `failure_class: "product"`, increment `product_failures` (max 3 attempts per goal). After 3 product failures or `"needs-human-review"`, set the goal `status:"blocked"` (`[~]`), append `blocked` to the ledger, and **cascade `status:"blocked"`** (`note:"blocked-by:<goal_id>"`) to every downstream `pending` goal whose `depends_on` transitively includes this goal. Continue with remaining independent `pending` goals; if none remain and user input is required, write state `current_phase:"blocked"`, `active:false`, and ask.

## Explicit steering & stale-goal reconciliation

- **Stale-Goal Reconciliation (on start/resume)**: Before executing a `pending` goal, run observable repo checks (`fileExists`, `fileContains`, `gitGrep`) against its target paths. If the repository already satisfies a goal's acceptance criteria from earlier work, verify with targeted tests and record a `checkpoint` with `note:"reconciled-from-repo"` instead of re-implementing.
- **Explicit Steering**: Change the decomposition only with evidence. Append a `steer` ledger entry with `kind`, `evidence`, and `rationale`, then edit `goals.json` accordingly. Supported kinds: `add_subgoal`, `split_subgoal`, `reorder_pending`, `revise_pending_wording`, `amend_criterion`, `annotate_ledger`, `mark_blocked_superseded`. Never silently delete goals. Mark them `superseded` instead.
- **Criterion Amendment & Autonomous Ruling Audit Trail (`Rulings, not stalls`)**: When a goal's acceptance criterion must be adjusted or an ambiguity/plan conflict is resolved autonomously against the spec without stalling the run, append a `steer` (`kind:"amend_criterion"` or `kind:"ruling"`) ledger entry recording `decision` (or `previous_criterion` / `amended_criterion`), `rationale`, `evidence`, and `cost_if_wrong` (`"Ruling: <what was decided> — <why> — <cost_if_wrong>"`). Surface all autonomous rulings and any deferred minor review observations explicitly under `"Rulings made & Deferred minors"` in the final closeout report. Ordinary prose does not mutate the plan.

## Team bridge

For parallel story execution, run `$team` against the active goals. Team workers return task evidence only. The Ultragoal leader alone updates `goals.json` and the ledger.

## Final gate and exit evidence

Before final completion (phase `reviewing`):

1. Run targeted verification for every goal.
2. Run `$ai-slop-cleaner` on the changed files, then rerun verification.
3. Audit every invariant from `goals.json` and the brief/spec/steering against implementation, tests, and review evidence.
4. Run `$code-review` through independent `code-reviewer` and `architect` subagent lanes. If review or invariant proof is not clean, add a `Resolve final code-review blockers` goal with the findings, append `review-blockers`, and loop back to execution. Inside Autopilot, design-level findings return Autopilot to `ralplan`.
5. When clean: append a `final-gate` ledger entry with cleaner, verification, review, and invariant evidence. Standalone: write the state terminal (`active:false`, `current_phase:"complete"`, `completed_at`). Inside Autopilot: set `handoff_artifacts.ultragoal` and let Autopilot finish.

Report goal ids/statuses, ledger path, review verdicts, and any blocker. Never claim completion from state files alone. Completion requires the verification evidence in the ledger.

## Resume

On `continue`/`resume`, read `goals.json`, the tail of `ledger.jsonl`, and the state file, then resume from the first non-complete goal. Do not re-decompose an existing plan unless steering is justified.
- **Resumed-run `started`-edge closeout bound (ported from OMC `v5.7.20` `#4646`, `#4650`)**: when resuming an interrupted or previously blocked goal, append a fresh `started` ledger entry (`event:"started"`). Only verification runs and `checkpoint` entries recorded **strictly after** that latest unmatched `started` entry count toward closing out the resumed goal — pre-resume notes or stale artifacts from an earlier attempt never satisfy closeout.