Skip to content

The one and only agent harness for complex codebases. Project memory, planning, execution, and verified completion inside Codex.

docs(web): per-skill sections, ulw-research rename, Windows first-party, auto-activation tone

YeonGyu-Kim4a15494c5bff
diff --git a/packages/web/content/docs/faq.md b/packages/web/content/docs/faq.md
index e255f0e7..3f6ca844 100644
--- a/packages/web/content/docs/faq.md
+++ b/packages/web/content/docs/faq.md
@@ -18,10 +18,7 @@ They follow the same flow. LazyCodex installs into the Codex environment. Use wh
No. Unless you are building LazyCodex from source, Bun is not required. Install and usage go through `npx` with plain Node.js/npm.
**Does it work on Windows?**
-It can, but native Windows is not recommended. If you must use Windows, run everything inside WSL2 Ubuntu. If the install or run misbehaves, switch to WSL2 or Git Bash before debugging further.
-
-**What version does the docs site show?**
-The plugin version — currently `4.12.1`. This is the OmO plugin package version that LazyCodex installs.
+Yes. Both the npx installer and the Codex marketplace path support Windows natively. The installer provisions Node.js and Git Bash automatically when they are missing, and shell hooks run through Git Bash. If you already have Node.js and Git for Windows installed, everything works out of the box. See the [Windows section in Installation](./installation.md) for environment variable overrides and bootstrap logs.
### First use
diff --git a/packages/web/content/docs/skills.md b/packages/web/content/docs/skills.md
index 68c736c8..dfe7d494 100644
--- a/packages/web/content/docs/skills.md
+++ b/packages/web/content/docs/skills.md
@@ -1,74 +1,185 @@
-LazyCodex is most useful as a harness for complex codebases: project memory, planning, execution, verified completion, skills, hooks, model routing, and diagnostics.
+Skills are specialist playbooks that LazyCodex loads on top of the command pillars. They auto-activate when a task matches their domain — you do not need to study or memorize them. Include `ultrawork` (or the short alias `ulw`) in your prompt and the harness picks the right skills internally.
-### Built-in workflows
+When you want to call a skill explicitly, put its name in the prompt: `$review-work`, `$remove-ai-slops`, `$ulw-research`, and so on.
-Start with `$init-deep` when the repository is too large or too old to explain from memory. It generates hierarchical `AGENTS.md` context so agents can find the right files before they change code.
+### Commands
-Use `$ulw-plan` when the work needs decisions before implementation, `$start-work` when a plan should be executed, and `$ulw-loop` when you want the agent to keep going until the result is verified.
+The command pillars stay simple:
-### Feature coverage
+- `$init-deep` — project memory
+- `$ulw-plan` — decision-complete planning before coding
+- `$start-work` — execute a plan with durable Boulder progress
+- `$ulw-loop` — evidence-bound loop until verified completion
-The three command pillars stay simple:
+Skills add specialist judgment around those pillars. The sections below describe each skill and how it is typically used.
-- `$ulw-loop` keeps moving until verified completion
-- `$ulw-plan` turns fuzzy work into a decision-complete plan
-- `$start-work` executes a plan with durable Boulder progress
+---
-Skills add specialist judgment around those pillars.
+### review-work
-Most skills auto-activate when a request matches their domain, so you do not need to study or manually select every skill before using LazyCodex. When you want to be explicit, put the skill name in the prompt — for example `$visual-qa`, `$git-master`, or `$ultraresearch`.
+Five-lane parallel post-implementation review.
-| Skill | Use it for |
-| --- | --- |
-| `init-deep` | Hierarchical `AGENTS.md` context for large or old repos |
-| `ulw-plan` | Explore-first planning before coding |
-| `ulw-loop` | Evidence-bound loop until verified completion |
-| `start-work` | Execute a plan with durable Boulder progress |
-| `review-work` | Five-lane parallel post-implementation review |
-| `remove-ai-slops` | Behavior-preserving cleanup of AI-looking code |
-| `frontend` | Designed UI work instead of generic layout filling |
-| `programming` | Strict TypeScript, Rust, Python, or Go discipline, TDD-first |
-| `git-master` | Atomic commits, rebase/squash, push safety, history investigation |
-| `visual-qa` | Screenshot/TUI diff plus dual-oracle visual QA |
-| `debugging` | Evidence-led root-cause investigation |
-| `refactor` | Behavior-preserving restructure of existing code |
-| `ultraresearch` | Maximum-saturation research: parallel codebase, web, official-docs, and OSS-repo swarms, recursive lead expansion, empirical verification, and cited synthesis |
-| `LSP` | Diagnostics, definitions, references, symbols, and renames |
-| `lsp-setup` | Configure language servers for a project |
-| `AST-grep` | Structural search and rewrite across code |
-| `rules` | Project instructions from AGENTS, rules, and instruction files |
-| `comment-checker` | Feedback after edit-like operations |
+After significant work, `review-work` launches five sub-agents in parallel — each covering a different angle: goal/constraint verification, hands-on QA execution, code quality, security, and context mining from git history and issues. All five must pass for the review to pass. One failure means the review fails.
-### Skill highlights
+**When it activates:** After completing any meaningful implementation — especially when the change touches 3+ files or runs for 20+ minutes.
-**review-work** — A post-implementation review orchestrator. After significant work, it launches five parallel sub-agents covering goal/constraint verification, hands-on QA execution, code quality, security, and context mining from git history and issues. All five must pass for the review to pass. One failure means the review fails.
+**Example:** After finishing a PR, the user says:
-**remove-ai-slops** — Removes AI-generated code smells while strictly preserving behavior. The safety invariant: regression tests lock behavior *before* a single line is deleted. Covers obvious comments, excessive defensive code, unnecessary abstractions, dead code, duplicates, and oversized modules (250+ pure LOC triggers a full modular refactoring).
+```text
+review my work
+```
-**frontend** — Not a single rule file but a router. It reads design, perfection, and ui-ux-db references based on the task, then builds and verifies against the actual browser. Covers UI implementation, styling, layout, animation, Lighthouse 100, Core Web Vitals, accessibility, and React dev tools.
+The harness spawns five parallel reviewers in separate threads, each with a focused lens. The final verdict is PASS only when every lane agrees.
-**programming** — One philosophy across four languages: strict types, modern stacks (Pydantic v2 / serde+thiserror / Zod / gin+sqlc+pgx+slog), parse-don't-validate, exhaustive match, typed errors, no escape hatches, 250 pure LOC ceiling, TDD. The skill gates on language and loads the matching reference set before writing a single line.
+---
-**debugging** — Hypothesis-driven runtime debugging. Every claim about why a bug happens must come from observed state, not code reading. Covers crashes, silent failures, wrong responses, stuck processes, memory leaks, async misbehavior, and reverse engineering. Leaves no debug artifacts behind.
+### remove-ai-slops
-**refactor** — Maps the codebase before touching anything, evaluates test coverage to set the verification strategy, plans atomic steps with rollback points, then executes with LSP and AST-grep. Any test failure during execution triggers an immediate stop and revert.
+Behavior-preserving cleanup of AI-generated code smells.
-**LSP** — Gives the agent language-server precision: diagnostics, go-to-definition, find-references, document symbols, and safe workspace-wide renames. Runs as MCP tool calls, not shell commands.
+The safety invariant: regression tests lock behavior *before* a single line is deleted. Covers obvious comments, excessive defensive code, unnecessary abstractions, dead code, duplicates, and oversized modules (250+ pure LOC triggers a full modular refactoring). Workers run in parallel batches of five, and any test failure triggers an immediate revert.
-**rules** — Automatically injects project instructions from `CONTEXT.md`, `.omo/rules/`, `.claude/rules/`, `.github/instructions/`, and `.github/copilot-instructions.md` at session start and on every prompt submit. No command to run — just works when the plugin is active.
+**When it activates:** When asked to clean, deslop, or remove AI-generated patterns.
-**comment-checker** — Fires after every edit-like tool call. If it flags a comment, Codex receives blocking feedback and must fix or justify the comment before proceeding. Catches comment drift (comments that no longer match the code below them) at the moment of introduction rather than in a later review.
+**Example:** Combining with `refactor` and `programming` for a full cleanup pass:
-### Where skills live
+```text
+ulw plan and manual qa, no behaviour changes, no regressions
+/refactor /remove-ai-slops through /programming
+```
+
+The harness plans the cleanup first, locks behavior with tests, then dispatches parallel workers by slop category — safe to dangerous order.
+
+---
+
+### frontend
+
+UI, UX, design, performance, accessibility, and visual QA — all in one router.
+
+Not a single rule file but a router. It reads design, perfection, and ui-ux-db references based on the task, then builds and verifies against the actual browser. Covers UI implementation, styling, layout, animation, Lighthouse 100, Core Web Vitals, accessibility, SEO, and React dev tools like `react-scan` and `react-doctor`.
+
+**When it activates:** Any task involving UI, styling, layout, animation, design, or performance auditing.
+
+**Example:**
+
+```text
+redesign the sidebar with better spacing and hit Lighthouse 100
+```
+
+The skill routes to the right design references, builds to match the existing design system, then runs a real Playwright Chromium Lighthouse audit — never the Lighthouse CLI, never by weakening UX.
+
+---
+
+### programming
+
+One philosophy across four languages: strict types, modern stacks, TDD.
+
+Applies to every `.py`, `.pyi`, `.rs`, `.ts`, `.tsx`, `.mts`, `.cts`, `.go` file. The skill gates on language, loads the matching reference set, and enforces: parse-don't-validate at boundaries, exhaustive variant matching, typed errors, no escape hatches (`any`, `unwrap`, `@ts-ignore`), 250 pure LOC ceiling per file, and mandatory TDD (RED → GREEN → REFACTOR).
+
+**When it activates:** Automatically on any code file edit in the supported languages.
+
+**Example:** The skill is always on. When editing TypeScript, it loads the TypeScript reference (Bun + Biome + strict tsconfig), enforces branded types and discriminated unions, and runs the post-write review loop: measure pure LOC, self-review seven questions, refactor if over 250 LOC.
+
+---
+
+### debugging
+
+Hypothesis-driven runtime debugging across any language or binary.
+
+Every claim about why a bug happens must come from observed runtime state, not code reading. The skill runs a phased loop: setup and journal, form 3+ orthogonal hypotheses, investigate in parallel, escalate to independent verifiers after 2 failed rounds, confirm root cause by toggling, lock with a failing test, fix minimally, QA on the real surface, then clean up every debug artifact.
+
+**When it activates:** Crashes, silent failures, wrong responses, stuck processes, memory leaks, async misbehavior, or reverse engineering.
+
+**Example:**
+
+```text
+debug this — the API returns 200 but the body is empty
+```
+
+The skill fires parallel investigation lanes, attaches real debuggers (pdb, node inspect, lldb, dlv), and does not close the bug until the root cause is confirmed by toggling and a failing test goes GREEN.
+
+---
+
+### refactor
+
+Codemap-aware, LSP- and AST-grep-powered restructuring.
+
+Maps the codebase before touching anything, evaluates test coverage to set the verification strategy, plans atomic steps with rollback points, then executes with LSP renames and AST-grep structural rewrites. Any test failure during execution triggers an immediate stop and revert.
+
+**When it activates:** Requests to refactor, restructure, extract, simplify, or modernize code.
-OmO can load skills from project and user locations such as `.opencode/skills`, `~/.config/opencode/skills`, `.claude/skills`, `.agents/skills`, and `~/.agents/skills`.
+**Example:**
-LazyCodex installs the Codex Light setup with:
+```text
+refactor the validation logic into its own module --scope=module
+```
+
+The skill builds a dependency graph of the target, runs characterization tests to pin current behavior, then executes the restructuring step by step — verifying after each step.
+
+---
+
+### visual-qa
+
+Screenshot and TUI diff plus dual-oracle visual QA.
+
+Captures reference and actual evidence — screenshots for web UIs, `tmux capture-pane` for terminal UIs — then runs a bundled pixel-diff or column-width script. Two parallel read-only oracle passes evaluate: one for design-system and functional integrity, one for visual fidelity and CJK text precision. The final verdict is a single good/bad score.
+
+**When it activates:** After building or changing any UI, or when asked to verify visual correctness.
+
+---
+
+### git-master
+
+Atomic commits, rebase/squash, push safety, history investigation.
+
+Handles commit message style detection, semantic grouping, fixup autosquash, blame, bisect, `log -S`, and questions like "who wrote this" or "when was this added."
+
+**When it activates:** Any git operation — committing, rebasing, squashing, history search.
+
+---
+
+### ulw-research
+
+Maximum-saturation research mode (formerly `ultraresearch`).
+
+Orchestrates parallel explore and librarian swarms across the codebase, the web, official documentation, and OSS repositories. Runs a recursive EXPAND loop driven by leads that workers return, verifies findings empirically by running code, and produces cited synthesis with optional reports.
+
+**When it activates:** Only on explicit demand — the word `ulw-research`, the legacy alias `ultraresearch`, or any request for deep research or an ultra-precise investigation.
-```bash
-npx lazycodex-ai install
+**Example:**
+
+```text
+ulw-research the typeclaw architecture — map every module and find the official docs
```
-That installer wires the Codex marketplace plugin as `omo@sisyphuslabs` while keeping the public package alias easy to remember.
+The skill fans out 10+ parallel search lanes across GitHub, official docs, and web sources, recursively expands promising leads, then synthesizes a cited report.
+
+---
+
+### LSP
+
+Language-server diagnostics, definitions, references, symbols, and safe renames.
+
+Gives the agent language-server precision via MCP tool calls. Runs diagnostics after every edit, finds definitions and references across the workspace, and performs safe renames through the language server's own workspace edit — not text find-and-replace.
+
+**When it activates:** Automatically after edit-like tool calls (diagnostics), and on demand for navigation and renames.
+
+---
+
+### AST-grep
+
+Structural search and rewrite across 25 languages.
+
+Finds code by syntactic shape rather than text — every function call matching a pattern, every import shaped like X. Rewrites are deterministic and always previewed with `dryRun=true` before applying. Pairs with the `refactor` skill for safe, large-scale codemods.
+
+**When it activates:** Structural code matching, pattern-based search, or deterministic rewrites (strip `as any`, migrate `require()` to `import`, find empty catch blocks).
+
+---
+
+### Where skills live
+
+LazyCodex installs skills as part of the OmO plugin. OmO can also load skills from project and user locations such as `.codex/skills`, `~/.codex/skills`, `.agents/skills`, and `~/.agents/skills`.
+
+Each skill carries deep internal references — detailed playbooks, language-specific recipes, and per-phase instructions — but none of that is something you need to read. The harness reads it for you when the skill activates.
The command pillars and the disciplines behind them are covered in depth: [ulw-plan](./ulw-plan.md), [ulw-loop](./ulw-loop.md), [start-work](./start-work.md), [TDD](./tdd.md), [manual QA](./manual-qa.md), and [git workflow](./git-workflow.md).
diff --git a/packages/web/content/docs/ultrawork.md b/packages/web/content/docs/ultrawork.md
index f95fb17a..04005672 100644
--- a/packages/web/content/docs/ultrawork.md
+++ b/packages/web/content/docs/ultrawork.md
@@ -1,4 +1,4 @@
-ultrawork is the headline mode. Typing `ultrawork` (or the short alias `ulw`) anywhere in your prompt activates maximum-precision, outcome-first, evidence-driven orchestration.
+ultrawork is the headline mode. Include `ultrawork` (or the short alias `ulw`) anywhere in your prompt — like adding `ultrathink` — and the harness switches to maximum-precision, outcome-first, evidence-driven orchestration. Skills activate internally; you do not need to name them.
> "Plan, execute, verify, and keep the evidence attached."
@@ -6,10 +6,18 @@ The principle is simple. An agent saying it is done does not mean the work is do
### Usage
-```bash
+Just include the word in your prompt. Nothing else to configure.
+
+```text
ulw add authentication
```
+```text
+fix the flaky checkout test ultrawork
+```
+
+The harness reads the task, picks the right skills (programming, debugging, refactor, etc.), and runs the evidence-bound loop automatically. You do not choose skills yourself unless you want to be explicit — for example `$review-work` or `$ulw-research`.
+
### What it enforces
- Strict TDD: RED → GREEN → SURFACE → CLEAN
diff --git a/packages/web/lib/docs-content.generated.ts b/packages/web/lib/docs-content.generated.ts
index 5d8d7b61..92798bc4 100644
--- a/packages/web/lib/docs-content.generated.ts
+++ b/packages/web/lib/docs-content.generated.ts
@@ -4,13 +4,13 @@ export const DOC_SOURCES: Record<string, string> = {
"installation.md": "<p>One command installs the OmO agent harness for Codex without a global package install.</p>\n<h3 id=\"prerequisites\">Prerequisites</h3>\n<ul>\n<li><a href=\"https://nodejs.org\">Node.js</a> — any maintained LTS; <code>npx</code> ships with it. Bun is <strong>not</strong> required: the installer runs on plain Node.</li>\n<li><a href=\"https://github.com/openai/codex\">OpenAI Codex</a>: the <strong>Codex App</strong> (recommended) or the <strong>Codex CLI</strong>.</li>\n</ul>\n<p>LazyCodex runs <em>inside</em> Codex. Codex must be installed and logged in before you start. If you are setting up for the first time, the Codex App is the easier path — you can open a project and run <code>$command</code> directly from the GUI.</p>\n<blockquote>\n<p>Do NOT use <code>npm install -g</code> or <code>bun add -g</code>. Always invoke via <code>npx</code>.</p>\n</blockquote>\n<h3 id=\"install\">Install</h3>\n<p>The command is one line. No global install, no setup files.</p>\n<pre><code class=\"language-bash\">npx lazycodex-ai install\n</code></pre>\n<p>This is exactly equivalent to <code>npx --yes --package oh-my-openagent omo install --platform=codex</code>.</p>\n<p>To skip the TUI and run a fully autonomous, prompt-free setup:</p>\n<pre><code class=\"language-bash\">npx lazycodex-ai install --no-tui --codex-autonomous\n</code></pre>\n<p>The installer connects commands, skills, hooks, model routing, and verification defaults into your Codex configuration. It is strongly recommended to let an LLM agent run the install — the agent handles subscription detection, model selection, and provider auth automatically.</p>\n<p>After install, the next Codex launch asks you to approve the <code>omo</code> hooks in the startup review. Hooks do not run before approval.</p>\n<p>If the install feels like too many steps, you do not have to run the command yourself. Open Codex and give it the <a href=\"https://lazycodex.ai\">lazycodex.ai</a> link, then ask it to install LazyCodex. The agent reads the docs and walks the setup.</p>\n<blockquote>\n<p><strong>Stuck?</strong> Join the <a href=\"https://discord.gg/6ztZB9jvWq\">LazyCodex Discord</a> and ask <strong>Jobdori</strong> for help.</p>\n</blockquote>\n<h3 id=\"install-from-the-codex-marketplace-experimental\">Install from the Codex marketplace (experimental)</h3>\n<p>The npx installer above stays the primary path. As an additive, experimental alternative you can install from inside Codex itself: type <code>/plugins</code>, open the <strong>Add Marketplace</strong> tab (&quot;Add a marketplace from a Git repo or local root.&quot;), and enter <code>https://github.com/code-yeongyu/lazycodex</code>, then install <code>omo</code> from the <code>sisyphuslabs</code> marketplace. Or from the CLI:</p>\n<pre><code class=\"language-bash\">codex plugin marketplace add https://github.com/code-yeongyu/lazycodex\ncodex plugin add omo@sisyphuslabs\n</code></pre>\n<p>On the next launch, approve the omo hooks in Codex&#39;s startup review — hooks never run before approval. The first approved session prints <code>LazyCodex bootstrap running in background — restart the session when it completes</code> while a background worker finishes the setup (config blocks, agent roles, bin links, a pinned <code>sg</code> binary for the <code>ast_grep</code> MCP); restart when it is done. The marketplace path never touches Codex permission settings — autonomous mode remains the explicit <code>npx lazycodex-ai install --no-tui --codex-autonomous</code> choice.</p>\n<p>Upgrade with <code>codex plugin marketplace upgrade sisyphuslabs</code>. The next startup review shows the hooks as <strong>Modified</strong> — expected after every upgrade, because the plugin files changed and the previous trust hashes no longer match — re-approve them and the following session re-runs bootstrap on the new version. If anything looks pending or degraded, <code>npx lazycodex-ai doctor</code> explains what and why.</p>\n<h3 id=\"authentication\">Authentication</h3>\n<p>Auth targets <strong>Codex itself</strong>, not LazyCodex. The Codex CLI logs in during its own setup; the Codex App logs in through the app UI. There is no separate LazyCodex login command.</p>\n<p>Once Codex is logged in, <code>npx lazycodex-ai install</code> handles subscription detection, model selection, and provider routing. If you let an LLM agent run the install, it walks the same process for you.</p>\n<p>To check what is configured:</p>\n<pre><code class=\"language-bash\">npx lazycodex-ai doctor\n</code></pre>\n<p><code>doctor</code> explains what is set up, what is missing, and why it matters. See <a href=\"#configuration\">Configuration</a> for provider and routing details.</p>\n<h3 id=\"windows\">Windows</h3>\n<p>Native Windows works with both install paths.</p>\n<ul>\n<li><strong>Node:</strong> <code>npx lazycodex-ai install</code> needs Node.js on <code>PATH</code> (LTS recommended). On marketplace installs the bootstrap step provisions a pinned Node LTS runtime into <code>%USERPROFILE%\\.codex\\runtime\\node\\</code> automatically when <code>node</code> is missing — installing Node yourself first also works and skips the download.</li>\n<li><strong>Git Bash:</strong> required for shell hooks. The installer and the marketplace bootstrap both try <code>winget install --id Git.Git -e --source winget</code> when Git Bash is missing. If Git lives somewhere custom, set <code>OMO_CODEX_GIT_BASH_PATH</code> to a path like <code>C:\\Program Files\\Git\\bin\\bash.exe</code>.</li>\n<li><strong><code>where bash</code> shows <code>C:\\Windows\\System32\\bash.exe</code>:</strong> that is the WSL launcher, not Git Bash — LazyCodex intentionally ignores <code>System32</code> and <code>WindowsApps</code> <code>bash.exe</code> shims when resolving Git Bash. Install Git for Windows or point <code>OMO_CODEX_GIT_BASH_PATH</code> at a real Git Bash so the resolver finds it.</li>\n<li><strong>Troubleshooting:</strong> the Windows marketplace bootstrap writes a transcript to <code>%USERPROFILE%\\.codex\\plugins\\data\\omo-sisyphuslabs\\bootstrap\\ps-bootstrap.log</code>; degraded lines look like <code>degraded component=node reason=... hint=npx lazycodex-ai doctor</code>. Run <code>npx lazycodex-ai doctor</code> for the full health report.</li>\n</ul>\n<h3 id=\"let-an-agent-do-it\">Let an agent do it</h3>\n<p>It is strongly recommended to let an LLM agent run the install and walk the setup for you. The agent handles subscription detection, model selection, and provider auth automatically.</p>\n",
"recommended-environment.md": "<p>The smoothest environment for LazyCodex is Ubuntu or macOS. The harness leans on shell, Git, Node.js/npm, Codex config files, and hooks — all of which behave predictably on Unix-like systems.</p>\n<h3 id=\"operating-system\">Operating system</h3>\n<table>\n<thead>\n<tr>\n<th>OS</th>\n<th>Recommendation</th>\n<th>Notes</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><strong>Ubuntu</strong></td>\n<td>Most recommended</td>\n<td>Server and dev environments both have predictable paths, shells, and package management.</td>\n</tr>\n<tr>\n<td><strong>macOS</strong></td>\n<td>Recommended</td>\n<td>Good for local development. Homebrew plus Node.js/npm is all you need.</td>\n</tr>\n<tr>\n<td><strong>Windows</strong></td>\n<td>Not recommended</td>\n<td>Native Windows shells and path differences cause unnecessary friction with hooks, CLI, file permissions, and script execution.</td>\n</tr>\n</tbody></table>\n<p>If you must use Windows, run Codex and LazyCodex inside <strong>WSL2 Ubuntu</strong> rather than native Windows. Keep the project on the WSL2 filesystem for the most stable experience.</p>\n<h3 id=\"before-you-install\">Before you install</h3>\n<table>\n<thead>\n<tr>\n<th>Item</th>\n<th>Expected state</th>\n</tr>\n</thead>\n<tbody><tr>\n<td>Codex</td>\n<td>Codex App or Codex CLI installed and logged in.</td>\n</tr>\n<tr>\n<td>Node.js/npm</td>\n<td>A maintained Node.js LTS. <code>npx</code> ships with npm.</td>\n</tr>\n<tr>\n<td>Project</td>\n<td>A repository opened in Codex that you want to work in.</td>\n</tr>\n<tr>\n<td>Git</td>\n<td>A Git repository so changes can be tracked and reverted.</td>\n</tr>\n<tr>\n<td>Secrets</td>\n<td>Provider keys live in the shell or Codex environment — never pasted into project files.</td>\n</tr>\n</tbody></table>\n<p>You do <strong>not</strong> need to install Bun unless you are building LazyCodex from source. Normal install and usage go through the <code>npx</code> path.</p>\n<p>Check your versions first:</p>\n<pre><code class=\"language-bash\">node -v\nnpm -v\nnpx -v\n</code></pre>\n<p>If they are missing, install Node.js:</p>\n<pre><code class=\"language-bash\"># Ubuntu or WSL2 Ubuntu\nsudo apt update\nsudo apt install -y nodejs npm\n\n# macOS\nbrew install node\n</code></pre>\n<h3 id=\"author-recommendations\">Author recommendations</h3>\n<ul>\n<li><strong>Start with the Codex App.</strong> Install, login, session management, and skill invocation are all visible in the GUI, which is less confusing for first-time users.</li>\n<li><strong>Use ChatGPT Pro or above.</strong> The docs assume the Codex usage environment that comes with ChatGPT Pro and above.</li>\n<li><strong>Try bare Codex first.</strong> If you have never used a coding agent before, spend a session with Codex alone before adding LazyCodex on top. Understanding how the base agent responds and edits files makes the harness layer easier to follow.</li>\n<li><strong>Stick to supported models.</strong> Mixing in GLM, Kimi, Mimo, or other non-default model stacks is not recommended. The docs and skill flows are written around Codex and OmO defaults.</li>\n</ul>\n",
"getting-started.md": "<p>LazyCodex is most useful as a harness for complex codebases: project memory, planning, execution, verified completion, skills, hooks, model routing, and diagnostics. This page walks through install verification and the four commands you will reach for most often.</p>\n<h3 id=\"prerequisites\">Prerequisites</h3>\n<ul>\n<li><code>npx</code> available from a Node.js/npm install. Bun is not required.</li>\n<li>Codex App or <a href=\"https://github.com/openai/codex\">OpenAI Codex CLI</a>.</li>\n</ul>\n<p>LazyCodex connects OmO commands, skills, and hooks into Codex configuration. If Codex is working normally, the install flow is the same for App and CLI.</p>\n<h3 id=\"install\">Install</h3>\n<p>The simplest approach: open a new task in Codex, give it the LazyCodex GitHub link, and ask it to install.</p>\n<pre><code class=\"language-text\">https://github.com/code-yeongyu/lazycodex\n\nInstall LazyCodex from this repository.\n</code></pre>\n<p>If you prefer running the command directly:</p>\n<pre><code class=\"language-bash\">npx lazycodex-ai install\n</code></pre>\n<p>After install, reopen Codex and check that OmO commands and skills appear in the <code>$</code> menu. The next launch asks you to approve the <code>omo</code> hooks in the startup review — hooks do not run before approval.</p>\n<p>If the status shows <code>pending</code> or <code>degraded</code>, run the diagnostic first:</p>\n<pre><code class=\"language-bash\">npx lazycodex-ai doctor\n</code></pre>\n<h3 id=\"authentication\">Authentication</h3>\n<p>LazyCodex has no separate login. The installer (or the agent running it) handles subscription detection, model selection, and provider auth. Codex App or Codex CLI must already be logged in, but that is a prerequisite rather than a LazyCodex-specific step.</p>\n<p>See <a href=\"#configuration\">Configuration</a> for provider and routing details.</p>\n<h3 id=\"the-four-commands\">The four commands</h3>\n<table>\n<thead>\n<tr>\n<th>Command</th>\n<th>Use it when</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>$init-deep</code></td>\n<td>The repository is too large or too old to explain from memory.</td>\n</tr>\n<tr>\n<td><code>$ulw-plan</code></td>\n<td>The work needs decisions before any code is written.</td>\n</tr>\n<tr>\n<td><code>$start-work</code></td>\n<td>A plan exists and should be executed to completion.</td>\n</tr>\n<tr>\n<td><code>$ulw-loop</code></td>\n<td>You want the agent to keep going until the result is verified.</td>\n</tr>\n</tbody></table>\n<h3 id=\"your-first-run\">Your first run</h3>\n<p>Start by giving the agent project context with hierarchical <code>AGENTS.md</code> memory:</p>\n<pre><code class=\"language-text\">$init-deep\n</code></pre>\n<p>Then pick the command that matches your task.</p>\n<p><strong>If you need to plan first</strong> — this reads the repository and writes a decision-complete plan without touching product code. Approve the plan before it executes.</p>\n<pre><code class=\"language-text\">$ulw-plan &quot;add a done-toggle helper to the small task app&quot;\n</code></pre>\n<p><strong>If a plan already exists</strong> — execute it. All checkboxes must complete before it stops.</p>\n<pre><code class=\"language-text\">$start-work\n</code></pre>\n<p><strong>If you want end-to-end verified completion</strong> — the loop keeps going until evidence proves the result.</p>\n<pre><code class=\"language-text\">$ulw-loop &quot;fix the payment flow failure and verify end to end&quot;\n</code></pre>\n<h3 id=\"how-to-choose\">How to choose</h3>\n<p>Start with <code>$init-deep</code> once per repository so agents have hierarchical <code>AGENTS.md</code> context to work from.</p>\n<p>For anything ambiguous, run <code>$ulw-plan</code> first. It interviews you, explores the codebase in parallel, and writes a decision-complete plan to <code>plans/&lt;slug&gt;.md</code> without touching product code.</p>\n<p>Hand that plan to <code>$start-work</code> to execute it: durable Boulder state, parallel subagents, strict TDD, and five evidence gates. It prints <code>ORCHESTRATION COMPLETE</code> when every checkbox is done.</p>\n<p><code>$ulw-loop</code> is the tightest loop — use it for a single task that must run until an oracle verifies completion. It does not plan; it executes and verifies.</p>\n<h3 id=\"a-typical-session\">A typical session</h3>\n<pre><code class=\"language-text\">$init-deep\n$ulw-plan &quot;add rate limiting to the api gateway&quot;\n$start-work plans/add-rate-limiting.md\n</code></pre>\n<p>If the job is small and well-understood, skip the plan and loop directly:</p>\n<pre><code class=\"language-text\">ulw fix the flaky checkout test\n</code></pre>\n<p>See <a href=\"#skills\">Feature coverage</a> for the skills that add specialist judgment around these commands.</p>\n",
- "faq.md": "<p>Quick answers to common sticking points. Start with <strong>Install &amp; environment</strong> if you are setting up, <strong>First use</strong> if you are choosing a command, <strong>Execution &amp; verification</strong> if something seems off during a run, and <strong>Conflicts &amp; limits</strong> if you hit a wall.</p>\n<h3 id=\"install-amp-environment\">Install &amp; environment</h3>\n<p><strong>What is LazyCodex?</strong>\nA light port of OmO for Codex. It layers commands, skills, hooks, and model routing onto Codex so the agent plans before it edits, verifies before it claims done, and keeps project context across sessions.</p>\n<p><strong>Is LazyCodex a replacement for OmO?</strong>\nNo. It is a focused subset. The full OmO has deeper orchestration. LazyCodex takes the parts that work well inside Codex and packages them as a repeatable install.</p>\n<p><strong>Can I ask Codex to install it for me?</strong>\nYes. Open Codex and give it the LazyCodex GitHub link or <code>lazycodex.ai</code>, then ask it to install. Or run <code>npx lazycodex-ai install</code> yourself.</p>\n<p><strong>Is there a difference between Codex App and Codex CLI installs?</strong>\nThey follow the same flow. LazyCodex installs into the Codex environment. Use whichever surface you prefer — App or CLI.</p>\n<p><strong>Do I need Bun?</strong>\nNo. Unless you are building LazyCodex from source, Bun is not required. Install and usage go through <code>npx</code> with plain Node.js/npm.</p>\n<p><strong>Does it work on Windows?</strong>\nIt can, but native Windows is not recommended. If you must use Windows, run everything inside WSL2 Ubuntu. If the install or run misbehaves, switch to WSL2 or Git Bash before debugging further.</p>\n<p><strong>What version does the docs site show?</strong>\nThe plugin version — currently <code>4.12.1</code>. This is the OmO plugin package version that LazyCodex installs.</p>\n<h3 id=\"first-use\">First use</h3>\n<p><strong>What kind of tasks is LazyCodex best at?</strong>\nLarge, long-running work where planning and verification matter. Small questions or one-line fixes can go straight to Codex without the harness.</p>\n<p><strong>Do I need to study every skill before using it?</strong>\nNo. Skills auto-activate when a task matches their domain. Learn the four commands first; dig into individual skills when you hit a specific need.</p>\n<p><strong>Which commands should I learn first?</strong>\n<code>$init-deep</code> for project memory, <code>$ulw-plan</code> for planning, <code>$start-work</code> for executing a plan, and <code>$ulw-loop</code> for open-ended tasks that need verified completion.</p>\n<p><strong>How do I know the install worked?</strong>\nOpen Codex and type <code>$</code> in the input — you should see OmO commands and skills listed. On the CLI, typing <code>ulw</code> should activate ultrawork mode. The first real command is usually <code>$init-deep</code>.</p>\n<p><strong>The $ menu does not show any commands after install.</strong>\nOpen a new Codex session to reload the plugin, then check whether the startup review has a pending <code>omo</code> hook approval. If it still does not show, run <code>npx lazycodex-ai doctor</code> to check install and skill loading state.</p>\n<h3 id=\"execution-amp-verification\">Execution &amp; verification</h3>\n<p><strong>Is <code>npx lazycodex-ai doctor</code> a real thing?</strong>\nYes. It runs the OmO doctor flow and reports what is configured, what is missing, and why. Use it whenever something looks off.</p>\n<p><strong>Why does it ask me to approve hooks?</strong>\nCodex reviews hooks at startup. The <code>omo</code> hooks do not run until you approve them. After each upgrade the hooks show as <strong>Modified</strong> because the plugin files changed — re-approve to pick up the new version.</p>\n<p><strong>What should I check after an upgrade?</strong>\nIf hooks show as Modified, re-approve them. If anything looks pending or degraded, run <code>npx lazycodex-ai doctor</code> for the full picture.</p>\n<p><strong><code>$ulw-loop</code> keeps finishing too quickly — what do I do?</strong>\nIteration alone does not fix vague completion criteria. Be specific about what you want collected, what verification must pass, and what the agent should investigate when data is missing. Or run <code>$ulw-plan</code> first to nail down the scope.</p>\n<p><strong>Do I need a bigger token budget?</strong>\nLazyCodex is not a token-saving tool. It pushes good models and enough tokens through planning, execution, and verification. For large tasks, split work into smaller units before a single thread gets too heavy.</p>\n<p><strong>How do I pick a thinking/reasoning level?</strong>\nDo not overthink it. Avoid <code>low</code>; use <code>medium</code> for everyday work; use <code>high</code> when failure cost is significant or review matters; save <code>xhigh</code> for genuinely heavy tasks.</p>\n<p><strong>Can LazyCodex do computer-use?</strong>\nIt can, if the Codex session has computer-use tools connected. LazyCodex does not provide those tools itself — it directs the agent to use them during workflows and enforces stronger verification when they are available.</p>\n<h3 id=\"conflicts-amp-limits\">Conflicts &amp; limits</h3>\n<p><strong>Can I use it on desktop and continue on mobile/remote?</strong>\nLazyCodex installs into Codex, so it works wherever Codex works. The Codex App&#39;s desktop/mobile remote flow pairs well. Some features may only be fully available on the desktop app.</p>\n<p><strong>Team mode shows up but thread creation fails.</strong>\nUpdate LazyCodex and Codex to latest, then run <code>npx lazycodex-ai doctor</code>. Team mode depends on Codex desktop app features that may differ between App and CLI.</p>\n<p><strong>Can I use OMX alongside LazyCodex?</strong>\nNot recommended. Running both together can cause conflicts that burn tokens and fail silently. If the installer warns about a conflict, remove one. LazyCodex is meant to run as the sole thin layer on top of Codex.</p>\n",
+ "faq.md": "<p>Quick answers to common sticking points. Start with <strong>Install &amp; environment</strong> if you are setting up, <strong>First use</strong> if you are choosing a command, <strong>Execution &amp; verification</strong> if something seems off during a run, and <strong>Conflicts &amp; limits</strong> if you hit a wall.</p>\n<h3 id=\"install-amp-environment\">Install &amp; environment</h3>\n<p><strong>What is LazyCodex?</strong>\nA light port of OmO for Codex. It layers commands, skills, hooks, and model routing onto Codex so the agent plans before it edits, verifies before it claims done, and keeps project context across sessions.</p>\n<p><strong>Is LazyCodex a replacement for OmO?</strong>\nNo. It is a focused subset. The full OmO has deeper orchestration. LazyCodex takes the parts that work well inside Codex and packages them as a repeatable install.</p>\n<p><strong>Can I ask Codex to install it for me?</strong>\nYes. Open Codex and give it the LazyCodex GitHub link or <code>lazycodex.ai</code>, then ask it to install. Or run <code>npx lazycodex-ai install</code> yourself.</p>\n<p><strong>Is there a difference between Codex App and Codex CLI installs?</strong>\nThey follow the same flow. LazyCodex installs into the Codex environment. Use whichever surface you prefer — App or CLI.</p>\n<p><strong>Do I need Bun?</strong>\nNo. Unless you are building LazyCodex from source, Bun is not required. Install and usage go through <code>npx</code> with plain Node.js/npm.</p>\n<p><strong>Does it work on Windows?</strong>\nYes. Both the npx installer and the Codex marketplace path support Windows natively. The installer provisions Node.js and Git Bash automatically when they are missing, and shell hooks run through Git Bash. If you already have Node.js and Git for Windows installed, everything works out of the box. See the <a href=\"#installation\">Windows section in Installation</a> for environment variable overrides and bootstrap logs.</p>\n<h3 id=\"first-use\">First use</h3>\n<p><strong>What kind of tasks is LazyCodex best at?</strong>\nLarge, long-running work where planning and verification matter. Small questions or one-line fixes can go straight to Codex without the harness.</p>\n<p><strong>Do I need to study every skill before using it?</strong>\nNo. Skills auto-activate when a task matches their domain. Learn the four commands first; dig into individual skills when you hit a specific need.</p>\n<p><strong>Which commands should I learn first?</strong>\n<code>$init-deep</code> for project memory, <code>$ulw-plan</code> for planning, <code>$start-work</code> for executing a plan, and <code>$ulw-loop</code> for open-ended tasks that need verified completion.</p>\n<p><strong>How do I know the install worked?</strong>\nOpen Codex and type <code>$</code> in the input — you should see OmO commands and skills listed. On the CLI, typing <code>ulw</code> should activate ultrawork mode. The first real command is usually <code>$init-deep</code>.</p>\n<p><strong>The $ menu does not show any commands after install.</strong>\nOpen a new Codex session to reload the plugin, then check whether the startup review has a pending <code>omo</code> hook approval. If it still does not show, run <code>npx lazycodex-ai doctor</code> to check install and skill loading state.</p>\n<h3 id=\"execution-amp-verification\">Execution &amp; verification</h3>\n<p><strong>Is <code>npx lazycodex-ai doctor</code> a real thing?</strong>\nYes. It runs the OmO doctor flow and reports what is configured, what is missing, and why. Use it whenever something looks off.</p>\n<p><strong>Why does it ask me to approve hooks?</strong>\nCodex reviews hooks at startup. The <code>omo</code> hooks do not run until you approve them. After each upgrade the hooks show as <strong>Modified</strong> because the plugin files changed — re-approve to pick up the new version.</p>\n<p><strong>What should I check after an upgrade?</strong>\nIf hooks show as Modified, re-approve them. If anything looks pending or degraded, run <code>npx lazycodex-ai doctor</code> for the full picture.</p>\n<p><strong><code>$ulw-loop</code> keeps finishing too quickly — what do I do?</strong>\nIteration alone does not fix vague completion criteria. Be specific about what you want collected, what verification must pass, and what the agent should investigate when data is missing. Or run <code>$ulw-plan</code> first to nail down the scope.</p>\n<p><strong>Do I need a bigger token budget?</strong>\nLazyCodex is not a token-saving tool. It pushes good models and enough tokens through planning, execution, and verification. For large tasks, split work into smaller units before a single thread gets too heavy.</p>\n<p><strong>How do I pick a thinking/reasoning level?</strong>\nDo not overthink it. Avoid <code>low</code>; use <code>medium</code> for everyday work; use <code>high</code> when failure cost is significant or review matters; save <code>xhigh</code> for genuinely heavy tasks.</p>\n<p><strong>Can LazyCodex do computer-use?</strong>\nIt can, if the Codex session has computer-use tools connected. LazyCodex does not provide those tools itself — it directs the agent to use them during workflows and enforces stronger verification when they are available.</p>\n<h3 id=\"conflicts-amp-limits\">Conflicts &amp; limits</h3>\n<p><strong>Can I use it on desktop and continue on mobile/remote?</strong>\nLazyCodex installs into Codex, so it works wherever Codex works. The Codex App&#39;s desktop/mobile remote flow pairs well. Some features may only be fully available on the desktop app.</p>\n<p><strong>Team mode shows up but thread creation fails.</strong>\nUpdate LazyCodex and Codex to latest, then run <code>npx lazycodex-ai doctor</code>. Team mode depends on Codex desktop app features that may differ between App and CLI.</p>\n<p><strong>Can I use OMX alongside LazyCodex?</strong>\nNot recommended. Running both together can cause conflicts that burn tokens and fail silently. If the installer warns about a conflict, remove one. LazyCodex is meant to run as the sole thin layer on top of Codex.</p>\n",
"init-deep.md": "<p><code>$init-deep</code> generates hierarchical <code>AGENTS.md</code> context so agents start from local guidance before touching a large repository. Run it once per project, and again whenever the architecture shifts enough that the existing context no longer reflects reality.</p>\n<h3 id=\"what-it-produces\">What it produces</h3>\n<ul>\n<li>A root <code>AGENTS.md</code> that orients agents to the project: stack, layout, conventions, and where to look first.</li>\n<li>Nested <code>AGENTS.md</code> files in the directories that matter most, so an agent descending into a package gets scoped guidance instead of guessing.</li>\n<li>References to project rules, skills, and instruction files the harness should respect.</li>\n</ul>\n<h3 id=\"when-to-run-it\">When to run it</h3>\n<ul>\n<li>Onboarding a repository that is too large or too old to explain from memory.</li>\n<li>After a major refactor, migration, or layout change.</li>\n<li>When agents keep picking the wrong files or ignoring local conventions.</li>\n</ul>\n<h3 id=\"how-to-use-it\">How to use it</h3>\n<pre><code class=\"language-text\">$init-deep\n</code></pre>\n<p>The command walks the tree, reads the files that define how the project actually works, and writes the context. Review the generated <code>AGENTS.md</code> files, trim anything stale, and commit them. Agents in later turns read that context before they edit, so the first session pays for every session after it.</p>\n<h3 id=\"after-init\">After init</h3>\n<p>With context in place, move to <a href=\"#ulw-plan\"><code>$ulw-plan</code></a> when the work needs a plan, or <a href=\"#ulw-loop\"><code>$ulw-loop</code></a> for a single verified task.</p>\n",
"ulw-plan.md": "<p><code>$ulw-plan</code> is the strategic planning consultant (Prometheus). It turns an idea into a decision-complete work plan. It is a planner, NOT an implementer. When you say &quot;do X&quot; it produces a plan for X and never writes product code.</p>\n<h3 id=\"the-flow\">The flow</h3>\n<ol>\n<li><strong>Socratic interview</strong> — ask only the forks that exploration cannot resolve. When intent is fuzzy, research to best practice instead of interrogating.</li>\n<li><strong>Parallel codebase exploration</strong> — fan out read-only subagents to ground every decision in the actual code, never in memory.</li>\n<li><strong>Metis gap analysis</strong> — name every unknown the plan depends on and either close it or surface it as an explicit fork.</li>\n<li><strong>Write the plan</strong> to <code>plans/&lt;slug&gt;.md</code> — one decision-complete plan a worker executes with zero further interview.</li>\n<li><strong>Optional Momus high-accuracy review</strong> — an adversarial pass that tries to break the plan before it ships.</li>\n</ol>\n<h3 id=\"output\">Output</h3>\n<p>Questions, research, and a work plan whose every todo carries references, acceptance criteria, a QA plan, and a commit boundary. The plan records <code>status: awaiting-approval</code> and waits — it never begins execution itself.</p>\n<h3 id=\"handoff\">Handoff</h3>\n<p>Once you approve, hand the plan to <a href=\"#start-work\"><code>$start-work</code></a>, which executes it against durable Boulder state with the five evidence gates.</p>\n",
"start-work.md": "<p><code>$start-work</code> executes a Prometheus work plan until every top-level checkbox is done.</p>\n<h3 id=\"how-it-works\">How it works</h3>\n<ul>\n<li>Durable Boulder state in <code>.omo/boulder.json</code> survives across turns and sessions</li>\n<li>A Stop-hook re-injects the next turn until the plan is complete</li>\n<li>Independent sub-tasks fan out to parallel subagents</li>\n<li>Strict TDD plus five evidence gates: plan reread, automated verification, manual-QA, adversarial QA, cleanup</li>\n<li>Progress is recorded to a ledger</li>\n</ul>\n<h3 id=\"syntax\">Syntax</h3>\n<pre><code class=\"language-bash\">$start-work [plan-name] [--worktree &lt;absolute-path&gt;]\n</code></pre>\n<h3 id=\"done\">Done</h3>\n<p>It prints an <code>ORCHESTRATION COMPLETE</code> block when every checkbox is checked.</p>\n",
"ulw-loop.md": "<p><code>$ulw-loop</code> is a self-referential development loop that decomposes work into systematic, evidence-bound steps and runs until verified completion.</p>\n<h3 id=\"how-it-works\">How it works</h3>\n<p>The agent works continuously and emits <code>&lt;promise&gt;DONE&lt;/promise&gt;</code> when it believes the task is complete, but that does NOT end the loop. An Oracle must verify the result first. The loop ends only after the system confirms the Oracle verified it. If verification fails, it continues with the message: &quot;Oracle verification failed. Continuing ULTRAWORK loop.&quot;</p>\n<p>Each step carries its own evidence: a real artifact, not a dry-run claim. Progress is checkpointed, so a long run survives restarts without losing what was already proven.</p>\n<h3 id=\"bootstrap\">Bootstrap</h3>\n<p>Before the first run, the loop reads its full workflow reference (Bootstrap tier triage, the Execution Loop, and the Manual-QA channels table) so every later phase executes the same way. It only reads the sections the current phase needs.</p>\n<h3 id=\"manual-qa-channels\">Manual-QA channels</h3>\n<p>A step does not close on a status string. It closes on a captured artifact from a real surface — an HTTP call, a tmux session, or a browser — plus an adversarial pass and a cleanup receipt. See <a href=\"#manual-qa\">manual QA</a>.</p>\n<h3 id=\"syntax\">Syntax</h3>\n<pre><code class=\"language-bash\">$ulw-loop &quot;task description&quot; [--completion-promise=TEXT] [--strategy=reset|continue]\n</code></pre>\n<h3 id=\"limits\">Limits</h3>\n<p>The iteration cap is 500 in ultrawork mode (100 in normal mode).</p>\n<h3 id=\"reading-more\">Reading more</h3>\n<ul>\n<li><a href=\"#ultrawork\">ultrawork mode</a> — the mode that turns the loop into a binding verified run.</li>\n<li><a href=\"#hooks-lifecycle\">Hooks &amp; Lifecycle</a> — how the Stop-hook re-injects the next turn.</li>\n</ul>\n",
- "skills.md": "<p>LazyCodex is most useful as a harness for complex codebases: project memory, planning, execution, verified completion, skills, hooks, model routing, and diagnostics.</p>\n<h3 id=\"built-in-workflows\">Built-in workflows</h3>\n<p>Start with <code>$init-deep</code> when the repository is too large or too old to explain from memory. It generates hierarchical <code>AGENTS.md</code> context so agents can find the right files before they change code.</p>\n<p>Use <code>$ulw-plan</code> when the work needs decisions before implementation, <code>$start-work</code> when a plan should be executed, and <code>$ulw-loop</code> when you want the agent to keep going until the result is verified.</p>\n<h3 id=\"feature-coverage\">Feature coverage</h3>\n<p>The three command pillars stay simple:</p>\n<ul>\n<li><code>$ulw-loop</code> keeps moving until verified completion</li>\n<li><code>$ulw-plan</code> turns fuzzy work into a decision-complete plan</li>\n<li><code>$start-work</code> executes a plan with durable Boulder progress</li>\n</ul>\n<p>Skills add specialist judgment around those pillars.</p>\n<p>Most skills auto-activate when a request matches their domain, so you do not need to study or manually select every skill before using LazyCodex. When you want to be explicit, put the skill name in the prompt — for example <code>$visual-qa</code>, <code>$git-master</code>, or <code>$ultraresearch</code>.</p>\n<table>\n<thead>\n<tr>\n<th>Skill</th>\n<th>Use it for</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>init-deep</code></td>\n<td>Hierarchical <code>AGENTS.md</code> context for large or old repos</td>\n</tr>\n<tr>\n<td><code>ulw-plan</code></td>\n<td>Explore-first planning before coding</td>\n</tr>\n<tr>\n<td><code>ulw-loop</code></td>\n<td>Evidence-bound loop until verified completion</td>\n</tr>\n<tr>\n<td><code>start-work</code></td>\n<td>Execute a plan with durable Boulder progress</td>\n</tr>\n<tr>\n<td><code>review-work</code></td>\n<td>Five-lane parallel post-implementation review</td>\n</tr>\n<tr>\n<td><code>remove-ai-slops</code></td>\n<td>Behavior-preserving cleanup of AI-looking code</td>\n</tr>\n<tr>\n<td><code>frontend</code></td>\n<td>Designed UI work instead of generic layout filling</td>\n</tr>\n<tr>\n<td><code>programming</code></td>\n<td>Strict TypeScript, Rust, Python, or Go discipline, TDD-first</td>\n</tr>\n<tr>\n<td><code>git-master</code></td>\n<td>Atomic commits, rebase/squash, push safety, history investigation</td>\n</tr>\n<tr>\n<td><code>visual-qa</code></td>\n<td>Screenshot/TUI diff plus dual-oracle visual QA</td>\n</tr>\n<tr>\n<td><code>debugging</code></td>\n<td>Evidence-led root-cause investigation</td>\n</tr>\n<tr>\n<td><code>refactor</code></td>\n<td>Behavior-preserving restructure of existing code</td>\n</tr>\n<tr>\n<td><code>ultraresearch</code></td>\n<td>Maximum-saturation research: parallel codebase, web, official-docs, and OSS-repo swarms, recursive lead expansion, empirical verification, and cited synthesis</td>\n</tr>\n<tr>\n<td><code>LSP</code></td>\n<td>Diagnostics, definitions, references, symbols, and renames</td>\n</tr>\n<tr>\n<td><code>lsp-setup</code></td>\n<td>Configure language servers for a project</td>\n</tr>\n<tr>\n<td><code>AST-grep</code></td>\n<td>Structural search and rewrite across code</td>\n</tr>\n<tr>\n<td><code>rules</code></td>\n<td>Project instructions from AGENTS, rules, and instruction files</td>\n</tr>\n<tr>\n<td><code>comment-checker</code></td>\n<td>Feedback after edit-like operations</td>\n</tr>\n</tbody></table>\n<h3 id=\"skill-highlights\">Skill highlights</h3>\n<p><strong>review-work</strong> — A post-implementation review orchestrator. After significant work, it launches five parallel sub-agents covering goal/constraint verification, hands-on QA execution, code quality, security, and context mining from git history and issues. All five must pass for the review to pass. One failure means the review fails.</p>\n<p><strong>remove-ai-slops</strong> — Removes AI-generated code smells while strictly preserving behavior. The safety invariant: regression tests lock behavior <em>before</em> a single line is deleted. Covers obvious comments, excessive defensive code, unnecessary abstractions, dead code, duplicates, and oversized modules (250+ pure LOC triggers a full modular refactoring).</p>\n<p><strong>frontend</strong> — Not a single rule file but a router. It reads design, perfection, and ui-ux-db references based on the task, then builds and verifies against the actual browser. Covers UI implementation, styling, layout, animation, Lighthouse 100, Core Web Vitals, accessibility, and React dev tools.</p>\n<p><strong>programming</strong> — One philosophy across four languages: strict types, modern stacks (Pydantic v2 / serde+thiserror / Zod / gin+sqlc+pgx+slog), parse-don&#39;t-validate, exhaustive match, typed errors, no escape hatches, 250 pure LOC ceiling, TDD. The skill gates on language and loads the matching reference set before writing a single line.</p>\n<p><strong>debugging</strong> — Hypothesis-driven runtime debugging. Every claim about why a bug happens must come from observed state, not code reading. Covers crashes, silent failures, wrong responses, stuck processes, memory leaks, async misbehavior, and reverse engineering. Leaves no debug artifacts behind.</p>\n<p><strong>refactor</strong> — Maps the codebase before touching anything, evaluates test coverage to set the verification strategy, plans atomic steps with rollback points, then executes with LSP and AST-grep. Any test failure during execution triggers an immediate stop and revert.</p>\n<p><strong>LSP</strong> — Gives the agent language-server precision: diagnostics, go-to-definition, find-references, document symbols, and safe workspace-wide renames. Runs as MCP tool calls, not shell commands.</p>\n<p><strong>rules</strong> — Automatically injects project instructions from <code>CONTEXT.md</code>, <code>.omo/rules/</code>, <code>.claude/rules/</code>, <code>.github/instructions/</code>, and <code>.github/copilot-instructions.md</code> at session start and on every prompt submit. No command to run — just works when the plugin is active.</p>\n<p><strong>comment-checker</strong> — Fires after every edit-like tool call. If it flags a comment, Codex receives blocking feedback and must fix or justify the comment before proceeding. Catches comment drift (comments that no longer match the code below them) at the moment of introduction rather than in a later review.</p>\n<h3 id=\"where-skills-live\">Where skills live</h3>\n<p>OmO can load skills from project and user locations such as <code>.opencode/skills</code>, <code>~/.config/opencode/skills</code>, <code>.claude/skills</code>, <code>.agents/skills</code>, and <code>~/.agents/skills</code>.</p>\n<p>LazyCodex installs the Codex Light setup with:</p>\n<pre><code class=\"language-bash\">npx lazycodex-ai install\n</code></pre>\n<p>That installer wires the Codex marketplace plugin as <code>omo@sisyphuslabs</code> while keeping the public package alias easy to remember.</p>\n<p>The command pillars and the disciplines behind them are covered in depth: <a href=\"#ulw-plan\">ulw-plan</a>, <a href=\"#ulw-loop\">ulw-loop</a>, <a href=\"#start-work\">start-work</a>, <a href=\"#tdd\">TDD</a>, <a href=\"#manual-qa\">manual QA</a>, and <a href=\"#git-workflow\">git workflow</a>.</p>\n",
- "ultrawork.md": "<p>ultrawork is the headline mode. Typing <code>ultrawork</code> (or the short alias <code>ulw</code>) anywhere in your prompt activates maximum-precision, outcome-first, evidence-driven orchestration.</p>\n<blockquote>\n<p>&quot;Plan, execute, verify, and keep the evidence attached.&quot;</p>\n</blockquote>\n<p>The principle is simple. An agent saying it is done does not mean the work is done. The work is done when <strong>observable evidence verifies</strong> it.</p>\n<h3 id=\"usage\">Usage</h3>\n<pre><code class=\"language-bash\">ulw add authentication\n</code></pre>\n<h3 id=\"what-it-enforces\">What it enforces</h3>\n<ul>\n<li>Strict TDD: RED → GREEN → SURFACE → CLEAN</li>\n<li>At least 3 realistic QA scenarios scaled to the risk of the task</li>\n<li>Real manual-QA channels (HTTP call, tmux, browser, computer use, CLI stdout, data diff)</li>\n<li>A binding verification gate that loops until the work is genuinely done</li>\n</ul>\n<h3 id=\"relationship-to-ulw-loop\">Relationship to <code>$ulw-loop</code></h3>\n<p><code>$ulw-loop</code> is the command form of ultrawork discipline. The latest flow stores request, goals, success criteria, and an evidence ledger under <code>.omo/ulw-loop</code>:</p>\n<table>\n<thead>\n<tr>\n<th>File</th>\n<th>Role</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>.omo/ulw-loop/brief.md</code></td>\n<td>Original request and persistent constraints</td>\n</tr>\n<tr>\n<td><code>.omo/ulw-loop/goals.json</code></td>\n<td>Goals and success criteria</td>\n</tr>\n<tr>\n<td><code>.omo/ulw-loop/ledger.jsonl</code></td>\n<td>pass, fail, block, steering, checkpoint records</td>\n</tr>\n</tbody></table>\n<p>Saying &quot;done&quot; is not enough. Each success criterion requires evidence captured from a real surface, and that evidence must pass before the loop stops.</p>\n<p>The exact syntax and flags live in the <a href=\"#ulw-loop\"><code>$ulw-loop</code> command docs</a>.</p>\n<h3 id=\"failure-limits\">Failure limits</h3>\n<p>The loop does not run forever. The latest <code>$ulw-loop</code> workflow uses these caps:</p>\n<table>\n<thead>\n<tr>\n<th>Condition</th>\n<th>Limit</th>\n</tr>\n</thead>\n<tbody><tr>\n<td>Iterations on one goal without a full pass</td>\n<td>5 cycles</td>\n</tr>\n<tr>\n<td>Same failure on the same criterion</td>\n<td>3 times</td>\n</tr>\n</tbody></table>\n<h3 id=\"evidence-over-hope\">Evidence over hope</h3>\n<p>The loop does not stop at &quot;I wrote some code.&quot; It stops when the result is confirmed by evidence — what check ran and what it showed — not by the agent&#39;s expected status report.</p>\n<h3 id=\"position-among-commands\">Position among commands</h3>\n<p><code>$ulw-loop</code> is one of several commands, each for a different shape of work.</p>\n<p>The typical flow: <code>$ulw-plan</code> produces a decision-complete plan, <code>$start-work</code> executes it checkpoint by checkpoint, and <code>$ulw-loop</code> keeps open-ended work running until a verifier approves. Detailed syntax for each command is in the <a href=\"#ulw-plan\">Commands</a> section.</p>\n",
+ "skills.md": "<p>Skills are specialist playbooks that LazyCodex loads on top of the command pillars. They auto-activate when a task matches their domain — you do not need to study or memorize them. Include <code>ultrawork</code> (or the short alias <code>ulw</code>) in your prompt and the harness picks the right skills internally.</p>\n<p>When you want to call a skill explicitly, put its name in the prompt: <code>$review-work</code>, <code>$remove-ai-slops</code>, <code>$ulw-research</code>, and so on.</p>\n<h3 id=\"commands\">Commands</h3>\n<p>The command pillars stay simple:</p>\n<ul>\n<li><code>$init-deep</code> — project memory</li>\n<li><code>$ulw-plan</code> — decision-complete planning before coding</li>\n<li><code>$start-work</code> — execute a plan with durable Boulder progress</li>\n<li><code>$ulw-loop</code> — evidence-bound loop until verified completion</li>\n</ul>\n<p>Skills add specialist judgment around those pillars. The sections below describe each skill and how it is typically used.</p>\n<hr>\n<h3 id=\"review-work\">review-work</h3>\n<p>Five-lane parallel post-implementation review.</p>\n<p>After significant work, <code>review-work</code> launches five sub-agents in parallel — each covering a different angle: goal/constraint verification, hands-on QA execution, code quality, security, and context mining from git history and issues. All five must pass for the review to pass. One failure means the review fails.</p>\n<p><strong>When it activates:</strong> After completing any meaningful implementation — especially when the change touches 3+ files or runs for 20+ minutes.</p>\n<p><strong>Example:</strong> After finishing a PR, the user says:</p>\n<pre><code class=\"language-text\">review my work\n</code></pre>\n<p>The harness spawns five parallel reviewers in separate threads, each with a focused lens. The final verdict is PASS only when every lane agrees.</p>\n<hr>\n<h3 id=\"remove-ai-slops\">remove-ai-slops</h3>\n<p>Behavior-preserving cleanup of AI-generated code smells.</p>\n<p>The safety invariant: regression tests lock behavior <em>before</em> a single line is deleted. Covers obvious comments, excessive defensive code, unnecessary abstractions, dead code, duplicates, and oversized modules (250+ pure LOC triggers a full modular refactoring). Workers run in parallel batches of five, and any test failure triggers an immediate revert.</p>\n<p><strong>When it activates:</strong> When asked to clean, deslop, or remove AI-generated patterns.</p>\n<p><strong>Example:</strong> Combining with <code>refactor</code> and <code>programming</code> for a full cleanup pass:</p>\n<pre><code class=\"language-text\">ulw plan and manual qa, no behaviour changes, no regressions\n/refactor /remove-ai-slops through /programming\n</code></pre>\n<p>The harness plans the cleanup first, locks behavior with tests, then dispatches parallel workers by slop category — safe to dangerous order.</p>\n<hr>\n<h3 id=\"frontend\">frontend</h3>\n<p>UI, UX, design, performance, accessibility, and visual QA — all in one router.</p>\n<p>Not a single rule file but a router. It reads design, perfection, and ui-ux-db references based on the task, then builds and verifies against the actual browser. Covers UI implementation, styling, layout, animation, Lighthouse 100, Core Web Vitals, accessibility, SEO, and React dev tools like <code>react-scan</code> and <code>react-doctor</code>.</p>\n<p><strong>When it activates:</strong> Any task involving UI, styling, layout, animation, design, or performance auditing.</p>\n<p><strong>Example:</strong></p>\n<pre><code class=\"language-text\">redesign the sidebar with better spacing and hit Lighthouse 100\n</code></pre>\n<p>The skill routes to the right design references, builds to match the existing design system, then runs a real Playwright Chromium Lighthouse audit — never the Lighthouse CLI, never by weakening UX.</p>\n<hr>\n<h3 id=\"programming\">programming</h3>\n<p>One philosophy across four languages: strict types, modern stacks, TDD.</p>\n<p>Applies to every <code>.py</code>, <code>.pyi</code>, <code>.rs</code>, <code>.ts</code>, <code>.tsx</code>, <code>.mts</code>, <code>.cts</code>, <code>.go</code> file. The skill gates on language, loads the matching reference set, and enforces: parse-don&#39;t-validate at boundaries, exhaustive variant matching, typed errors, no escape hatches (<code>any</code>, <code>unwrap</code>, <code>@ts-ignore</code>), 250 pure LOC ceiling per file, and mandatory TDD (RED → GREEN → REFACTOR).</p>\n<p><strong>When it activates:</strong> Automatically on any code file edit in the supported languages.</p>\n<p><strong>Example:</strong> The skill is always on. When editing TypeScript, it loads the TypeScript reference (Bun + Biome + strict tsconfig), enforces branded types and discriminated unions, and runs the post-write review loop: measure pure LOC, self-review seven questions, refactor if over 250 LOC.</p>\n<hr>\n<h3 id=\"debugging\">debugging</h3>\n<p>Hypothesis-driven runtime debugging across any language or binary.</p>\n<p>Every claim about why a bug happens must come from observed runtime state, not code reading. The skill runs a phased loop: setup and journal, form 3+ orthogonal hypotheses, investigate in parallel, escalate to independent verifiers after 2 failed rounds, confirm root cause by toggling, lock with a failing test, fix minimally, QA on the real surface, then clean up every debug artifact.</p>\n<p><strong>When it activates:</strong> Crashes, silent failures, wrong responses, stuck processes, memory leaks, async misbehavior, or reverse engineering.</p>\n<p><strong>Example:</strong></p>\n<pre><code class=\"language-text\">debug this — the API returns 200 but the body is empty\n</code></pre>\n<p>The skill fires parallel investigation lanes, attaches real debuggers (pdb, node inspect, lldb, dlv), and does not close the bug until the root cause is confirmed by toggling and a failing test goes GREEN.</p>\n<hr>\n<h3 id=\"refactor\">refactor</h3>\n<p>Codemap-aware, LSP- and AST-grep-powered restructuring.</p>\n<p>Maps the codebase before touching anything, evaluates test coverage to set the verification strategy, plans atomic steps with rollback points, then executes with LSP renames and AST-grep structural rewrites. Any test failure during execution triggers an immediate stop and revert.</p>\n<p><strong>When it activates:</strong> Requests to refactor, restructure, extract, simplify, or modernize code.</p>\n<p><strong>Example:</strong></p>\n<pre><code class=\"language-text\">refactor the validation logic into its own module --scope=module\n</code></pre>\n<p>The skill builds a dependency graph of the target, runs characterization tests to pin current behavior, then executes the restructuring step by step — verifying after each step.</p>\n<hr>\n<h3 id=\"visual-qa\">visual-qa</h3>\n<p>Screenshot and TUI diff plus dual-oracle visual QA.</p>\n<p>Captures reference and actual evidence — screenshots for web UIs, <code>tmux capture-pane</code> for terminal UIs — then runs a bundled pixel-diff or column-width script. Two parallel read-only oracle passes evaluate: one for design-system and functional integrity, one for visual fidelity and CJK text precision. The final verdict is a single good/bad score.</p>\n<p><strong>When it activates:</strong> After building or changing any UI, or when asked to verify visual correctness.</p>\n<hr>\n<h3 id=\"git-master\">git-master</h3>\n<p>Atomic commits, rebase/squash, push safety, history investigation.</p>\n<p>Handles commit message style detection, semantic grouping, fixup autosquash, blame, bisect, <code>log -S</code>, and questions like &quot;who wrote this&quot; or &quot;when was this added.&quot;</p>\n<p><strong>When it activates:</strong> Any git operation — committing, rebasing, squashing, history search.</p>\n<hr>\n<h3 id=\"ulw-research\">ulw-research</h3>\n<p>Maximum-saturation research mode (formerly <code>ultraresearch</code>).</p>\n<p>Orchestrates parallel explore and librarian swarms across the codebase, the web, official documentation, and OSS repositories. Runs a recursive EXPAND loop driven by leads that workers return, verifies findings empirically by running code, and produces cited synthesis with optional reports.</p>\n<p><strong>When it activates:</strong> Only on explicit demand — the word <code>ulw-research</code>, the legacy alias <code>ultraresearch</code>, or any request for deep research or an ultra-precise investigation.</p>\n<p><strong>Example:</strong></p>\n<pre><code class=\"language-text\">ulw-research the typeclaw architecture — map every module and find the official docs\n</code></pre>\n<p>The skill fans out 10+ parallel search lanes across GitHub, official docs, and web sources, recursively expands promising leads, then synthesizes a cited report.</p>\n<hr>\n<h3 id=\"lsp\">LSP</h3>\n<p>Language-server diagnostics, definitions, references, symbols, and safe renames.</p>\n<p>Gives the agent language-server precision via MCP tool calls. Runs diagnostics after every edit, finds definitions and references across the workspace, and performs safe renames through the language server&#39;s own workspace edit — not text find-and-replace.</p>\n<p><strong>When it activates:</strong> Automatically after edit-like tool calls (diagnostics), and on demand for navigation and renames.</p>\n<hr>\n<h3 id=\"ast-grep\">AST-grep</h3>\n<p>Structural search and rewrite across 25 languages.</p>\n<p>Finds code by syntactic shape rather than text — every function call matching a pattern, every import shaped like X. Rewrites are deterministic and always previewed with <code>dryRun=true</code> before applying. Pairs with the <code>refactor</code> skill for safe, large-scale codemods.</p>\n<p><strong>When it activates:</strong> Structural code matching, pattern-based search, or deterministic rewrites (strip <code>as any</code>, migrate <code>require()</code> to <code>import</code>, find empty catch blocks).</p>\n<hr>\n<h3 id=\"where-skills-live\">Where skills live</h3>\n<p>LazyCodex installs skills as part of the OmO plugin. OmO can also load skills from project and user locations such as <code>.codex/skills</code>, <code>~/.codex/skills</code>, <code>.agents/skills</code>, and <code>~/.agents/skills</code>.</p>\n<p>Each skill carries deep internal references — detailed playbooks, language-specific recipes, and per-phase instructions — but none of that is something you need to read. The harness reads it for you when the skill activates.</p>\n<p>The command pillars and the disciplines behind them are covered in depth: <a href=\"#ulw-plan\">ulw-plan</a>, <a href=\"#ulw-loop\">ulw-loop</a>, <a href=\"#start-work\">start-work</a>, <a href=\"#tdd\">TDD</a>, <a href=\"#manual-qa\">manual QA</a>, and <a href=\"#git-workflow\">git workflow</a>.</p>\n",
+ "ultrawork.md": "<p>ultrawork is the headline mode. Include <code>ultrawork</code> (or the short alias <code>ulw</code>) anywhere in your prompt — like adding <code>ultrathink</code> — and the harness switches to maximum-precision, outcome-first, evidence-driven orchestration. Skills activate internally; you do not need to name them.</p>\n<blockquote>\n<p>&quot;Plan, execute, verify, and keep the evidence attached.&quot;</p>\n</blockquote>\n<p>The principle is simple. An agent saying it is done does not mean the work is done. The work is done when <strong>observable evidence verifies</strong> it.</p>\n<h3 id=\"usage\">Usage</h3>\n<p>Just include the word in your prompt. Nothing else to configure.</p>\n<pre><code class=\"language-text\">ulw add authentication\n</code></pre>\n<pre><code class=\"language-text\">fix the flaky checkout test ultrawork\n</code></pre>\n<p>The harness reads the task, picks the right skills (programming, debugging, refactor, etc.), and runs the evidence-bound loop automatically. You do not choose skills yourself unless you want to be explicit — for example <code>$review-work</code> or <code>$ulw-research</code>.</p>\n<h3 id=\"what-it-enforces\">What it enforces</h3>\n<ul>\n<li>Strict TDD: RED → GREEN → SURFACE → CLEAN</li>\n<li>At least 3 realistic QA scenarios scaled to the risk of the task</li>\n<li>Real manual-QA channels (HTTP call, tmux, browser, computer use, CLI stdout, data diff)</li>\n<li>A binding verification gate that loops until the work is genuinely done</li>\n</ul>\n<h3 id=\"relationship-to-ulw-loop\">Relationship to <code>$ulw-loop</code></h3>\n<p><code>$ulw-loop</code> is the command form of ultrawork discipline. The latest flow stores request, goals, success criteria, and an evidence ledger under <code>.omo/ulw-loop</code>:</p>\n<table>\n<thead>\n<tr>\n<th>File</th>\n<th>Role</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>.omo/ulw-loop/brief.md</code></td>\n<td>Original request and persistent constraints</td>\n</tr>\n<tr>\n<td><code>.omo/ulw-loop/goals.json</code></td>\n<td>Goals and success criteria</td>\n</tr>\n<tr>\n<td><code>.omo/ulw-loop/ledger.jsonl</code></td>\n<td>pass, fail, block, steering, checkpoint records</td>\n</tr>\n</tbody></table>\n<p>Saying &quot;done&quot; is not enough. Each success criterion requires evidence captured from a real surface, and that evidence must pass before the loop stops.</p>\n<p>The exact syntax and flags live in the <a href=\"#ulw-loop\"><code>$ulw-loop</code> command docs</a>.</p>\n<h3 id=\"failure-limits\">Failure limits</h3>\n<p>The loop does not run forever. The latest <code>$ulw-loop</code> workflow uses these caps:</p>\n<table>\n<thead>\n<tr>\n<th>Condition</th>\n<th>Limit</th>\n</tr>\n</thead>\n<tbody><tr>\n<td>Iterations on one goal without a full pass</td>\n<td>5 cycles</td>\n</tr>\n<tr>\n<td>Same failure on the same criterion</td>\n<td>3 times</td>\n</tr>\n</tbody></table>\n<h3 id=\"evidence-over-hope\">Evidence over hope</h3>\n<p>The loop does not stop at &quot;I wrote some code.&quot; It stops when the result is confirmed by evidence — what check ran and what it showed — not by the agent&#39;s expected status report.</p>\n<h3 id=\"position-among-commands\">Position among commands</h3>\n<p><code>$ulw-loop</code> is one of several commands, each for a different shape of work.</p>\n<p>The typical flow: <code>$ulw-plan</code> produces a decision-complete plan, <code>$start-work</code> executes it checkpoint by checkpoint, and <code>$ulw-loop</code> keeps open-ended work running until a verifier approves. Detailed syntax for each command is in the <a href=\"#ulw-plan\">Commands</a> section.</p>\n",
"discipline-agents.md": "<p>LazyCodex ports a single discipline agent from OmO into Codex: <strong>Hephaestus</strong>, the autonomous deep worker. There is no Sisyphus orchestrator in the Codex package — Hephaestus is the one role, and it carries the whole run itself with read-only subagents for parallel exploration.</p>\n<h3 id=\"what-hephaestus-is\">What Hephaestus is</h3>\n<p>Named after the Greek god of the forge. Goal-oriented: you give it objectives, not step-by-step recipes, and it executes them end-to-end. &quot;The Legitimate Craftsman.&quot; Methodical, thorough, obsessive — built for deep architectural reasoning, complex debugging, and cross-domain synthesis.</p>\n<h3 id=\"installed-roles\">Installed roles</h3>\n<p>As of <code>4.12.1</code>, the following roles are installed. When Codex exposes <code>agent_type</code>, the role is set directly; otherwise the role description is included in the message as a fallback.</p>\n<table>\n<thead>\n<tr>\n<th>Role</th>\n<th>Primary use</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>explorer</code></td>\n<td>Internal codebase context: structure, call flows, test locations.</td>\n</tr>\n<tr>\n<td><code>librarian</code></td>\n<td>External docs, library contracts, latest API research.</td>\n</tr>\n<tr>\n<td><code>plan</code></td>\n<td>Plan drafting and task decomposition.</td>\n</tr>\n<tr>\n<td><code>momus</code> / <code>metis</code></td>\n<td>Missing decisions, edge cases, risk review.</td>\n</tr>\n<tr>\n<td><code>lazycodex-executor</code></td>\n<td>Executing specific task units from a plan.</td>\n</tr>\n<tr>\n<td><code>lazycodex-code-reviewer</code></td>\n<td>Post-implementation code quality review.</td>\n</tr>\n<tr>\n<td><code>lazycodex-qa-executor</code></td>\n<td>Real-execution-based QA.</td>\n</tr>\n<tr>\n<td><code>lazycodex-gate-reviewer</code></td>\n<td>Pre-completion verification gates.</td>\n</tr>\n<tr>\n<td><code>lazycodex-clone-fidelity-reviewer</code></td>\n<td>Clone and sync operation fidelity checks.</td>\n</tr>\n</tbody></table>\n<h3 id=\"parent-session-ownership\">Parent session ownership</h3>\n<p>Even with multiple roles, completion judgment is never handed wholesale to a sub-agent. The parent Codex session keeps ownership of goals, constraints, and final judgment. Sub-agents are used to read terrain, find gaps, or assist review.</p>\n<h3 id=\"the-operating-loop\">The operating loop</h3>\n<p>Hephaestus runs a short, tight loop on every unit of work:</p>\n<ol>\n<li><strong>Explore</strong> — map the terrain. Read the code with tools, never speculate. Fire 2-5 parallel explore subagents before writing anything.</li>\n<li><strong>Plan</strong> — chart the course. Record files to modify, specific changes, and dependencies via <code>update_plan</code>.</li>\n<li><strong>Implement</strong> — build with precision. Surgical edits that match codebase style (naming, indentation, imports, error handling) even when a greenfield would read differently.</li>\n<li><strong>Verify</strong> — prove it works. LSP diagnostics on changed files, related tests, and build — in parallel where possible.</li>\n<li><strong>Manually QA</strong> — drive the artifact through its real surface (HTTP call, tmux, browser), then write the final message.</li>\n</ol>\n<h3 id=\"non-goals\">Non-goals</h3>\n<ul>\n<li><strong>Never trusts subagent self-reports.</strong> Verification is independent; a child saying &quot;done&quot; does not close the work.</li>\n<li><strong>Never proposes when you asked for code.</strong> Unless you explicitly want a plan or a brainstorm, it implements.</li>\n<li><strong>Never speculates about code it has not read.</strong> Exploration is cheap; assumption is expensive.</li>\n<li><strong>Never leaves work unresolved at end of turn.</strong> Every plan step is reconciled: <code>completed</code>, blocked (one-line reason), or removed (one-line reason).</li>\n</ul>\n<h3 id=\"delegation-not-orchestration\">Delegation, not orchestration</h3>\n<p>Hephaestus stays the parent. For parallel exploration it spawns read-only Codex subagent roles (<code>multi_agent_v1.spawn_agent</code>) and keeps the parent session live with brief status updates while children run. It does not hand the run off to a separate orchestrator — it owns the goal, delegates the grunt work, and verifies the results itself.</p>\n<h3 id=\"boulder-state\">Boulder state</h3>\n<p><code>$start-work</code> uses <code>.omo/boulder.json</code> to persist progress and the Stop-hook continuation to keep plan execution moving. This is the core visible behavior: checkboxes advance, and when all are done it prints <strong>ORCHESTRATION COMPLETE</strong>.</p>\n<h3 id=\"where-the-boulder-comes-from\">Where the boulder comes from</h3>\n<p>The full OmO has a second primary agent, <strong>Sisyphus</strong>, the orchestrator with <code>.omo/boulder.json</code> session continuity. The Codex package is the Hephaestus-only light port, so on Codex the durable progress state lives in <code>.omo/boulder.json</code> as written by <a href=\"#start-work\"><code>$start-work</code></a> and the Stop-hook continuation — without the Sisyphus orchestration layer.</p>\n<h3 id=\"reading-more\">Reading more</h3>\n<ul>\n<li><a href=\"#ultrawork\">ultrawork mode</a> — the mode that turns the loop into a binding verified run.</li>\n<li><a href=\"#hooks-lifecycle\">Hooks &amp; Lifecycle</a> — how the Stop-hook re-injects the next turn until the plan is complete.</li>\n</ul>\n",
"model-routing.md": "<p>Multi-model routing sends each part of a run to the model that fits it best, instead of running everything on one model. LazyCodex installs OmO&#39;s routing defaults into Codex so a serious repository is not bottlenecked by a single context window or price point.</p>\n<h3 id=\"current-baseline\">Current baseline</h3>\n<p>The <code>4.12.1</code> bundled <code>model-catalog.json</code> centers the default profile on <code>gpt-5.5</code>:</p>\n<table>\n<thead>\n<tr>\n<th>Profile</th>\n<th>Model</th>\n<th>Reasoning</th>\n</tr>\n</thead>\n<tbody><tr>\n<td>Default</td>\n<td><code>gpt-5.5</code></td>\n<td><code>high</code></td>\n</tr>\n<tr>\n<td>Plan mode</td>\n<td><code>gpt-5.5</code></td>\n<td><code>xhigh</code></td>\n</tr>\n<tr>\n<td>Worker</td>\n<td><code>gpt-5.5</code></td>\n<td><code>high</code></td>\n</tr>\n<tr>\n<td>Verifier</td>\n<td><code>gpt-5.5</code></td>\n<td><code>high</code></td>\n</tr>\n</tbody></table>\n<p>The actual model name you see may differ as Codex and OpenAI update their model lineup. This doc focuses on <em>how</em> LazyCodex uses model profiles, not on comparing specific models.</p>\n<h3 id=\"what-gets-routed\">What gets routed</h3>\n<ul>\n<li><strong>Planning and exploration</strong> go to a strong reasoning model that can hold a large context and weigh trade-offs.</li>\n<li><strong>Implementation turns</strong> go to a fast, capable coding model for the bulk of the edit loop.</li>\n<li><strong>Verification</strong> goes to a model used as an oracle, chosen for judgment rather than throughput.</li>\n<li><strong>Specialist skills</strong> can target their own model when a skill benefits from a specific profile.</li>\n</ul>\n<h3 id=\"why-role-profiles-exist\">Why role profiles exist</h3>\n<p>Role-based profiles separate work by nature:</p>\n<ul>\n<li>General tasks follow the default model setting.</li>\n<li>Plan mode may demand stronger reasoning.</li>\n<li>Worker and verifier are kept separate so the same result is checked from a different angle.</li>\n</ul>\n<p>This pairs with <a href=\"#discipline-agents\">Agent Roles</a>. Even when multiple roles move in parallel, each role&#39;s model profile is tracked in the Codex configuration.</p>\n<h3 id=\"how-it-fits-the-harness\">How it fits the harness</h3>\n<p>Routing is part of the harness setup that <code>npx lazycodex-ai install</code> wires into Codex. It detects the available subscriptions and provider auth, then maps roles to models so you do not hand-configure each one.</p>\n<h3 id=\"provider-auth\">Provider auth</h3>\n<p>Auth targets Codex itself, not LazyCodex. Once Codex is logged in, the installer&#39;s subscription detection and provider routing take over. If you let an LLM agent run the install, it walks the same detection and selection for you.</p>\n<h3 id=\"user-notes\">User notes</h3>\n<ul>\n<li>The model name you see after install may differ from what the docs list. The installed <code>model-catalog.json</code> and the models your Codex build supports take precedence.</li>\n<li>Model settings balance quality and speed. Lowering them arbitrarily can degrade planning, review, and QA quality together.</li>\n<li>When in doubt, check install state and Codex config first.</li>\n</ul>\n<h3 id=\"customizing-it\">Customizing it</h3>\n<p>Routing and provider settings live in the configuration. See <a href=\"#configuration\">Configuration</a> for the fields that control which model handles which role, and how to override the defaults per project.</p>\n",
"hooks-lifecycle.md": "<p>Hooks and lifecycle are how the harness keeps a long run moving without you re-prompting every turn. OmO installs lifecycle hooks into Codex that observe each turn and decide what happens next.</p>\n<h3 id=\"trigger-matrix\">Trigger matrix</h3>\n<table>\n<thead>\n<tr>\n<th>Event</th>\n<th>What fires</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>SessionStart</code></td>\n<td>Project rules loading, telemetry, auto-update check, bootstrap provisioning, CodeGraph bootstrap.</td>\n</tr>\n<tr>\n<td><code>UserPromptSubmit</code></td>\n<td>Project rules re-injection, ultrawork trigger detection, <code>$ulw-loop</code> steering.</td>\n</tr>\n<tr>\n<td><code>PreToolUse</code></td>\n<td>Git Bash MCP guidance on Bash calls, <code>$ulw-loop</code> goal budget protection on goal creation.</td>\n</tr>\n<tr>\n<td><code>PostToolUse</code></td>\n<td>Comment checker, LSP diagnostics, CodeGraph init guidance, <code>apply_patch</code> rule matching, thread title hygiene.</td>\n</tr>\n<tr>\n<td><code>Stop</code> / <code>SubagentStop</code></td>\n<td><code>$start-work</code> continuation, LazyCodex executor evidence verification.</td>\n</tr>\n<tr>\n<td><code>PostCompact</code></td>\n<td>Git Bash notification, project rules, and LSP diagnostics cache resets.</td>\n</tr>\n</tbody></table>\n<h3 id=\"the-core-mechanism\">The core mechanism</h3>\n<p>A Stop-hook fires when a turn ends. If a plan is still in progress, the hook re-injects the next turn automatically — the agent continues from durable progress state instead of waiting for you to say &quot;continue&quot;. The run only stops when the plan is complete or a gate fails in a way that needs a human.</p>\n<h3 id=\"where-progress-lives\">Where progress lives</h3>\n<p>Progress state is written to <code>.omo/boulder.json</code> and survives across turns and sessions. That is what lets <a href=\"#start-work\"><code>$start-work</code></a> resume a plan after a restart, and what keeps <a href=\"#ulw-loop\"><code>$ulw-loop</code></a> honest about how far it has actually gotten.</p>\n<h3 id=\"approval-and-trust\">Approval and trust</h3>\n<p>Hooks never run before approval. On the first launch after install, Codex&#39;s startup review asks you to approve the omo hooks. After every upgrade the hooks show as <strong>Modified</strong> — expected, because the plugin files changed and the previous trust hashes no longer match — re-approve and the next session re-runs bootstrap on the new version.</p>\n<h3 id=\"evidence-gates\">Evidence gates</h3>\n<p>During execution the lifecycle enforces five evidence gates before a step can close: plan reread, automated verification, manual-QA, adversarial QA, and cleanup. A step that cannot pass its gates does not advance, regardless of what the status text claims.</p>\n<h3 id=\"installed-components\">Installed components</h3>\n<p>The hooks above are thin entry points into these installed components:</p>\n<table>\n<thead>\n<tr>\n<th>Component</th>\n<th>Responsibility</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>rules</code></td>\n<td>Project rules at session start, prompt submit, <code>apply_patch</code>, and post-compact.</td>\n</tr>\n<tr>\n<td><code>bootstrap</code></td>\n<td>LazyCodex install state and provisioning checks.</td>\n</tr>\n<tr>\n<td><code>telemetry</code></td>\n<td>Session start recording.</td>\n</tr>\n<tr>\n<td><code>comment-checker</code></td>\n<td>Comment feedback after edit-like tool calls.</td>\n</tr>\n<tr>\n<td><code>lsp</code></td>\n<td>Language-server diagnostics after edit-like tool calls and cache reset after compact.</td>\n</tr>\n<tr>\n<td><code>ultrawork</code></td>\n<td>Ultrawork trigger detection at prompt submit.</td>\n</tr>\n<tr>\n<td><code>ulw-loop</code></td>\n<td>Loop steering and goal budget protection.</td>\n</tr>\n<tr>\n<td><code>start-work-continuation</code></td>\n<td><code>$start-work</code> execution continuation.</td>\n</tr>\n<tr>\n<td><code>git-bash</code></td>\n<td>Git Bash MCP guidance on Bash calls and post-compact.</td>\n</tr>\n<tr>\n<td><code>codegraph</code></td>\n<td>CodeGraph bootstrap and init guidance.</td>\n</tr>\n<tr>\n<td><code>teammode</code></td>\n<td>Thread title hygiene checks.</td>\n</tr>\n<tr>\n<td><code>lazycodex-executor-verify</code></td>\n<td>Sub-agent evidence verification.</td>\n</tr>\n</tbody></table>\n<h3 id=\"reading-more\">Reading more</h3>\n<ul>\n<li><a href=\"#ultrawork\">ultrawork mode</a> — the mode that turns these gates into a binding loop.</li>\n<li><a href=\"#configuration\">Configuration</a> — how to tune hook behavior and lifecycle defaults.</li>\n</ul>\n",
@@ -260,18 +260,63 @@ export const DOC_TOC: Record<string, DocHeading[]> = {
"skills.md": [
{
"level": 3,
- "id": "built-in-workflows",
- "text": "Built-in workflows"
+ "id": "commands",
+ "text": "Commands"
},
{
"level": 3,
- "id": "feature-coverage",
- "text": "Feature coverage"
+ "id": "review-work",
+ "text": "review-work"
+ },
+ {
+ "level": 3,
+ "id": "remove-ai-slops",
+ "text": "remove-ai-slops"
+ },
+ {
+ "level": 3,
+ "id": "frontend",
+ "text": "frontend"
+ },
+ {
+ "level": 3,
+ "id": "programming",
+ "text": "programming"
+ },
+ {
+ "level": 3,
+ "id": "debugging",
+ "text": "debugging"
+ },
+ {
+ "level": 3,
+ "id": "refactor",
+ "text": "refactor"
+ },
+ {
+ "level": 3,
+ "id": "visual-qa",
+ "text": "visual-qa"
+ },
+ {
+ "level": 3,
+ "id": "git-master",
+ "text": "git-master"
+ },
+ {
+ "level": 3,
+ "id": "ulw-research",
+ "text": "ulw-research"
+ },
+ {
+ "level": 3,
+ "id": "lsp",
+ "text": "LSP"
},
{
"level": 3,
- "id": "skill-highlights",
- "text": "Skill highlights"
+ "id": "ast-grep",
+ "text": "AST-grep"
},
{
"level": 3,
diff --git a/packages/web/lib/site-config.ts b/packages/web/lib/site-config.ts
index 0ec6f34d..449ea682 100644
--- a/packages/web/lib/site-config.ts
+++ b/packages/web/lib/site-config.ts
@@ -76,8 +76,8 @@ export const SITE_CONFIG = {
builtInSkills: {
title: "Built-in skill coverage",
summary:
- "Skills auto-activate when a task matches their domain, so you do not need to study every one first. Add a skill name to your prompt when you want to call it explicitly; ultraresearch is the maximum-saturation mode for deep codebase, web, official-docs, and OSS-repo research.",
- skills: ["ultraresearch", "review-work", "remove-ai-slops", "frontend", "programming", "visual-qa", "LSP", "AST-grep", "rules", "comment-checker"],
+ "Skills auto-activate when a task matches their domain, so you do not need to study every one first. Add a skill name to your prompt when you want to call it explicitly; ulw-research is the maximum-saturation mode for deep codebase, web, official-docs, and OSS-repo research.",
+ skills: ["ulw-research", "review-work", "remove-ai-slops", "frontend", "programming", "visual-qa", "LSP", "AST-grep"],
},
} as const;