/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 }, warnings? }`. `nextActions` are things to do next; `warnings` are facts to know (a fallback the binder took, a driver objective that differs). 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>/`. When `PI_SESSION_CWD` is missing (seen after an extension reload restarted the kernel), the binder falls back to the cwd recorded in the `PI_SESSION_FILE` header, then to `process.cwd()`, and every envelope carries a warning naming the fix: `env("PI_SESSION_CWD", "<session cwd>")`. `status().result.binding` shows `{ cwd, cwdSource, sessionId, goalStorePaths }`, so check it after any kernel restart and re-pin the env when `cwdSource` is not `PI_SESSION_CWD`.
• 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; `result.operations[]` carries `method` (the camelCase name to call), `args` (field -> type, `?` = optional), `description`, `mutating` — enough to recover every call below after a kernel restart | | `status()` | none; `result` carries `plan`, `summary`, `nextActions`, `evidenceRoot` (stable plan-level artifact dir), `currentAttemptDir` (moves with the active goal), `binding` (`cwd`, `cwdSource`, `sessionId`, `goalStorePaths`), `driver` (`available`, `status`, `objectiveMatchesPlan`, `objectiveAcknowledged`) | | `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?, artifacts? }`; every `artifacts` path must exist (resolved against the session cwd, `ULW_LOOP_EVIDENCE_ARTIFACT_MISSING` otherwise) and is stored on the criterion and the ledger entry, repo-relative when inside the cwd | | `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, successCriteria? }` with `successCriteria: [{ scenario, expectedEvidence, userModel?, essential? }]`; omit it and the three seeded placeholders name the exact `steer({ kind: "revise_criterion", ... })` call that replaces each one | | `recordReviewBlockers(args)` | `{ goalId, title