Executes a written ulw-plan work plan with Boulder state, evidence ledger, worktree discipline, and parallel subagents. Use when the user says ulw-execute or asks to run a .omo/plans plan.
Install
Use withClaudeCursorCodex
The file stays in the publisher's repository. PlugMCP does not host or rewrite it.
Executes a written ulw-plan work plan with Boulder state, evidence ledger, worktree discipline, and parallel subagents. Use when the user says ulw-execute or asks to run a .omo/plans plan.
name: ulw-execute
description: "Executes a written ulw-plan work plan with Boulder state, evidence ledger, worktree discipline, and parallel subagents. Use when the user says ulw-execute or asks to run a .omo/plans plan."
argument-hint: "[plan-name] [--worktree ] [--make-pr] [--ship]"
ABSOLUTE RULE: YOU ARE AN ORCHESTRATOR — NEVER THE IMPLEMENTER
YOU DO NOT WRITE CODE. YOU DO NOT EDIT PRODUCT FILES. YOU DO NOT RUN QA YOURSELF. EVERY unit of implementation, test, QA, and review work MUST be delegated to a spawned subagent. NO EXCEPTIONS. Your hands touch only plan selection, .omo/ state (Boulder, ledger, plan checkboxes), decomposition, dispatch, verdicts, and evidence records. About to edit a product file or run an implementation command yourself? STOP. SPAWN A WORKER INSTEAD. Orchestrate at MAXIMUM PARALLELISM: every independent unit runs concurrently; only named dependencies serialize.
Codex Harness Tool Compatibility
Translate any OpenCode-only tool name in an inherited example to its Codex equivalent:
OpenCode example
Codex tool to use
final-review task(...)
multi_agent_v1.spawn_agent({"message":"TASK: act as a rigorous reviewer. ...","agent_type":"lazycodex-gate-reviewer","fork_context":false})
worker task(...)
multi_agent_v1.spawn_agent({"message":"TASK: act as <role>. ...","fork_context":false}) — for implementation workers add `agent_type: "lazycodex-worker-<low
background_output(task_id="...")
multi_agent_v1.wait_agent(...) for mailbox signals
When translating load_skills=[...], name the skills inside the spawned agent's message. If a code block below conflicts with this section, this section wins.
Codex exposes ONE of two subagent tool surfaces per session; check your own tool list and route accordingly. If multi_agent_v1.* tools exist, use the table above as written. If instead a flat spawn_agent with a required task_name exists (multi_agent_v2), rewrite every multi_agent_v1.* example: multi_agent_v1.spawn_agent({...,"fork_context":false}) becomes spawn_agent({"task_name":"<lowercase_digits_underscores>","message":...,"agent_type":...,"fork_turns":"none"}) ("all" only when full parent history is truly required); send_input becomes send_message; do not call close_agent/resume_agent (finished agents end on their own; followup_task re-tasks one, interrupt_agent stops one); wait_agent takes only timeout_ms and returns on any child mailbox activity. On the v2 surface agent_type may be absent from the spawn schema — when absent, omit it and describe the role inside message. If a code block below conflicts with this section, this section wins.
Codex tier mapping for the delegation router
When tier worker agents are installed, map the delegation router's parenthesized difficulty to agent_type: (low) -> lazycodex-worker-low; (medium) -> lazycodex-worker-medium; (high) -> lazycodex-worker-high. Explorer/librarian research lanes keep their own roles. On spawn surfaces without agent_type, state the tier inside message. Difficulty (model power) is orthogonal to the LIGHT/HEAVY rigor tier in step 4 — judge each on its own facts.
Codex Subagent Reliability
Every multi_agent_v1.spawn_agent message is a self-contained executable assignment: TASK: <imperative assignment>, then DELIVERABLE, SCOPE, and VERIFY, with role instructions inside message. Use fork_context: false unless full history is truly required; paste only the context the child needs.
Plan and reviewer agents may run for a long time: spawn them in the background and keep doing independent root work. Between multi_agent_v1.wait_agent calls, back off — double the timeout up to ~5 minutes — instead of spinning short cycles. A timeout only means no new mailbox update arrived; treat a running child as alive. Require WORKING: <task> - <current phase> before long passes and BLOCKED: <reason> only when progress stops. Keep the parent visibly alive with active subagent count, names, and latest WORKING: phase. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly BLOCKED:, or no longer running — then record inconclusive (never a pass), close if safe, and respawn a smaller fork_context: false task with the missing deliverable.
ulw-execute
Execute a work plan until every top-level checkbox is [x] or [~]. This skill pairs with the harness's ulw-execute continuation hook, which re-injects the next turn while .omo/boulder.json says this codex:<session_id> still has unchecked plan work.
plan-name (optional): a full or partial file stem under .omo/plans/.
--worktree (optional): reuse an existing task-owned worktree for the first phase instead of creating one; every phase runs in a task-owned worktree regardless.
--make-pr (optional): deliver each phase's worktree as a pull request — push the branch, open a reviewer-readable PR, hand off with the URL, and merge only if the user asks.
--ship (optional): full delivery lifecycle; implies --make-pr. After the PR opens, stay on the job until it is MERGED: watch CI and review gates, fix failures and address feedback from the worktree (fresh QA evidence for behavior changes), merge per the repository's merge policy, then remove the worktree and sync .omo/ state back.
Goal and todo discipline (MANDATORY)
Do ALL of this immediately after the plan is selected, BEFORE the first implementation dispatch. Skipping any step is a defect.
Set the goal, in detail. When a goal tool is available (create_goal), call it with a DETAILED objective: the plan name and path, the concrete end state, the phase and task counts, the delivery mode (direct, --make-pr, or --ship), and how completion will be verified. One work session = one registered goal (the goal tool holds one active goal); each phase then carries its own concrete goal — the ledger entry Phase 2 records before the wave's first dispatch, defined from the previous phase's landed and verified evidence. No goal tool -> record the same objective as the first ledger entry.
Register every phase and task as todos. Mirror the plan into the todo/plan tool of your harness: one phase per plan wave, one todo per column-zero checkbox (including the final verification wave). Register ALL of them up front - never keep tasks in memory only.
Keep them current at every moment. Mark a todo in_progress when its work dispatches and done immediately after its verification passes. Never batch-complete at the end, never execute work that is not a registered todo; discovered work inside the change's blast radius — the request not delivered, a regression this change introduces, an invalid proof, a failing test or stale doc of touched code — is appended to the plan as a follow-up checkbox after the checkpoint in progress, mirrored as a todo, and fixed to the ideal state once that checkpoint closes; it joins the open checkpoint only when it blocks that checkpoint's acceptance; a defect outside it gets a tracked issue with reproduction and evidence and a line in the final report. A worker that meets a defect outside its assigned files reports it instead of fixing it; only the orchestrator appends the checkbox and dispatches it to a correctly scoped unit. The todo list, Boulder state, and plan checkboxes must always tell the same story.
Phase 1: Select the plan
Read .omo/boulder.json if it exists.
List work plan files under .omo/plans/.
If plan-name was provided, select the matching plan.
If exactly one active or paused Boulder work exists for this session, resume it.
If no active work exists and exactly one plan exists, select it.
If no active work exists and there is no selectable plan, enter No-plan bootstrap.
If multiple plans remain possible, ask one focused selection question.
No-plan bootstrap
When the user explicitly said start work / $ulw-execute and no selectable plan exists, treat that phrase as approval: bootstrap ulw-plan to create the approved plan before execution and implementation, instead of stalling or asking for generic approval again. A brief or notes file without waves, checkboxes, and acceptance criteria is NOT decision-complete — enter this bootstrap too.
Invoke the ulw-plan skill from the current request and require its dynamic adversarial workflow: collect, verify, design, adversarial plan-review, synthesize.
The generated work plan must be saved under .omo/plans/<slug>.md before implementation or Boulder state writes that point at plan work.
Use maximum safe parallelism in the generated plan: independent files/tasks fan out; same-file writes, shared state, and named dependencies serialize.
Preserve safety boundaries. Ask one focused question only when the objective is missing, destructive, or has a safety/product ambiguity that repository exploration cannot resolve.
After the plan exists, continue directly to Phase 2.
Phase 2: Create or update Boulder state
Write .omo/boulder.json before implementation starts. Prefix session ids with codex: so the continuation hook can identify its own session.
Every phase (plan wave) runs in its own task-owned worktree with its own goal: before the wave's first dispatch, record the wave's goal — its checkboxes and their acceptance criteria — as a ledger entry, then git worktree add <repo>-wt/<plan>-<wave> <branch off the integration base> (or verify a --worktree path with git worktree list --porcelain), store the absolute path as worktree_path, run every edit, command, test, and evidence capture inside it; the wave lands on the integration base once each of its checkboxes is verified or [~] (direct merge, or the PR under --make-pr/--ship; a [~] row's unverified changes do not land: a dispatched worker reverts them in the wave worktree before landing, and the unmet entry records the revert), and the next wave branches from that landed base. Use the bundled ultrawork directive’s Task resources and todo rules at wave/worktree creation; read those sections if absent from context.
Parallel delivery lanes (teams and worktrees)
Solo orchestration with parallel background workers is the default topology. Decide once, when the wave's lanes are known, and record the verdict in the ledger:
Independent lanes -> parallel workers. Separate files, no shared contract: one parallel spawn burst; no team.
Dependency-ordered lanes -> one workflow run per wave. Sub-tasks with real ordering between them (C needs A and B finished first) and a harness with a native workflow tool: dispatch the wave as ONE run (one producer node per lane plus a verification node); recover inside it with retry/amend/send; let the run's settle wake you instead of arming per-lane watchers; the next wave is a NEW run (or amend when only the definition changed) — never one graph for the whole plan. Read the mass-ulw skill's SKILL.md and references/planning.md IN FULL before defining any graph.
Overlapping lanes -> a team. The lanes touch the same module or contract AND running them concurrently actually finishes sooner: stand up a team (where the harness has one) so one lane's discoveries relay through you mid-flight.
PR-mode independent lanes -> a worktree per lane. Under --make-pr/--ship, when a wave holds independent checkboxes, give each lane its own branch and task-owned worktree, delivered as its own PR.
Landing rules, regardless of topology:
Merge per verified unit. A lane lands the moment its own gates pass — it never waits for the slowest sibling. Integrate landed work back into the base the remaining lanes branch from.
Only the orchestrator merges. Workers and team members never merge and never push the base branch.
Conflicts are the orchestrator's job. Decide the landing order and tell the later lane what changed; a worker never resolves a sibling's conflict blind.
Phase 3: Execute the next checkbox
Read the full selected plan.
Find the first unchecked column-0 checkbox in ## TODOs or ## Final Verification Wave.
Ignore nested checkboxes under acceptance criteria, evidence, and definition-of-done sections.
Classify the checkbox tier and record it in its ledger entry. Default is LIGHT — a narrow change inside existing layers. Take HEAVY only on a fact you can point to: a new module / abstraction / domain model; auth, security, or session; an external integration; a DB schema or migration; concurrency or transaction boundaries; a cross-domain refactor; or the plan or user signals care. When unsure, take HEAVY; upgrade and redo skipped gates the moment a HEAVY fact surfaces; never downgrade.
Decompose that checkbox into atomic sub-tasks sized for ONE worker in ONE run — a sub-task that would need mid-flight steering is two sub-tasks. Collect every other unchecked checkbox in the same plan wave whose dependencies are met — their lanes execute concurrently. A wave that could split further but holds fewer than 3 independent sub-tasks is under-split.
DELEGATE EVERYTHING. YOU NEVER IMPLEMENT. Route every sub-task through the delegation router below, then dispatch ALL independent sub-tasks across those checkboxes in one parallel worker-spawn burst (a single batched spawn call where the harness supports it); route named dependencies per the lane-topology decision above. Verification and checkbox marking stay per-checkbox.
Give every dispatched sub-task its completion condition and watch for it per the section below. A dispatch whose completion nobody watches is an unfinished dispatch.
Monitor every dispatched subagent to its completion condition
A spawned worker is not fire-and-forget. For EACH subagent in the burst, name the observable state that ends its lane — the file written, the PR opened, the checkbox's gates green — and put a watcher on THAT state, never on a clock.
Arm one watcher per lane, at spawn time. The worker's own completion arrives on its own as an injected notification; arm an explicit monitor on top of it only when the lane's completion condition lives OUTSIDE the child's final message — CI turning green, a log line, a build artifact appearing, a branch landing. Watch the state itself (monitor with a command that exits or emits on that condition), and keep the burst's watchers distinct so one lane firing never reads as another's.
NEVER poll and NEVER sleep. No sleep, no timed retry loop, no re-reading the same status hoping it changed. Between waves, do independent root work or end the turn; an idle session is always woken. A single task_output({ mode: "tail" }) peek is allowed only when a midpoint decision genuinely depends on it.
Tear the watcher down the instant it resolves. The moment a monitor fires, or you discover it was armed on the WRONG condition (it watches a path the lane never touches, a pattern that can never match, a lane you already cancelled), stop it with kill_bash and say so in the ledger. A stale watcher re-fires on unrelated output and corrupts the next wave's verdict.
Then advance. Fired watcher plus verified evidence means that lane's gates run and its checkbox closes; a mis-set watcher means re-arm it on the right condition or drop it, and continue. Never let a dead watcher hold the run open, and never treat watcher silence as a pass.
When the plan annotates a todo with Recommended task executor category:, follow that annotation; deviate only for a reason recorded in the ledger entry. Otherwise route by shape, in the omo category vocabulary (category-capable harnesses pass it directly on the worker-spawn tool, e.g. task(category="quick", ...); others map the parenthesized difficulty):
Category
Route here
quick (low)
mechanical, single-file, boilerplate, config/copy — the default for every splittable piece
unspecified-low (low)
small tasks that fit no other category
unspecified-high (medium)
standard features across a few files with known patterns
visual-engineering (medium)
frontend, UI/UX, styling, animation
writing (low)
documentation and prose
git (low)
git operations
deep-low (medium)
hairy debugging, research-heavy or subtle cross-module work the worker can settle from what it reads
deep-high (high)
the same, when the central decision cannot be settled from evidence: a trade-off, a cross-package contract, or correctness argued from invariants
ultrabrain (high)
ONE genuinely hard, logic-heavy problem — hand it the goal, not step-by-step instructions
Sizing is a two-branch decision made per checkbox, before dispatch:
Splittable work splits. When the checkbox decomposes into independent pieces, dispatch them as a swarm of quick/unspecified-low workers in ONE parallel burst — many small cheap workers in parallel beat one large delegation.
Cohesive hard work stays whole. When splitting would sever shared reasoning (one algorithm, one migration, one subtle bug), send the WHOLE problem to deep-low, deep-high or ultrabrain as ONE delegation. Never force-split work whose parts share one insight.
Each sub-task message must include:
Goal and exact files or directories in scope.
The tests already covering the touched behavior, READ before any edit as the behavior of record (intent, coverage, pass); a bug's reproduction captured before the fix. A new test ONLY where the repository keeps tests for this behavior AND a regression would otherwise pass unnoticed by the sub-task's Manual-QA scenario — never one that mirrors its implementation (mock-call assertions, pinned constants) or restates the change.
Implementation constraints from the plan and project rules.
Automated verification commands to run.
One Manual-QA channel, named with the exact tool and exact invocation (the literal curl, send-keys, page.click / session.click, payload, selectors, and the binary observable that decides PASS/FAIL), not "verify it works". A LIGHT checkbox needs one real-surface proof of its deliverable, and auxiliary surfaces (CLI stdout, DB state diff, parsed config dump) are first-class when the surface is CLI- or data-shaped:
HTTP call: curl -i against the live endpoint.
Terminal / TUI: drive a real pty; tmux send-keys is fine for a boot/behavior smoke, but color/layout/CJK evidence goes through the xterm.js web terminal below, NEVER tmux capture-pane.
Browser use: omowright from js eval (staged in the browser skill) — the owned engine (connectPipe on a task-owned profile, connectCloakProfile for bot-scored targets) for unauthenticated pages, the attached engine (connectBrowserSkill() in the user's signed-in browser) when the page needs their login; never a clone of or a launch against the live profile.
Computer use: OS-level GUI automation against the running desktop app when the surface is not a page.
TUI visual evidence: when a TUI claim needs visual QA or PR proof, run bun script/qa/web-terminal-visual-qa.mjs --command "<cmd>" --input "{Enter}" --evidence-dir <dir> (real pty rendered through xterm.js in Chrome) and attach terminal.png plus metadata.json.
The adversarial classes that apply to this sub-task (from the 9 ultraqa classes) and how each is probed.
Required artifact path and cleanup receipt.
Tool-use expectations: batch independent tool calls in parallel; when the harness exposes a code-execution surface (eval), use it for multi-call steps instead of one-by-one calls.
The 9 ultraqa classes are trigger-mapped: new input parsing → malformed input; untrusted external text → prompt injection; resumable or long-running flows → cancel/resume; generated or cached artifacts → stale state; uncommitted user files in scope → dirty worktree; long external commands → hung or long commands; new or timing-sensitive tests → flaky tests; log-based success claims → misleading success output; mid-operation interrupts → repeated interruptions. A class applies when its trigger fact holds. Probe each applicable class; record the rest as not-applicable with a one-line reason.
Phase 4: Verify and record evidence
For each checkbox, complete all five gates before marking it done:
Plan reread: confirm the checkbox and acceptance criteria.
Automated verification: run tests, typecheck, lint, build, or the plan-specific equivalent.
Manual-QA channel: capture a real artifact, not a dry-run claim.
Adversarial QA: exercise every class the Phase 3 trigger map marks applicable and capture the observable result for each.
Cleanup: register every QA resource teardown as its own todo when spawned (QA scripts, tmux assets, browser sessions, PIDs, ports, containers, temp dirs), execute each, and capture the receipt. No QA asset is left running.
Append evidence to .omo/ulw-execute/ledger.jsonl, one JSON object per line. Include at least event, plan, task, session_id, commands, artifact, adversarial_classes, and cleanup fields, plus attempt and checkpoint_opened_at on every entry tied to a checkbox. adversarial_classes lists each probed class with its observable result and each ruled-out class with a one-line reason.
Completion contract
A worker done claim is never final: each implementation sub-task returns a DoneClaim, a different context runs AdversarialVerify probing or reproducing the claim, failures loop back to the executor, and only a confirmed verifier verdict becomes FullyDone.
confirmed is the only pass verdict. false-positive, needs-fix, and needs-human-review all block checkbox completion.
The verifier must be independent from the executor: use the harness's gate reviewer (see the harness compatibility section) or a fresh reviewer worker on a strong model, or root only when root did not implement or materially rewrite that task.
A worker done claim must be independently verified before it becomes checkbox completion.
On a non-confirmed verdict, append the feedback to the ledger with the attempt number and its failure signature (the failing check plus its first error line, with volatile values stripped: temp-dir paths, timestamps, process and run ids, durations). Attempts count per checkbox across all its sub-tasks and re-splits, timed from its first dispatch (checkpoint_opened_at). STOP when the same signature repeats on consecutive attempts, on the third failed attempt, or 4 hours after the first dispatch (a plan may change these numbers, never remove the stop). Check the 4-hour bound also when a lane's watcher fires or the turn resumes without a verdict; when it has passed, cancel that lane and stop the same way: mark the checkbox - [~] (the plan grammar's blocked state) with a one-line gap naming what is unmet and the last evidence, mark every checkbox that depends on it, directly or through another [~] row, - [~] with the gap blocked by <id>, close the todo of every row marked [~] here labelled blocked: <gap>, append an unmet ledger entry listing what each attempt changed, and continue in the same turn with the next checkpoint that depends on none of them, or with Completion when none remains. Otherwise leave the checkbox - [ ] and re-dispatch the executor with the exact failure.
A [~] row counts as closed, never as a met dependency: Phase 3 skips it, Completion starts once every top-level row is [x] or [~], and the ORCHESTRATION COMPLETE block names each [~] row with its gap. Final Verification Wave rows are never dependents of a [~] row: they verify the landed work and report each [~] row as a known gap, which alone never fails a final-wave row. A [~] gap is never re-queued as a new checkbox in this run, by the blast-radius rule or by a final-wave verdict; the one harness-repair follow-up in the next rule is the only exception.
The verifier sets failure_class. A harness failure (the runner, fixture, CI job or environment failed and the product behavior was never exercised) gets one repair dispatch inside the checkpoint, which does not count as an attempt; when it recurs, stop as above with the harness gap named and append the harness repair once as a follow-up checkbox; a harness-repair follow-up that stops is reported, not re-appended.
The verifier must probe the applicable adversarial keys, including stale_state, dirty_worktree, and misleading_success_output, before allowing FullyDone.
Phase 5: Mark progress
Only after verification passes:
Edit the plan checkbox from - [ ] to - [x].
Re-read the plan and confirm the remaining count decreased.
Append a task-completed ledger entry.
Continue with the next checkbox. Do not ask whether to continue.
Completion
When all top-level checkboxes in ## TODOs and ## Final Verification Wave are complete:
Run the plan's final verification commands.
For PR/branch work, finish the lifecycle from the last phase's worktree: sync .omo/ state back to the main repo, create or update the PR, wait for review/verification gates, merge by default unless explicitly opted out, and remove the worktree only after successful merge or explicit handoff. Finish directory teardown per Task resources and record its receipts.
Remove or mark the Boulder work as completed.
Print an ORCHESTRATION COMPLETE block with the plan path, verification commands, artifacts, and cleanup receipts.
Hard rules
No production change before the tests covering that behavior were read and a bug's reproduction captured; existing tests are green on the unchanged code first, and one that contradicts the intent is a FINDING, never edited green.
No --dry-run as completion evidence.
No tests-only completion claim. A Manual-QA artifact is required.
NO DIRECT IMPLEMENTATION BY THE ORCHESTRATOR. Root NEVER edits product files, writes tests, or runs QA itself — a spawned worker does.
No completion claim while an applicable ultraqa adversarial class was never probed. Each applicable class needs a captured observable result; each skipped class needs a one-line not-applicable reason in the ledger.
No implementation, review, or merge in the main checkout; every phase works in its task-owned worktree.
No unprefixed session ids in Boulder state. Sessions are always recorded as codex:<session_id>.
No stale-memory execution. The plan and ledger are the durable source of truth.
How do I install ulw-execute?
Download packages/shared-skills/skills/ulw-execute/SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
Where does ulw-execute live?
The publisher keeps it at https://github.com/code-yeongyu/oh-my-openagent.
Which agents can use ulw-execute?
Claude, Cursor, and Codex can read a SKILL.md you add from the publisher's repository.