ultrawork

name	ultrawork
description	Parallel execution engine for high-throughput task completion.

Ultrawork is the Omagy adaptation of OMX Ultrawork: a parallel execution engine for high-throughput task completion. It is a component, not a standalone persistence mode. It provides parallelism, context discipline, and smart delegation guidance, but not Ralph's persistence loop, architect sign-off, deslop, or long-running completion guarantees.

<Use_When>

• Multiple independent tasks can run simultaneously.
• The user says "ulw", "ultrawork", or explicitly wants parallel execution.
• The task benefits from concurrent execution plus lightweight evidence before wrap-up.
• You need a direct-tool lane plus optional background evidence lanes without entering Ralph. </Use_When>

<Do_Not_Use_When>

• The task requires guaranteed completion with persistence, architect verification, deslop, or re-verification; use /omagy:ralph instead because Ralph includes Ultrawork.
• The task requires a full autonomous pipeline; use /omagy:autopilot when that entrypoint is available because Autopilot includes Ralph which includes Ultrawork.
• There is only one sequential task with no parallelism opportunity; execute directly or use one implementer lane.
• The request is still in plan-consensus mode; keep planning artifacts in /omagy:plan --consensus or /omagy:ralplan until execution is explicitly authorized.
• The user needs session persistence or resume guarantees; use /omagy:ralph, which adds persistence on top of Ultrawork. </Do_Not_Use_When>

<Why_This_Exists> Sequential task execution wastes time when tasks are independent. Ultrawork keeps the execution branch fast while tightening the protocol: gather enough context first, define pass/fail acceptance criteria before editing, decide deliberately between local execution and delegation, and finish with evidence rather than vibes. </Why_This_Exists>

<Execution_Policy>

• Start every /omagy:ultrawork run by reading workflow state:

  omagy workflow status --json
  

• Respect internal/contracts/multi-state-transition-contract.md before activation. Direct Ultrawork may coexist only with /omagy:team. If /omagy:ralph, /omagy:plan, or /omagy:code-review is active, do not start Ultrawork as an overlap; complete, cancel, or hand off through the owning workflow first.

• Activate lightweight Ultrawork state before any task execution. Do not run the requested work first and backfill state later:

  omagy state write --input '{"mode":"ultrawork","active":true,"current_phase":"executing","reinforcement_count":1}' --json
  

• Close every activated Ultrawork run through the Omagy workflow runtime. If the run succeeds, execute omagy workflow complete --mode ultrawork with concrete verification evidence before the final user-facing report. If the run cannot continue or the user cancels, execute omagy cancel --mode ultrawork --json. Do not present Ultrawork as complete when neither runtime close path has executed in the current run.

• Gather enough context before implementation. Start with task intent, desired outcome, constraints, likely touchpoints, and uncertainty that would change the execution path.

• If uncertainty is still material after a quick repo read, do a focused evidence pass first instead of immediately editing.

• Define pass/fail acceptance criteria before launching execution lanes. Include the command, artifact, or manual check that proves success.

• Prefer direct tool work when the task is small, coupled, blocked on immediate local context, or touches shared files. Delegate only when the work is independent enough to benefit from parallel execution.

• When useful, run a direct-tool lane and one or more background evidence lanes at the same time. Evidence lanes can cover docs, tests, regression mapping, bounded repo analysis, or external dependency facts.

• Fire independent agy subagent calls simultaneously when they are truly independent. Do not serialize independent work.

• Before first delegation, read internal/shared/agent-tiers.md for Omagy tier selection guidance.

• Use the available Omagy agent roster for lanes: implementer, explorer, analyst, librarian, quality-reviewer, security-reviewer, and verifier. Pick the smallest role that owns the lane.

• Auto-delegate librarian or another evidence lane when official docs, version-aware framework guidance, best practices, or external dependency behavior materially affect task correctness. Treat that lane as evidence, not as the replacement primary workflow.

• Use Antigravity long-running/background execution for operations over about 30 seconds, such as installs, builds, and test suites. Run quick status checks, file reads, and simple commands in the foreground.

• Keep completion claims evidence-bound. Every file field, command result, or behavior claim in the final report must come from an explicit read, command output, subagent result, artifact, or manual QA note from the current run. If a requested fact was not verified in the current run, label it not verified instead of inferring it from memory or surrounding context.

• If the user says continue, continue the active Ultrawork branch rather than restarting discovery or re-asking settled questions. </Execution_Policy>

<Plan_Handoff_Boundary> When the user asks to execute the latest approved plan, approved handoff, PRD, or /omagy:plan output, do not start Ultrawork directly from Plan handoff. Plan-approved execution enters through /omagy:ralph or /omagy:team; Ralph may then use Ultrawork internally as its execution engine.

omagy plan handoff --mode ralph --json
omagy plan handoff --mode team --json

If Plan handoff is missing, ambiguous, or lacks a matching test spec, do not start Ultrawork. Return to /omagy:plan to fix the PRD/test-spec pair or use /omagy:ralph / /omagy:team for approved execution. </Plan_Handoff_Boundary>

<Workflow_Overlap_Boundary> Ultrawork follows Omagy's multi-state transition contract:

• Allowed peer overlap: /omagy:team + /omagy:ultrawork.
• Denied overlap: /omagy:ralph + /omagy:ultrawork, because Ralph already owns the persistence wrapper and may use Ultrawork internally.
• Denied overlap: /omagy:plan or /omagy:code-review + /omagy:ultrawork. Finish or cancel those workflows first, or route execution through /omagy:ralph / /omagy:team.

If activation is denied, clear the incompatible workflow explicitly:

omagy state clear --input '{"mode":"<mode>"}' --json

</Workflow_Overlap_Boundary>

<Artifact_Intake> If the prompt points at an Omagy spec, context, plan, interview, or report artifact, read it through the artifact CLI before shaping execution:

omagy artifact read --input '{"path":"<repo-relative artifact path>","max_bytes":16000}' --json

For substantial work, persist the working plan or completion report as a safe artifact instead of embedding large JSON in workflow state:

omagy artifact write --input '{"path":".omagy/reports/<slug>-ultrawork.md","content":"<markdown report>"}' --json

</Artifact_Intake>

1. **Runtime preflight and activation gate** - Run `omagy workflow status --json`. - If no incompatible workflow is active, activate Ultrawork state with `omagy state write ... active:true` before performing the requested file reads, build/test commands, implementation work, or verification. - Only lightweight shaping is allowed before activation: restating intent, acceptance criteria, constraints, and blockers. Do not read target files, run build/test commands, inspect requested artifacts, or execute task work before activation. 2. **Context + certainty check** - State the task intent in one sentence. - List constraints and unknowns that could invalidate a quick fix. - If confidence is low, inspect first and narrow the task before editing. 3. **Define acceptance criteria before execution** - What must be true at the end? - Which command or artifact proves it? - Which manual QA check is required, if any? - If the user requests `read-only`, `do not modify files`, or equivalent, write the cleanliness acceptance criterion as an attempted verification: "Attempt to verify no workspace changes; if Git or an explicit filesystem audit is unavailable, mark cleanliness `not verified`." Do not phrase the acceptance criterion as "confirm no source code was modified" unless the current run has a suitable audit that can prove it. 4. **Classify dependency shape** - Independent tasks -> parallel lanes. - Shared-file, prerequisite-heavy, or tightly coupled tasks -> local execution or staged lanes. 5. **Choose self vs delegate deliberately** - Work locally when the next step depends on immediate repo context, shared files, or tight iteration. - Delegate when the task slice is bounded, independent, and materially improves throughput. 6. **Run execution lanes** - Direct-tool lane for immediate implementation or verification work. - Background evidence lanes for tests, docs, repo analysis, or regression checks. 7. **Run dependent tasks sequentially** - Wait for prerequisites before launching dependent work. 8. **Close with lightweight evidence** - Build/typecheck passes when relevant. - Affected tests pass. - Manual QA notes are recorded when the task needs a user-visible or behavior-level check. - No new errors are introduced. - Each final claim is backed by a current-run read, command output, subagent result, artifact, or manual QA note.

<Tool_Usage>

• Read internal/shared/agent-tiers.md before selecting delegated lanes.
• Use explorer for simple lookups and bounded repo evidence gathering.
• Use implementer for independent implementation slices.
• Use analyst for complex diagnosis or risky multi-file analysis.
• Use quality-reviewer, security-reviewer, or verifier only as evidence lanes inside Ultrawork. Do not turn their output into Ralph-level sign-off.
• Prefer a direct-tool lane when the immediate next step is blocked on local context.
• Prefer background evidence lanes when they can learn something useful in parallel with implementation.
• Use foreground execution for quick status checks and file operations. </Tool_Usage>

<Evidence_Discipline> Model OMX Ultrawork's evidence-first closure. Ultrawork may be lightweight, but it must not claim success from vibes or stale context.

• Before execution, state the pass/fail acceptance criteria and the evidence source that will prove each one.
• For quick file-field checks, read the named file in the current run and quote or summarize the exact field that was read. Do not report package.json fields, skill frontmatter, README headings, config values, or test names unless they were read or produced by a current-run tool/subagent/artifact.
• If the user asks for parallel work but the work is only quick foreground reads, say that no background lane was needed instead of pretending it was parallelized.
• Treat subagent outputs as evidence only when the subagent reports the files, commands, artifacts, or manual checks it actually inspected.
• Do not write broad claims such as "verified by parallel subagent" without a concrete evidence source. For every subagent-backed field or behavior claim, name the lane role and available lane identity, then list the specific files, commands, artifacts, or manual checks that lane inspected. If a lane identity or inspected source is not available, mark that claim not verified.
• Final verification reports must include an evidence-source column or inline source marker for every requested acceptance criterion: direct tool read, command output, artifact path, manual QA note, or subagent lane role/id. Do not group several requested fields under one generic "parallel subagent" source unless the lane report explicitly covers every grouped field.
• Name the host evidence surface exactly enough to match the current run. In Antigravity, prefer Read(...), Bash(...), artifact paths, manual QA notes, or subagent lane role/id. Do not write stale Codex-specific labels such as view_file unless that is the tool surface actually shown in the current host transcript.
• Treat read-only, no files modified, no source changes, and similar workspace-cleanliness claims as verification claims. When the workspace is a git repository, prove them with current-run git status --short or git diff --stat output. If git is unavailable, either use an explicit current-run filesystem audit suitable for the requested scope, or label the cleanliness claim not verified.
• Acceptance criteria must not pre-claim cleanliness. For read-only requests, write "attempt to verify no workspace changes" rather than "confirm no source code was modified" unless a current-run audit can actually prove it.
• The final report's acceptance-criteria labels must follow the same rule. Do not use a left-column label such as "do not modify files", "no files modified", or "不修改任何文件" when the evidence is not verified. Use "attempted workspace cleanliness verification" or "尝试验证无工作区变更" instead, then put not verified in the result/evidence column when the audit fails or is unavailable.
• Do not write "no source files were modified", "no files were modified", or equivalent wording after a failed or unavailable cleanliness check. Use the narrower wording: "No source-writing tool call was observed; workspace cleanliness is not verified."
• This applies to final notes as well as the evidence table. If the evidence table says workspace cleanliness is not verified, the closing note must not say "As requested, no files were modified" or any equivalent. Use the exact narrow form instead: "No source-writing tool call was observed; workspace cleanliness is not verified because <cleanliness command> failed or was unavailable."
• Final reports must separate verified evidence from unverified or inferred facts. Use not verified for anything requested but not checked in the current run.
• Do not complete Ultrawork in prose only. The current run must execute omagy workflow complete --mode ultrawork with concrete verification evidence, or execute omagy cancel --mode ultrawork --json if the workflow is stopped before successful completion. </Evidence_Discipline>

<State_Management> Use Omagy CLI state and workflow commands for Ultrawork lifecycle state.

• On start:

  omagy state write --input '{"mode":"ultrawork","active":true,"current_phase":"executing","reinforcement_count":1}' --json
  

• On each reinforcement or continuation:

  omagy state write --input '{"mode":"ultrawork","state":{"reinforcement_count":2}}' --json
  

• On completion:

  omagy workflow complete --mode ultrawork --input '{"verification_evidence":["<command, artifact, or manual QA note>"]}' --json
  

• On cancellation or cleanup:

  omagy cancel --mode ultrawork --json
  

The Omagy Stop hook blocks active non-terminal Ultrawork state. It also blocks terminal Ultrawork state that lacks verification evidence. If Stop blocks, run omagy workflow next --json and continue from that instruction.

Terminal handoff follows internal/contracts/explicit-terminal-stop-model.md: report exactly one canonical lifecycle outcome (finished, blocked, failed, userinterlude, or askuserQuestion), concrete evidence, artifacts/state, and the required handoff. Do not present complete, cancelled, or blocked_on_user as the lifecycle outcome. </State_Management>

<Code_Review_Boundary> When code changes need review, merge readiness, or an independent final check, run /omagy:code-review as a read-only review pass and use its findings as normal evidence. Plain code-review does not write workflow gate state.

Ultrawork completion remains lightweight: fresh verification evidence is required. Review findings are not accepted as a direct Ultrawork runtime gate; handoff to Ralph when the workflow needs review-gated completion. </Code_Review_Boundary>

Two-track execution with acceptance criteria up front:

Acceptance criteria:
- `npm run build` passes
- Affected plan contract tests pass
- Manual QA: verify `/omagy:ultrawork` describes the active state path

Direct-tool lane:
- Update `skills/ultrawork/SKILL.md`

Background evidence lane:
- Invoke `verifier` to map which tests cover Ultrawork activation messaging

Why good: Context is grounded first, acceptance criteria are explicit, and the direct-tool lane runs alongside a bounded evidence lane.

Correct self-vs-delegate judgment:

Shared-file edit in progress across workflow runtime and its tests -> keep
implementation local.
Independent regression mapping for hook coverage -> delegate to verifier.

Why good: Shared-file work stays local; independent evidence work fans out.

Parallelizing before the task is grounded:

Invoke implementer: "Implement whatever seems necessary."
Invoke verifier: "Figure out how to test it later."

Why bad: No context, no pass/fail target, and delegation starts before the work is shaped.

Claiming success without evidence:

Made the changes. Ultrawork should be updated now.

Why bad: No verification output, no acceptance evidence, and no manual QA note when behavior is user-visible.

Reporting fields that were not read in the current run:

README, package.json, and skills/ultrawork/SKILL.md are all consistent.

Why bad: The final claim names three artifacts but does not show current-run reads, command output, subagent evidence, or artifact evidence for each one. Read each artifact or mark the unchecked facts as not verified.

Using a generic subagent source without lane evidence:

README.md, package.json, and SKILL.md were verified by parallel subagent.

Why bad: This hides which lane produced which evidence and which file each lane actually inspected. Name the lane role/id and inspected source for each claim, or mark the claim not verified.

Pre-claiming cleanliness in acceptance criteria:

Acceptance criteria:
- Confirm no source code was modified.

Evidence:
- Workspace cleanliness: not verified because git status failed.

Why bad: The acceptance criterion promises proof that the run does not have. For read-only requests, write: "Attempt to verify no workspace changes; if Git or explicit filesystem audit is unavailable, mark cleanliness not verified."

Pre-claiming cleanliness in the final report label:

验收标准               | 验证证据
不修改任何文件         | 工作区整洁度：未验证 (git status failed)

Why bad: The left column still states an unproven acceptance condition even though the evidence column says it was not verified. Write the label as "尝试验证无工作区变更" or "attempted workspace cleanliness verification" instead.

Claiming no files were modified without a cleanliness check:

npm run build passed. No files were modified.

Why bad: Build commands may write generated outputs, timestamps, caches, or permissions. Run git status --short, git diff --stat, or an explicit filesystem audit before claiming workspace cleanliness. If no suitable audit is available, say not verified.

Contradicting an unverified cleanliness check:

No source files were modified. Workspace cleanliness: not verified via Git.

Why bad: The first sentence is still an unverified cleanliness claim. If the audit failed or is unavailable, say only: "No source-writing tool call was observed; workspace cleanliness is not verified."

Contradicting the evidence table from a final note:

Workspace Cleanliness: Not verified. git status --short failed.

NOTE: As requested, no files were modified.

Why bad: The note upgrades an unverified cleanliness result into a verified claim. The final note must use the same narrow wording as the evidence table: "No source-writing tool call was observed; workspace cleanliness is not verified because git status --short failed."

Backfilling runtime state after task execution:

Read README.md, read package.json, ran npm run build, then wrote
omagy state write active:true.

Why bad: Ultrawork lifecycle state was activated after the requested work had already happened. Only intent/criteria/blocker shaping may happen before activation; file reads, build/test commands, and verification must happen after omagy state write ... active:true.

Using the wrong host evidence label:

Evidence source: current session view_file read of README.md.

Why bad: If Antigravity displayed Read(...), the evidence source should say Read(...) or equivalent current-host wording. Do not use Codex-only labels unless they actually appeared in the current run.

Completing only in prose without closing runtime state:

Verification passed. Ultrawork execution is complete.

Why bad: /omagy:ultrawork must activate runtime state before execution and must close that state with omagy workflow complete --mode ultrawork plus verification evidence, or omagy cancel --mode ultrawork --json if the run does not complete.

<Escalation_And_Stop_Conditions>

• When Ultrawork is invoked directly, apply lightweight verification only: build/typecheck passes when relevant, affected tests pass, and manual QA notes are captured when needed.
• Ralph owns persistence, architect verification, deslop, and the full verified-completion promise. Do not claim those guarantees from direct Ultrawork.
• If a task fails repeatedly across retries, report the issue rather than retrying indefinitely.
• Escalate to the user when tasks have unclear dependencies, conflicting requirements, or a materially branching acceptance target. </Escalation_And_Stop_Conditions>

<Final_Checklist>

• omagy workflow status --json ran and Ultrawork state was activated before requested file reads, build/test commands, implementation work, or verification.
• Task intent and constraints were grounded before editing.
• Pass/fail acceptance criteria were stated before execution.
• Read-only/no-modification acceptance criteria are phrased as attempted verification unless the current run has a real cleanliness audit.
• Final report labels do not use "do not modify files", "no files modified", or "不修改任何文件" when the evidence is not verified; they use attempted-verification wording instead.
• Parallel lanes were used only for independent work.
• Build/typecheck passes when relevant.
• Affected tests pass.
• Manual QA notes were recorded when behavior is user-visible.
• No new errors were introduced.
• Every file-field or behavior claim in the final report is backed by a current-run read, command output, subagent result, artifact, or manual QA note.
• Every subagent-backed claim names the lane role/id when available and the exact inspected files, commands, artifacts, or manual checks.
• The final report has an evidence source for each requested acceptance criterion, rather than a generic grouped "parallel subagent" claim.
• Evidence sources use the current host's actual tool names/surfaces, such as Antigravity Read(...) and Bash(...), rather than stale tool labels.
• Any read-only or no files modified claim is backed by current-run git status --short, git diff --stat, or an explicit filesystem audit; otherwise it is labeled not verified.
• The closing note does not override a not verified cleanliness result with broader wording such as "As requested, no files were modified".
• Completion claim stays inside Ultrawork's lightweight-verification boundary.
• omagy workflow complete --mode ultrawork recorded verification evidence, or omagy cancel --mode ultrawork cleaned up a stopped run.
• The final report does not claim Ultrawork completion unless the current run executed one of those runtime close paths. </Final_Checklist>

## Relationship to Other Modes

/omagy:ralph (persistence + verified completion wrapper)
  includes: /omagy:ultrawork
    provides: high-throughput execution + lightweight evidence

/omagy:autopilot (future autonomous execution)
  includes: /omagy:ralph
    includes: /omagy:ultrawork

Ultrawork is the parallelism and execution-discipline layer. Ralph adds persistence, architect verification, deslop, and retry-until-done behavior. Autopilot adds the broader autonomous lifecycle pipeline.