docs(omo-codex): batch 87 (11 files)
This commit is contained in:
YeonGyu-Kim
@@ -0,0 +1,5 @@
|
||||
__pycache__/
|
||||
*.pyc
|
||||
.DS_Store
|
||||
.env
|
||||
.env.*
|
||||
@@ -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
|
||||
```
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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: <action> for <criterion> — verify by <check>`. 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/<version>/` 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 `<ultrawork-mode>` ... 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.
|
||||
@@ -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"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,262 @@
|
||||
<ultrawork-mode>
|
||||
|
||||
**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-<criterion>`, 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 — <one-line goal>
|
||||
Started: <ISO timestamp>
|
||||
|
||||
## Plan (exhaustively detailed)
|
||||
<every step you will take, in order, broken to atomic actions>
|
||||
|
||||
## Success criteria + QA scenarios
|
||||
<copied from the goal>
|
||||
|
||||
## Now
|
||||
<the single step in progress>
|
||||
|
||||
## Todo
|
||||
<every remaining step, ordered>
|
||||
|
||||
## Findings
|
||||
<every non-obvious fact discovered, with file:line refs>
|
||||
|
||||
## Learnings
|
||||
<patterns / pitfalls / principles to remember next turn>
|
||||
```
|
||||
|
||||
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: <action> for <criterion> — verify by <check>` 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 <pid>`; verify `kill -0` fails), `tmux` sessions
|
||||
(`tmux kill-session -t ulw-qa-<criterion>`; verify with `tmux ls`),
|
||||
browser / Playwright contexts (`.close()`), containers
|
||||
(`docker rm -f`), bound ports (`lsof -i :<port>` 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 (`<type>(<scope>): <imperative>` — 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/<slug>.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 (`<sha> <subject>`). 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.
|
||||
|
||||
</ultrawork-mode>
|
||||
@@ -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"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,12 @@
|
||||
{
|
||||
"extends": "./tsconfig.json",
|
||||
"compilerOptions": {
|
||||
"allowImportingTsExtensions": false,
|
||||
"declaration": true,
|
||||
"outDir": "dist",
|
||||
"rootDir": "src",
|
||||
"noEmit": false
|
||||
},
|
||||
"include": ["src/**/*"],
|
||||
"exclude": ["test/**/*"]
|
||||
}
|
||||
@@ -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/**/*"]
|
||||
}
|
||||
Reference in New Issue
Block a user