/ulw-loop

name: ulw-loop
description: "A goal-like loop that decomposes work into systematic, evidence-bound ultrawork steps. Use when the user wants a goal loop or durable, checkpointed execution."
metadata:
  short-description: Goal-like ultrawork loop for systematic decomposition

ulw-loop

Use this skill when the user asks for `ulw-loop`, `ulw`, durable goal execution, evidence-led work, manual QA, or checkpointed long-running delivery.

This skill is compact by design: the run contract below is the whole bootstrap. `references/full-workflow.md` and `references/define-goal.md` carry the full doctrine; open a section only when the phase you are in needs it.

Run contract

1. Create goals from a JS eval cell: `agentToolkit.createGoals({ brief })` after the SDK import below. The SDK binds this session from the host env, so never pass a session id or a plan path. If the envelope reports `ULW_LOOP_PLAN_EXISTS_COMPLETE` (this session's aggregate is already complete), unrelated new work needs a fresh session; `createGoals({ brief, force: true })` is only for deliberately overwriting completed evidence. 2. Register the aggregate objective from the returned handoff with `create_goal`, shaped by `references/define-goal.md`. Goal creation is NEVER skipped. 3. Mirror every atomic step into the live `todo` checklist: one granular step per action, exactly one in_progress, transitions marked the instant they happen. 4. Treat each goal as a phase: create its own worktree off the integration base; dispatch its dependency-ordered lanes as ONE `workflow` run (read the mass-ulw skill first; ordering-free lanes stay a `task` batch); verify every criterion with real-surface evidence; land the worktree on the integration base at `agentToolkit.checkpoint({ goalId, status: "complete", evidence })` per the repository's flow (direct merge or merged PR); define the next goal's run from what this one proved. Tests alone never prove done. When a mass-ulw pointer accompanies this skill, this contract still owns goals, criteria, evidence, and checkpoints. 5. Stop when the goal's WHEN-TO-STOP line holds with evidence in hand.

When the injected ultrawork directive accompanies this skill, its goal/notepad/todo bootstrap is subsumed by this contract: the loop SDK owns goal state and the loop ledger is the notepad. Do not create a second one.

The SDK: one import, then method calls

Every ulw-loop operation runs inside a JS eval cell through the SDK the extension publishes at `OMO_AGENT_TOOLKIT_SDK_ROOT`. There is no `omo_agent_toolkit` tool and no CLI to spawn on Senpi.

const { agentToolkit } = await import(`${env("OMO_AGENT_TOOLKIT_SDK_ROOT")}/sdk.js`)
print(await agentToolkit.status())

Rules that keep it working:

• JS cells only. From a py, rb, or jl cell, run a separate eval with language `js`.
• Import once per kernel lifetime. `agentToolkit` stays bound in later cells; re-import only after a kernel restart or a `ReferenceError: agentToolkit is not defined`.
• Every call resolves to an envelope, never a throw: `{ ok: true, operation, result, nextActions, warnings? }` or `{ ok: false, operation, error: { code, message } }`. Read `nextActions` before deciding the next step, and branch on `error.code`, not on the message text.
• Never pass a session id or plan path. The SDK binds `PI_SESSION_ID` and `PI_SESSION_CWD` from the host env on each call; state lives under `.omo/ulw-loop/<session-id>/`.
• The driver snapshot is filled automatically from this session's goal store. Pass `codexGoalJson` only to override it.

Methods (argument fields are exact):

| Method | Args | |---|---| | `help()` | none | | `status()` | none; `result` carries `plan`, `summary`, `nextActions`, `currentAttemptDir` | | `createGoals(args)` | `{ brief, codexGoalMode?, force?, validationBatchesJson? }` | | `completeGoals(args?)` | `{ retryFailed? }`; acquires the next eligible goal or resumes the in-progress one | | `criteria(args)` | `{ goalId }` | | `recordEvidence(args)` | `{ goalId, criterionId, status: "pass" \| "fail" \| "blocked", evidence, notes? }` | | `checkpoint(args)` | `{ goalId, status: "complete" \| "failed" \| "blocked", evidence, codexGoalJson?, qualityGateJson? }`, or `{ printTemplate: true, goalId? }` for the quality-gate template | | `steer(args)` | `{ kind, source: "finding", evidence, rationale, ...kind fields }`; kinds and their fields are in `references/full-workflow.md` | | `addGoal(args)` | `{ title, objective }` | | `recordReviewBlockers(args)` | `{ goalId, title, objective, evidence, codexGoalJson? }` |

Non-Negotiables

• Write loop state only through the SDK; it lives under `.omo/ulw-loop/<session-id>/` and is never hand-edited. Mutations are serialized across processes by the session's `.state.lock`, so parallel `recordEvidence` calls from workers are safe.
• Register goals up front, shaped by `references/define-goal.md` (`agentToolkit.createGoals({ brief })`, then `create_goal` from the returned handoff), and mirror every atomic step into the live `todo` checklist: one ultra-granular step per action, exactly one in_progress, transitions marked the instant they happen.
• After any compaction or context loss, re-read brief + goals + ledger FIRST plus `agentToolkit.status()` (re-import the SDK if the kernel restarted), then resume; never re-plan from scratch.
• If `createGoals` answers `ULW_LOOP_PLAN_EXISTS_COMPLETE`, this session's aggregate is already done: start unrelated new work in a fresh session instead of steering or forcing the completed state. Use `force: true` only to intentionally overwrite completed evidence.
• Every success criterion needs observable evidence from a real surface: a channel (terminal/TUI via the xterm.js web terminal, HTTP, browser, computer-use) or, for CLI- or data-shaped criteria, an auxiliary surface (CLI stdout, DB diff, parsed config dump).
• Evidence is bound to the tree it was captured at (`git rev-parse --short "HEAD^{tree}"`); it goes stale only when tracke