---
name: ultragoal
description: Durable LazyClaude goal orchestration with CLI-backed state, explicit success criteria, evidence ledgers, checkpoints, steering, quality gates, and cleanup receipts.
---

# Ultragoal

Use this skill when work must survive turns, compaction, interrupted sessions,
or handoff to another agent. The core rule is strict: a goal is not complete
until every success criterion has observable evidence from a real surface and a
cleanup receipt.

LazyClaude ships a local runtime for this workflow. Use the package CLI as the
source of durable state:

```sh
lazyclaude-ai ultragoal create-goals --brief "<brief>" --json
lazyclaude-ai ultragoal status --json
lazyclaude-ai ultragoal criteria --json
lazyclaude-ai ultragoal record-evidence --criterion <id> --status pass --json '{"artifact":"...","cleanup":"..."}'
lazyclaude-ai ultragoal checkpoint --status complete --note "<summary>" --json
lazyclaude-ai ultragoal steer --kind scope --note "<evidence-backed steering>" --json
lazyclaude-ai ultragoal record-review-blockers --blocker "<finding>" --json
```

The executable runtime lives in `plugins/lazyclaude/lib/ultragoal/`. Runtime
state lives under `.omo/ultragoal/` in the active working directory:

- `.omo/ultragoal/brief.md` stores the original brief.
- `.omo/ultragoal/goals.json` stores the durable objective, status, criteria,
  blockers, steering decisions, and checkpoints.
- `.omo/ultragoal/ledger.jsonl` is the append-only evidence ledger.

The runtime uses atomic JSON writes and a lock-safe mutation path so concurrent
recording attempts do not corrupt `goals.json` or `ledger.jsonl`. Never hand-edit
these files as a substitute for CLI commands.

## Goal Shape

Represent every ultragoal run as:

- objective
- non-goals and user constraints
- success criteria
- expected evidence per criterion
- Manual-QA channel per criterion
- current state
- blockers
- cleanup receipts
- checkpoint history
- final quality gate

If model-facing goal tools are exposed, inspect them before creating a new
active goal. Treat `/goal` as a user-visible Claude Code slash command. Never
auto-type `/goal`, never claim slash-command activation without evidence, and
never mark a goal complete through native goal tooling until the local
ultragoal criteria have passed.

## Bootstrap

Do these steps before implementation edits:

1. Read `HANDOFF.md`, the active plan, and `.omo/ultragoal/ledger.jsonl` when
   they exist.
2. Run `lazyclaude-ai ultragoal status --json`.
3. If no state exists for the current objective, run
   `lazyclaude-ai ultragoal create-goals --brief "<brief>" --json`.
4. Run `lazyclaude-ai ultragoal criteria --json` and inspect the criterion ids.
5. Refine the working checklist so each criterion has exact expected evidence
   and one Manual-QA channel.

Do not start production edits when the objective, constraints, or evidence
surface is ambiguous. Resolve the ambiguity or record a blocker first.

## Success Criteria Refinement

Each criterion must have:

- `id`
- scenario
- exact expected evidence
- pass/fail boundary
- adversarial classes to probe
- Manual-QA channel: HTTP call, tmux, browser use, or computer use
- cleanup receipt requirement

Tests are supporting evidence. They are not sufficient completion proof for
user-facing behavior. A criterion can pass only when its real-surface artifact
exists and the cleanup receipt proves no QA resource remains alive.

## Execution Loop

Work one criterion at a time:

1. PLAN: read the criterion, prior ledger entries, constraints, and blockers.
2. PIN: when touching existing behavior, capture the current observable behavior
   with a characterization test or transcript before changing it.
3. RED: add a failing test or reproduction for the desired behavior.
4. GREEN: implement the smallest change that satisfies the criterion.
5. SURFACE: run the criterion's Manual-QA channel.
6. CAPTURE: save the artifact path, command, status, and observable result.
7. CLEAN: tear down every spawned process, tmux session, browser context, port,
   temp directory, container, worktree, or QA file.
8. RECORD: call `record-evidence` with pass, fail, or blocked.
9. CHECKPOINT: call `checkpoint` when a criterion, blocker, or steering change
   alters durable state.

Do not batch unrelated criteria. If discovery changes the goal, use steering
instead of silently changing the plan.

## Recording Evidence

Use `record-evidence` for exactly one criterion result:

```sh
lazyclaude-ai ultragoal record-evidence \
  --criterion criterion-1 \
  --status pass \
  --json '{"artifact":".omo/ulw-loop/evidence/criterion-1.txt","manualQa":"tmux transcript","cleanup":"tmux kill-session ...; HAS_SESSION_STATUS:1","adversarial":["malformed_input","stale_state"]}'
```

Allowed statuses are `pass`, `fail`, and `blocked`. A malformed evidence JSON
payload must fail with a controlled CLI error. A missing criterion id must fail
with a controlled state error. Never record `pass` while a QA resource is still
alive or while the artifact is only a dry-run claim.

## Manual-QA Channels

Manual-QA channels are required for criterion completion.

Pick one real channel per criterion:

- HTTP call: `curl -i` against the live endpoint.
- tmux: create a named session, drive the command, capture the pane transcript,
  kill the session, and verify `HAS_SESSION_STATUS:1`.
- Browser use: drive the real page, capture an action log and screenshot, then
  close the context.
- Computer use: automate the desktop surface, capture an action log and
  screenshot, then close the app/session.

Auxiliary CLI output can prove data-shaped behavior, but it does not replace
the selected Manual-QA channel for user-visible behavior.

## Checkpoints

Use checkpoints for resumability:

```sh
lazyclaude-ai ultragoal checkpoint --status active --note "<progress>" --json
lazyclaude-ai ultragoal checkpoint --status blocked --note "<blocker>" --json
lazyclaude-ai ultragoal checkpoint --status complete --note "<evidence summary>" --json
```

The runtime must reject `--status complete` until every criterion in
`.omo/ultragoal/goals.json` is `pass`. If completion is rejected, inspect
`criteria --json`, fix or record the pending criterion, and retry.

## Steering

Use `steer` only for evidence-backed changes in direction:

```sh
lazyclaude-ai ultragoal steer --kind scope --note "<what changed and why>" --json
lazyclaude-ai ultragoal steer --kind priority --note "<new order evidence>" --json
lazyclaude-ai ultragoal steer --kind blocker --note "<blocking evidence>" --json
lazyclaude-ai ultragoal steer --kind quality --note "<quality gate adjustment>" --json
lazyclaude-ai ultragoal steer --kind handoff --note "<handoff update>" --json
```

Normal prose does not mutate durable state. Steering must explain the observed
evidence and the exact next action. Invalid steering kinds must fail with a
controlled CLI error.

## Final Quality Gate

Before final completion:

1. All criteria are `pass` in `lazyclaude-ai ultragoal criteria --json`.
2. Targeted tests for changed behavior pass.
3. The relevant full validation suite passes for the blast radius.
4. Manual-QA artifacts exist for every user-facing criterion.
5. Cleanup receipts exist for every QA resource.
6. Review has no blocking findings for broad or risky changes.
7. Commit, push, tag, and publish actions match the user's explicit request.

Only after this gate may you call:

```sh
lazyclaude-ai ultragoal checkpoint --status complete --note "<final evidence>" --json
```

## Recovery

When resuming:

1. Read the handoff and ledger before doing new work.
2. Run `lazyclaude-ai ultragoal status --json`.
3. Run `lazyclaude-ai ultragoal criteria --json`.
4. Reproduce the latest blocker or verify the latest pass before proceeding.
5. Continue from the first pending or failed criterion.

Do not create a second parallel goal for the same objective just because the old
state is inconvenient. If state is corrupt, capture the controlled error and
record a blocker or steering note instead of inventing state.

## Stop Rules

Stop and surface the state when:

- All criteria pass and the final quality gate is complete.
- The same criterion fails three times with the same cause.
- Five cycles on one goal do not produce all-pass criteria.
- A safety boundary appears: destructive command, secret exposure, production
  write, or unapproved publish/push.
- Required external access, credentials, hardware, or user approval is missing.
- A QA process, tmux session, browser context, bound port, container, temp dir,
  or worktree cannot be cleaned up.

Leftover runtime state means `blocked`, not `pass`.
