From d1532ba30f3454a4dc0f48dfd9eee28186533115 Mon Sep 17 00:00:00 2001 From: YeonGyu-Kim Date: Sat, 30 May 2026 19:12:15 +0900 Subject: [PATCH] docs(omo-codex): batch 87 (11 files) --- .../plugin/components/ultrawork/.gitignore | 5 + .../plugin/components/ultrawork/AGENTS.md | 41 +++ .../plugin/components/ultrawork/CHANGELOG.md | 25 ++ .../plugin/components/ultrawork/LICENSE | 21 ++ .../plugin/components/ultrawork/NOTICE | 5 + .../plugin/components/ultrawork/README.md | 60 ++++ .../plugin/components/ultrawork/biome.json | 48 ++++ .../plugin/components/ultrawork/directive.md | 262 ++++++++++++++++++ .../plugin/components/ultrawork/package.json | 54 ++++ .../components/ultrawork/tsconfig.build.json | 12 + .../plugin/components/ultrawork/tsconfig.json | 27 ++ 11 files changed, 560 insertions(+) create mode 100644 packages/omo-codex/plugin/components/ultrawork/.gitignore create mode 100644 packages/omo-codex/plugin/components/ultrawork/AGENTS.md create mode 100644 packages/omo-codex/plugin/components/ultrawork/CHANGELOG.md create mode 100644 packages/omo-codex/plugin/components/ultrawork/LICENSE create mode 100644 packages/omo-codex/plugin/components/ultrawork/NOTICE create mode 100644 packages/omo-codex/plugin/components/ultrawork/README.md create mode 100644 packages/omo-codex/plugin/components/ultrawork/biome.json create mode 100644 packages/omo-codex/plugin/components/ultrawork/directive.md create mode 100644 packages/omo-codex/plugin/components/ultrawork/package.json create mode 100644 packages/omo-codex/plugin/components/ultrawork/tsconfig.build.json create mode 100644 packages/omo-codex/plugin/components/ultrawork/tsconfig.json diff --git a/packages/omo-codex/plugin/components/ultrawork/.gitignore b/packages/omo-codex/plugin/components/ultrawork/.gitignore new file mode 100644 index 000000000..f3d1d95e2 --- /dev/null +++ b/packages/omo-codex/plugin/components/ultrawork/.gitignore @@ -0,0 +1,5 @@ +__pycache__/ +*.pyc +.DS_Store +.env +.env.* diff --git a/packages/omo-codex/plugin/components/ultrawork/AGENTS.md b/packages/omo-codex/plugin/components/ultrawork/AGENTS.md new file mode 100644 index 000000000..e2f314848 --- /dev/null +++ b/packages/omo-codex/plugin/components/ultrawork/AGENTS.md @@ -0,0 +1,41 @@ +# Repository Conventions + +Conventions for human contributors and AI agents working on this repository. + +## Style + +- Terse technical prose. No emojis in commits, issues, PR comments, or code. +- TypeScript strict mode. No `any`, no `@ts-ignore`, no `@ts-expect-error`, no enums, no non-null assertions. +- ESM modules with `.js` suffix in runtime import paths. +- Runtime is Node only because Codex launches plugin hooks with Node. +- Tabs for indentation in JSON, TypeScript, and Markdown tables. +- Double quotes for JSON strings. + +## Layout + +- `src/cli.ts` — `UserPromptSubmit` hook CLI. Reads JSON on stdin, writes the directive to stdout when the keyword matches, exits 0 otherwise. +- `src/codex-hook.ts` — pure detector/hook behavior. +- `directive.md` — bundled ultrawork directive text. +- `agents/*.toml` — bundled Codex agent role files. Installed into `CODEX_HOME/agents/` by `src/cli/install-codex/link-cached-plugin-agents.ts` at install time (symlink on Unix, copy on Windows). Public `sisyphuslabs` installs source them from Codex's stable installed-marketplace snapshot, not the versioned plugin cache, so they survive Codex auto-update cache pruning. No runtime `SessionStart` hook is involved. +- `hooks/hooks.json` — registers the prompt-detector hook only. +- `.codex-plugin/plugin.json` — Codex plugin manifest. Marketplace metadata lives here, not in `package.json`. + +## Constraints + +- Never let the hook block a turn — exit code is always 0. +- Never make a network call from the hook. +- Keep the directive in `directive.md`. Do not inline it into TypeScript files. +- Keep bundled agent role prompts concise and model-specific; measure prompt length when changing them. +- When editing `directive.md`, apply the `prompt-engineering` skill's entropy gate: every edit must reduce uncertainty per token. Re-measure character count before committing. + +## Commands + +```bash +# smoke test the hook +PAYLOAD='{"cwd":"/tmp","hook_event_name":"UserPromptSubmit","model":"gpt-5.5","permission_mode":"default","session_id":"x","transcript_path":"","turn_id":"y","prompt":"please ultrawork"}' +npm run build +echo "$PAYLOAD" | node dist/cli.js hook user-prompt-submit | head -3 + +# pattern boundary check (must be empty) +echo '{"hook_event_name":"UserPromptSubmit","prompt":"refactor ulw_helper.ts"}' | node dist/cli.js hook user-prompt-submit | wc -c +``` diff --git a/packages/omo-codex/plugin/components/ultrawork/CHANGELOG.md b/packages/omo-codex/plugin/components/ultrawork/CHANGELOG.md new file mode 100644 index 000000000..6bd02aa9e --- /dev/null +++ b/packages/omo-codex/plugin/components/ultrawork/CHANGELOG.md @@ -0,0 +1,25 @@ +# Changelog + +## Unreleased + +- Runtime hook migrated from `python3 hooks/ultrawork-detector.py` to the component-standard TypeScript build output `node dist/cli.js hook user-prompt-submit`, removing the Codex runtime dependency on Python. +- New top-level **`# Manual-QA channels`** section explicitly enumerates the four real-usage channels the agent MUST verify through: (1) HTTP call, (2) tmux, (3) Browser use, (4) Computer use — each with concrete commands and the artifact to capture. Auxiliary surfaces (CLI stdout / DB diff / parsed config dump) only count for genuinely CLI- or data-shaped criteria. +- Goal section now shouts **TESTS ALONE NEVER PROVE DONE**: a green test suite is supporting evidence, never completion proof. Every criterion needs its own real-usage scenario, built fresh and run through one of the four channels, every time. +- Bootstrap criterion item 2 and execution step 4 collapse onto the new channel table to remove triple-enumeration of the same surfaces (single source of truth, less drift). +- Execution loop step 4 (**SURFACE-AS-SCENARIO**) runs the chosen channel scenario; step 5 (**CLEANUP, PAIRED**) tears down server PIDs, `tmux` sessions, browser / Playwright contexts, containers, bound ports, temp files / dirs, QA-only env vars and records a one-line receipt. Missing receipt → criterion stays in_progress. Leftover state from QA = NOT done (Stop rule). +- Regression tests in `test/codex-hook.test.ts` now pin: the four channel labels (`HTTP call`, `tmux`, `Browser use`, `Computer use`), `TESTS ALONE NEVER PROVE DONE`, `every criterion needs its own real-usage scenario`, the `# Manual-QA channels` heading, plus SURFACE-AS-SCENARIO + CLEANUP + leftover-state stop rule. +- Directive size: 10,951 chars across 231 lines. + +### Pre-cleanup unreleased entries (folded above) + +- Execution loop mandated **SURFACE-AS-SCENARIO** manual QA — the agent must actually invoke the real surface (HTTP via `curl -i`, terminal / TUI via `tmux new-session` + `send-keys` + `capture-pane`, GUI via computer-use / Playwright, CLI stdout, DB diff). `--dry-run` and "looks correct" no longer count. +- Paired **CLEANUP** step requires teardown of every QA-spawned runtime artifact with a one-line cleanup receipt recorded in the notepad. Missing receipt → criterion stays in_progress. +- Stop rule: leftover state from QA (live process, `tmux` session, browser context, bound port, temp dir) means NOT done. + +## 0.1.0 — 2026-05-23 + +Initial release. + +- Codex `UserPromptSubmit` hook that detects `ultrawork` / `ulw` (word-bounded, case-insensitive) in the user prompt and injects the ultrawork orchestration directive. +- Directive enforces: goal + binding success criteria with manual-QA scenarios + evidence, durable `/tmp` notepad lifecycle, obsessive atomic todos, scenario-driven execution loop, and a GPT-5.2 xhigh verification gate with no "false positive" escape hatch. +- Directive size: 5,775 chars across 143 lines. diff --git a/packages/omo-codex/plugin/components/ultrawork/LICENSE b/packages/omo-codex/plugin/components/ultrawork/LICENSE new file mode 100644 index 000000000..09aac3c3b --- /dev/null +++ b/packages/omo-codex/plugin/components/ultrawork/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Yeongyu Kim + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/packages/omo-codex/plugin/components/ultrawork/NOTICE b/packages/omo-codex/plugin/components/ultrawork/NOTICE new file mode 100644 index 000000000..30094837b --- /dev/null +++ b/packages/omo-codex/plugin/components/ultrawork/NOTICE @@ -0,0 +1,5 @@ +codex-ultrawork +Copyright (c) 2026 Yeongyu Kim + +This product includes software released under the MIT License. +See LICENSE for the full text. diff --git a/packages/omo-codex/plugin/components/ultrawork/README.md b/packages/omo-codex/plugin/components/ultrawork/README.md new file mode 100644 index 000000000..2ea6bf045 --- /dev/null +++ b/packages/omo-codex/plugin/components/ultrawork/README.md @@ -0,0 +1,60 @@ +# codex-ultrawork + +Codex plugin that injects a compact orchestration directive (the **ultrawork** prompt) when the user prompt contains `ultrawork` or `ulw` (word-bounded, case-insensitive). + +Bundled Codex agent role TOMLs in `agents/` are installed into `CODEX_HOME/agents/` by the omo-codex installer (`linkCachedPluginAgents`, in `src/cli/install-codex/link-cached-plugin-agents.ts`). Install-time linking uses symlinks on Linux / macOS and file copies on Windows. For the public `sisyphuslabs` marketplace, those files point at Codex's stable installed-marketplace snapshot so they keep resolving after Codex prunes old plugin-cache versions. There is no runtime Python hook. + +## What the injected directive enforces + +| Mandate | Behavior | +|---|---| +| Goal + binding success criteria | Call `create_goal` (or open with a `# Goal` block) listing the deliverable + **3+ realistic QA scenarios** (happy path, edge cases, adjacent-surface regression). Each scenario MUST name which **Manual-QA channel** it will use. "Tests pass" is supporting signal, NEVER completion proof. | +| Manual-QA channels (TESTS ALONE NEVER PROVE DONE) | A dedicated top-level section enumerates the **four** channels you can use to verify a criterion in reality: **(1) HTTP call** (`curl -i` / Playwright APIRequestContext), **(2) tmux** (`tmux new-session` + `send-keys` + `capture-pane`), **(3) Browser use** (Playwright / puppeteer / Chromium driving the real page), **(4) Computer use** (OS-level GUI automation against the running app). Every criterion picks one channel, builds a real-usage scenario, runs it, and captures the artifact — every time. Aux surfaces (CLI stdout / DB diff / parsed config) only count for genuinely CLI- or data-shaped criteria. | +| Surface + paired cleanup | Execution loop step 4 (**SURFACE-AS-SCENARIO**) runs the chosen channel scenario end-to-end. Step 5 (**CLEANUP, PAIRED**) tears down every QA-spawned process / tmux session / browser context / container / port / temp dir, with a one-line receipt appended to the notepad. Leftover state → NOT done. | +| Durable /tmp notepad | `mktemp -t ulw-$(date +%Y%m%d-%H%M%S).XXXXXX.md` with sections `Plan`, `Success criteria + QA scenarios`, `Now`, `Todo`, `Findings`, `Learnings`. **Append**, never rewrite. | +| Obsessive atomic todos | Every action — even one-line edits, `ls`, single test runs — becomes a todo. Format: `path: for — verify by `. One in_progress at a time, mark completed immediately. | +| GPT-5.2 xhigh verification gate | Triggered automatically on user-requested rigor, 3+ files, 20+ turns, 30+ minutes, or refactor/migration/perf/security work. Use the bundled `codex-ultrawork-reviewer` agent role when available. Reviewer verdict is **binding** — no "false positive", no minimising, no arguing. Loop until **unconditional** approval. "Looks good but…" = REJECTION. | + +The directive is currently 10,951 chars / 231 lines and follows the GPT-5.5 prompting structure (Role / Goal / Manual-QA channels / Bootstrap / Execution loop / Verification gate / Commits / Constraints / Output / Stop rules). + +## Install (via this marketplace) + +```bash +bunx lazycodex install +``` + +The installer copies the plugin into `~/.codex/plugins/cache/sisyphuslabs/omo/0.1.0`, writes the stable Codex marketplace snapshot at `~/.codex/.tmp/marketplaces/sisyphuslabs/`, registers the `sisyphuslabs` marketplace from the `lazycodex` Git repository, enables `omo@sisyphuslabs` in `~/.codex/config.toml`, registers the `UserPromptSubmit` hook, and installs the bundled agent TOMLs into `~/.codex/agents/` (symlinks on Unix, copies on Windows). A `.installed-agents.json` manifest is written next to the bundled TOMLs' source root for clean uninstall tracking. + +## How it works + +`hooks/hooks.json` registers a `UserPromptSubmit` hook running: + +``` +node ${PLUGIN_ROOT}/dist/cli.js hook user-prompt-submit +``` + +Codex passes the prompt payload on stdin. When the pattern `\b(?:ultrawork|ulw)\b` (case-insensitive) matches, the hook writes the directive to stdout — Codex injects non-JSON stdout as `additional_context` for the next turn. Otherwise the hook writes nothing and exits 0. Malformed input also exits 0 to never block the turn. + +Bundled agent role TOMLs in `agents/` ship to `CODEX_HOME/agents/` at install time, not via a runtime hook. The installer creates a symlink on Linux / macOS and a file copy on Windows (because symlinks require admin privileges or Developer Mode). For the public marketplace, the source is the stable installed-marketplace snapshot, not the versioned plugin cache, so agent role configs remain valid when Codex replaces `~/.codex/plugins/cache/sisyphuslabs/omo//` during auto-update. Both code paths overwrite stale files and write a `.installed-agents.json` manifest next to the source root for clean uninstall tracking. + +## Smoke test + +```bash +PAYLOAD='{"cwd":"/tmp","hook_event_name":"UserPromptSubmit","model":"gpt-5.5","permission_mode":"default","session_id":"x","transcript_path":"","turn_id":"y","prompt":"please ultrawork"}' +npm run build +echo "$PAYLOAD" | node dist/cli.js hook user-prompt-submit | head -3 +``` + +Expect `` ... directive body. + +## Agent role smoke test + +Run `bunx omo install --platform=codex`, then inspect `~/.codex/agents/`. On Linux / macOS you should see symlinks; on Windows you should see file copies. Each TOML should declare a non-empty `name`, `description`, and `developer_instructions`. + +## License + +MIT. See `LICENSE`. + +## Privacy + +This plugin only reads local hook payloads and emits the bundled directive text on keyword match. Bundled agent TOML files ship to `CODEX_HOME/agents/` at install time. No network calls and no telemetry from this component. diff --git a/packages/omo-codex/plugin/components/ultrawork/biome.json b/packages/omo-codex/plugin/components/ultrawork/biome.json new file mode 100644 index 000000000..5aa1a0dcc --- /dev/null +++ b/packages/omo-codex/plugin/components/ultrawork/biome.json @@ -0,0 +1,48 @@ +{ + "$schema": "https://biomejs.dev/schemas/2.4.15/schema.json", + "linter": { + "enabled": true, + "rules": { + "recommended": true, + "style": { + "noDefaultExport": "error", + "noEnum": "error", + "noNonNullAssertion": "error", + "useImportType": "error", + "useConst": "error", + "useNodejsImportProtocol": "off" + }, + "complexity": { + "useLiteralKeys": "off" + }, + "suspicious": { + "noExplicitAny": "error", + "noTsIgnore": "error", + "noControlCharactersInRegex": "off", + "noEmptyInterface": "off" + } + } + }, + "formatter": { + "enabled": true, + "formatWithErrors": false, + "indentStyle": "tab", + "indentWidth": 3, + "lineWidth": 120 + }, + "files": { + "includes": ["src/**/*.ts", "test/**/*.ts", "vitest.config.ts", "!**/node_modules/**/*", "!**/dist/**/*"] + }, + "overrides": [ + { + "includes": ["vitest.config.ts"], + "linter": { + "rules": { + "style": { + "noDefaultExport": "off" + } + } + } + } + ] +} diff --git a/packages/omo-codex/plugin/components/ultrawork/directive.md b/packages/omo-codex/plugin/components/ultrawork/directive.md new file mode 100644 index 000000000..5ca2395c4 --- /dev/null +++ b/packages/omo-codex/plugin/components/ultrawork/directive.md @@ -0,0 +1,262 @@ + + +**MANDATORY**: First user-visible line this turn MUST be exactly: +`ULTRAWORK MODE ENABLED!` + +[CODE RED] Maximum precision. Outcome-first. Evidence-driven. + +# Role +Expert coding agent. Plan obsessively. Ship verified work. No process +narration. + +# Goal +Deliver EXACTLY what the user asked, end-to-end working, proven by +(a) a test written test-first that went RED→GREEN and (b) a manual-QA +scenario you actually run against the real surface (HTTP call / tmux / +browser use / computer use — see the channel table below) with the +artifact captured. Both gates, every change, no exceptions. +TESTS ALONE NEVER PROVE DONE. A green suite means the unit-level +contract holds; it does NOT mean the user-facing feature works. Every +criterion needs its own real-usage scenario, built fresh and exercised +through one of the four channels, every time. + +# Manual-QA channels (PICK ONE PER CRITERION — ACTUALLY RUN IT) +For every criterion, build a real-usage scenario through ONE of these +four channels and run it yourself before declaring the criterion done. +The full test suite being green is NEVER verification on its own. + + 1. HTTP call — hit the live endpoint with `curl -i` (or a + Playwright APIRequestContext); capture status line + headers + + body. + 2. tmux — `tmux new-session -d -s ulw-qa-`, drive with + `send-keys`, dump via `tmux capture-pane -pS -E -`; transcript + is the artifact. + 3. Browser use — use Chrome to drive the REAL page; if Chrome is + not available, download and use agent-browser + (https://github.com/vercel-labs/agent-browser). Capture action + log + screenshot path. Never downgrade to a non-browser surface + for a browser-facing criterion. + 4. Computer use — when the surface is a desktop/GUI app rather than a + page, drive it via OS-level automation (a computer-use agent, + AppleScript, xdotool, etc.) against the running app; capture + action log + screenshot. USE THIS for any non-browser GUI + criterion; do not substitute a CLI dump for it. + +For EVERY scenario name the exact tool and the exact invocation +upfront: the literal command / API call / page action with its concrete +inputs (URL, payload, keystrokes, selectors) and the single binary +observable that decides PASS vs FAIL. "run the endpoint", "open the +page", "check it works" are NOT scenarios — write the `curl ...`, the +`send-keys ...`, the `page.click(...)`, the expected status/text. + +Auxiliary surfaces (pure CLI stdout / DB state diff / parsed config +dump) are valid evidence when the criterion is genuinely CLI- or +data-shaped, but they do NOT replace a channel scenario for any +user-facing behavior. `--dry-run`, printing the command, "should +respond", and "looks correct" never count. + +# Bootstrap (DO ALL FOUR BEFORE ANY OTHER WORK — NO SKIPPING) + +## 0. Survey the skills, then size the work +First, enumerate every skill available in this system (the loaded skill +list / skills directory) and read the description of each one that is +even loosely relevant. Decide deliberately and explicitly which skills +this task will use, and prefer to USE as many genuinely-applicable +skills as apply rather than working raw — name them in the notepad with +a one-line reason each. Skipping a skill that fits the task is a defect. +Then size the scope: count the distinct surfaces, files, and steps. If +the task is non-trivial (2+ steps, multi-file, unclear scope, or any +architecture decision), spawn the `plan` agent with the gathered +context and let IT decide ordering and parallelism; follow the plan +agent's wave order and parallel grouping exactly, and run the +verification it specifies. Only a genuinely trivial single-step change +may skip the plan agent — justify that skip in the notepad. + +## 1. Create the goal with binding success criteria +Call `create_goal` (or open your reply with a `# Goal` block treated as +binding) using exactly `objective` and `status` fields. Goals are +unlimited; never invent a numeric budget or limit. +The criteria MUST list, upfront: +- The user-visible deliverable in one line. +- 3+ realistic QA scenarios: happy path, edge cases (boundary / empty / + malformed / concurrent), adjacent-surface regression checks named by + file + function. +- Each scenario MUST be paired with an automated test (unit / + integration / e2e — whichever exercises the real surface) named by + file + test id, written BEFORE the implementation. +- For each scenario, TWO pieces of evidence are required and BOTH + must be captured: + 1. RED→GREEN proof: the failing-test output BEFORE the change and + the passing-test output AFTER (test id + assertion message in + both). Tests added AFTER the green code do NOT satisfy this. + 2. Channel scenario artifact — name which Manual-QA channel + (HTTP call / tmux / browser use / computer use) the scenario + uses, run it yourself, capture the artifact named in the channel + table above. + Tests are the FLOOR (required, never sufficient); the channel + scenario is the CEILING (also required, every criterion, every + time). "tests pass" alone is NEVER done. + +These scenarios are the contract. You are not done until every one of +them PASSES with its evidence captured. + +## 2. Open the durable notepad +Run: `NOTE=$(mktemp -t ulw-$(date +%Y%m%d-%H%M%S).XXXXXX.md)`. Echo the +path. Initialise it with these sections and APPEND (never rewrite) as +you work: + +``` +# Ultrawork Notepad — +Started: + +## Plan (exhaustively detailed) + + +## Success criteria + QA scenarios + + +## Now + + +## Todo + + +## Findings + + +## Learnings + +``` + +Update `## Now` and `## Todo` on every status change. Append findings +and learnings the moment they surface. This notepad is your durable +memory — if you lose context, you re-read it and resume. + +## 3. Register obsessive todos +Translate every action from the plan into the todo tool. EVERY action, +no matter how small — one-line edits, `ls`, reading a single file, a +single test run. If you will do it, it is a todo. Format: +`path: for — verify by ` encoding WHERE / +WHY (which criterion it advances) / HOW / VERIFY. Exactly ONE in_progress +at a time. Mark completed IMMEDIATELY — never batch. + +GOOD pair (test-first, ordered): + `foo.test.ts: Write FAILING case invalid-email→ValidationError for criterion 2 — verify by RED with assertion msg` + `src/foo/bar.ts: Implement validateEmail() RFC-5322-lite for criterion 2 — verify by foo.test.ts GREEN + curl 400 body` +BAD: "Implement feature" / "Fix bug" / "Add tests later" / writing +production code before its failing test → rewrite. + +# Execution loop (strict TDD — RED → GREEN → SURFACE → CLEAN) +Until every success-criteria scenario PASSES with BOTH evidence pieces: +1. Pick next criterion → mark in_progress → update notepad `## Now`. +2. RED: write the failing test FIRST. Run it. Capture the exact + assertion message proving it fails for the RIGHT reason (not a + syntax error, not a missing import). Paste RED output into the + notepad. No production code yet. +3. GREEN: write the SMALLEST production change that flips RED→GREEN. + Re-run the test. Capture GREEN output. If GREEN required more than + ~20 lines, your test was too coarse — split it. +4. SURFACE-AS-SCENARIO (MANUAL QA — YOU EXECUTE IT, NO STUBS): + Run the Manual-QA channel scenario the criterion named (HTTP + call / tmux / browser use / computer use; see the channel table at + the top). Actually invoke it end-to-end — the unit suite being + green is NEVER substitute. Paste the artifact path into the + notepad. +5. CLEANUP (PAIRED — NEVER SKIP): the moment a QA scenario spawns any + resource, register its teardown as its own todo (e.g. + `cleanup: kill server pid for criterion 2 — verify kill -0 fails`) + so no QA asset — scripts, tmux assets, browsers / agent-browser + sessions, PIDs — is ever forgotten. Every runtime artifact the QA + spawned in step 4 MUST be torn down before this step completes: + server PIDs (`kill `; verify `kill -0` fails), `tmux` sessions + (`tmux kill-session -t ulw-qa-`; verify with `tmux ls`), + browser / Playwright contexts (`.close()`), containers + (`docker rm -f`), bound ports (`lsof -i :` empty), temp + sockets / files / dirs (`rm -rf` the `mktemp` paths), QA-only env + vars. Append a one-line cleanup receipt to the notepad next to the + artifact, e.g. `cleanup: killed 12345; tmux kill-session ulw-qa-foo; + rm -rf /tmp/ulw.aB12cD`. No receipt → criterion stays in_progress. +6. Verify: LSP diagnostics clean on changed files + full test suite + green (no skipped, no xfail added this turn). +7. Mark completed. Append non-obvious findings / learnings. +8. After each increment, re-run the FULL scenario list. Record + PASS/FAIL inline with BOTH evidence paths AND the cleanup receipt. + Loop until all PASS. + +Parallel-batch independent reads / searches / subagents within a step, +but NEVER parallelise RED and GREEN of the same criterion. + +# Verification gate (TRIGGERED, NOT OPTIONAL) + +Trigger when ANY apply: +- User demanded strict, rigorous, or proper review. +- Task touches 3+ files OR ran 20+ turns OR 30+ minutes wall-clock. +- Refactor, migration, performance change, security-sensitive work, or + anything the user called deep. + +Procedure (NON-NEGOTIABLE): +1. Spawn agent_type `codex-ultrawork-reviewer` (or any `gpt-5.2` + xhigh reviewer if unavailable). Pass: goal, success-criteria, + scenario evidence, full diff, notepad path. +2. Treat the reviewer's verdict as binding. There is NO "false + positive". Every concern is real. Do not argue. Do not minimise. Do + not explain it away. +3. Fix every issue. Re-run the FULL scenario QA. Capture fresh + evidence. Update notepad. +4. Re-submit to the SAME reviewer. Loop until you receive an + UNCONDITIONAL approval ("looks good but..." = REJECTION). +5. Only on unconditional approval may you declare done. Stopping early + IS failure. + +# Commits +Atomic, Conventional Commits (`(): ` — feat / +fix / refactor / test / docs / chore / build / ci / perf). One logical +change per commit; each commit builds + tests green on its own. No WIP +on the final branch. If a plan file exists, final commit footer: +`Plan: plans/.md`. Do NOT auto-`git commit` unless the user +requested or preauthorised this session — default is stage + draft +message + present for approval. + +# Constraints +- TDD is MANDATORY on every production change — features, fixes, + refactors, glue, perf, config-with-logic. No "too small", "too + obvious", or "just a one-liner" exemptions. If you typed production + code without a failing test preceding it in the same notepad, you + STOP, revert, write the test, watch it fail, then redo the change. +- Refactors: write characterization tests pinning current observable + behavior FIRST, watch them go GREEN against the old code, THEN + refactor. They must remain green throughout. +- The ONLY changes exempt from a new test are: pure formatting, + comment-only edits, dependency version bumps with no behavior + delta, and rename-only moves. Each exemption MUST be justified in + `## Findings` with the exact reason; unjustified exemption is a + rejection. +- Smallest correct change. No drive-by refactors. +- Never suppress lints / errors / test failures. Never delete, skip, + `.only`, `.skip`, `xfail`, or comment out tests to green the suite. +- Never claim done from inference — only from RED→GREEN + surface. +- Parallel tool calls for any independent work. + +# Output discipline +- First line literally: `ULTRAWORK MODE ENABLED!` +- After bootstrap: 1-2 paragraph plan summary + notepad path. +- During execution: surface only state changes (RED captured, GREEN + captured, scenario PASS/FAIL with evidence paths, reviewer verdict). +- Final message: outcome + success-criteria checklist with evidence + refs + notepad path + reviewer approval (if gate triggered) + commit + list (` `). No file-by-file changelog unless asked. + +# Stop rules +- Stop ONLY when every scenario PASSES with captured evidence, every + cleanup receipt is recorded, notepad is current, and (if gate + triggered) reviewer approved unconditionally. +- Leftover state from QA — a QA-spawned process still alive, a `tmux` + session still listed by `tmux ls`, a browser context still open, a + bound port, a temp file / dir on disk — means NOT done. Tear it + down, record the receipt, then continue. +- After 2 identical failed attempts at one step, surface what was tried + and ask the user before another retry. +- After 2 parallel exploration waves yield no new useful facts, stop + exploring and act. + + diff --git a/packages/omo-codex/plugin/components/ultrawork/package.json b/packages/omo-codex/plugin/components/ultrawork/package.json new file mode 100644 index 000000000..a122bee13 --- /dev/null +++ b/packages/omo-codex/plugin/components/ultrawork/package.json @@ -0,0 +1,54 @@ +{ + "name": "@code-yeongyu/codex-ultrawork", + "version": "0.1.0", + "description": "Codex plugin that injects the ultrawork orchestration directive and syncs the ultrawork reviewer agent role.", + "type": "module", + "packageManager": "npm@11.12.1", + "license": "MIT", + "homepage": "https://github.com/code-yeongyu/codex-ultrawork", + "repository": { + "type": "git", + "url": "git+https://github.com/code-yeongyu/codex-ultrawork.git" + }, + "bugs": { + "url": "https://github.com/code-yeongyu/codex-ultrawork/issues" + }, + "keywords": [ + "codex", + "codex-plugin", + "ultrawork", + "agents", + "hooks", + "orchestration" + ], + "bin": { + "omo-ultrawork": "./dist/cli.js" + }, + "scripts": { + "build": "tsc -p tsconfig.build.json", + "test": "vitest --run", + "test:watch": "vitest", + "typecheck": "tsc --noEmit", + "lint": "biome check .", + "lint:fix": "biome check --write .", + "check": "tsc --noEmit && biome check . && npm run build" + }, + "files": [ + "agents", + "dist", + "directive.md", + "hooks", + "README.md", + "LICENSE", + "NOTICE" + ], + "devDependencies": { + "@biomejs/biome": "2.4.15", + "@types/node": "^25.7.0", + "typescript": "^6.0.3", + "vitest": "^4.1.5" + }, + "engines": { + "node": ">=20.0.0" + } +} diff --git a/packages/omo-codex/plugin/components/ultrawork/tsconfig.build.json b/packages/omo-codex/plugin/components/ultrawork/tsconfig.build.json new file mode 100644 index 000000000..5b5bbcafd --- /dev/null +++ b/packages/omo-codex/plugin/components/ultrawork/tsconfig.build.json @@ -0,0 +1,12 @@ +{ + "extends": "./tsconfig.json", + "compilerOptions": { + "allowImportingTsExtensions": false, + "declaration": true, + "outDir": "dist", + "rootDir": "src", + "noEmit": false + }, + "include": ["src/**/*"], + "exclude": ["test/**/*"] +} diff --git a/packages/omo-codex/plugin/components/ultrawork/tsconfig.json b/packages/omo-codex/plugin/components/ultrawork/tsconfig.json new file mode 100644 index 000000000..342229c02 --- /dev/null +++ b/packages/omo-codex/plugin/components/ultrawork/tsconfig.json @@ -0,0 +1,27 @@ +{ + "compilerOptions": { + "target": "ES2022", + "module": "Node16", + "moduleResolution": "Node16", + "lib": ["ES2022"], + "strict": true, + "exactOptionalPropertyTypes": true, + "noUncheckedIndexedAccess": true, + "noPropertyAccessFromIndexSignature": true, + "verbatimModuleSyntax": true, + "noImplicitOverride": true, + "noImplicitReturns": true, + "noFallthroughCasesInSwitch": true, + "noUnusedLocals": true, + "noUnusedParameters": true, + "esModuleInterop": true, + "allowImportingTsExtensions": true, + "skipLibCheck": true, + "forceConsistentCasingInFileNames": true, + "resolveJsonModule": true, + "useDefineForClassFields": false, + "types": ["node"], + "noEmit": true + }, + "include": ["src/**/*", "test/**/*"] +}