oh-my-opencode 4.10.0 → 4.11.0

package/packages/shared-skills/skills/frontend/references/ui-ux-db/scripts/search.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+UI/UX Pro Max Search - BM25 search engine for UI/UX style guides
+Usage: python search.py "<query>" [--domain <domain>] [--stack <stack>] [--max-results 3]
+       python search.py "<query>" --design-system [-p "Project Name"]
+       python search.py "<query>" --design-system --persist [-p "Project Name"] [--page "dashboard"]
+
+Domains: style, prompt, color, chart, landing, product, ux, typography
+Stacks: html-tailwind, react, nextjs
+
+Persistence (Master + Overrides pattern):
+  --persist    Save design system to design-system/MASTER.md
+  --page       Also create a page-specific override file in design-system/pages/
+"""
+
+import argparse
+import sys
+import io
+from core import CSV_CONFIG, AVAILABLE_STACKS, MAX_RESULTS, search, search_stack
+from design_system import generate_design_system, persist_design_system
+
+# Force UTF-8 for stdout/stderr to handle emojis on Windows (cp1252 default)
+if sys.stdout.encoding and sys.stdout.encoding.lower() != 'utf-8':
+    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
+if sys.stderr.encoding and sys.stderr.encoding.lower() != 'utf-8':
+    sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8')
+
+
+def format_output(result):
+    """Format results for Claude consumption (token-optimized)"""
+    if "error" in result:
+        return f"Error: {result['error']}"
+
+    output = []
+    if result.get("stack"):
+        output.append(f"## UI Pro Max Stack Guidelines")
+        output.append(f"**Stack:** {result['stack']} | **Query:** {result['query']}")
+    else:
+        output.append(f"## UI Pro Max Search Results")
+        output.append(f"**Domain:** {result['domain']} | **Query:** {result['query']}")
+    output.append(f"**Source:** {result['file']} | **Found:** {result['count']} results\n")
+
+    for i, row in enumerate(result['results'], 1):
+        output.append(f"### Result {i}")
+        for key, value in row.items():
+            value_str = str(value)
+            if len(value_str) > 300:
+                value_str = value_str[:300] + "..."
+            output.append(f"- **{key}:** {value_str}")
+        output.append("")
+
+    return "\n".join(output)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="UI Pro Max Search")
+    parser.add_argument("query", help="Search query")
+    parser.add_argument("--domain", "-d", choices=list(CSV_CONFIG.keys()), help="Search domain")
+    parser.add_argument("--stack", "-s", choices=AVAILABLE_STACKS, help="Stack-specific search (html-tailwind, react, nextjs)")
+    parser.add_argument("--max-results", "-n", type=int, default=MAX_RESULTS, help="Max results (default: 3)")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+    # Design system generation
+    parser.add_argument("--design-system", "-ds", action="store_true", help="Generate complete design system recommendation")
+    parser.add_argument("--project-name", "-p", type=str, default=None, help="Project name for design system output")
+    parser.add_argument("--format", "-f", choices=["ascii", "markdown"], default="ascii", help="Output format for design system")
+    # Persistence (Master + Overrides pattern)
+    parser.add_argument("--persist", action="store_true", help="Save design system to design-system/MASTER.md (creates hierarchical structure)")
+    parser.add_argument("--page", type=str, default=None, help="Create page-specific override file in design-system/pages/")
+    parser.add_argument("--output-dir", "-o", type=str, default=None, help="Output directory for persisted files (default: current directory)")
+
+    args = parser.parse_args()
+
+    # Design system takes priority
+    if args.design_system:
+        result = generate_design_system(
+            args.query, 
+            args.project_name, 
+            args.format,
+            persist=args.persist,
+            page=args.page,
+            output_dir=args.output_dir
+        )
+        print(result)
+        
+        # Print persistence confirmation
+        if args.persist:
+            project_slug = args.project_name.lower().replace(' ', '-') if args.project_name else "default"
+            print("\n" + "=" * 60)
+            print(f"✅ Design system persisted to design-system/{project_slug}/")
+            print(f"   📄 design-system/{project_slug}/MASTER.md (Global Source of Truth)")
+            if args.page:
+                page_filename = args.page.lower().replace(' ', '-')
+                print(f"   📄 design-system/{project_slug}/pages/{page_filename}.md (Page Overrides)")
+            print("")
+            print(f"📖 Usage: When building a page, check design-system/{project_slug}/pages/[page].md first.")
+            print(f"   If exists, its rules override MASTER.md. Otherwise, use MASTER.md.")
+            print("=" * 60)
+    # Stack search
+    elif args.stack:
+        result = search_stack(args.query, args.stack, args.max_results)
+        if args.json:
+            import json
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(format_output(result))
+    # Domain search
+    else:
+        result = search(args.query, args.domain, args.max_results)
+        if args.json:
+            import json
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(format_output(result))

package/packages/shared-skills/skills/frontend/scripts/perfection/lighthouse-audit.py

@@ -0,0 +1,201 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.11"
+# dependencies = [
+#     "playwright",
+#     "typer",
+#     "rich",
+# ]
+# ///
+
+# ─── How to run ───
+# 1. Install uv (if not installed):
+#      curl -LsSf https://astral.sh/uv/install.sh | sh
+# 2. Install Playwright browsers (one-time):
+#      uv run --with playwright python -m playwright install chromium
+# 3. Run:
+#      uv run lighthouse-audit.py https://example.com
+#      uv run lighthouse-audit.py https://example.com --desktop-only
+#      uv run lighthouse-audit.py https://example.com --threshold 95
+# ──────────────────
+
+"""Lighthouse audit via real Playwright Chrome.
+
+Follows the frontend skill perfection ruleset:
+  - NEVER use `lighthouse` CLI (uses headless-shell, not real Chrome)
+  - Use Playwright with channel="chrome" (real Chrome stable)
+  - Run lighthouse Node API via the Playwright CDP endpoint
+  - Mobile preset (primary) + Desktop preset (secondary)
+  - 100 in every category is the floor
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+import typer
+from rich import print as rprint
+from rich.table import Table
+
+
+# Lighthouse config as Node.js script — run via subprocess
+LIGHTHOUSE_RUNNER_JS = """\
+const lighthouse = require('lighthouse');
+const chromeLauncher = require('chrome-launcher');
+
+const url = process.argv[2];
+const port = parseInt(process.argv[3]);
+const preset = process.argv[4]; // 'mobile' or 'desktop'
+
+const config = {
+  extends: 'lighthouse:default',
+  settings: {
+    formFactor: preset === 'desktop' ? 'desktop' : 'mobile',
+    throttling: preset === 'desktop'
+      ? { rttMs: 40, throughputKbps: 10240, cpuSlowdownMultiplier: 1 }
+      : undefined,
+    screenEmulation: preset === 'desktop'
+      ? { mobile: false, width: 1350, height: 940, deviceScaleFactor: 1 }
+      : undefined,
+    onlyCategories: ['performance', 'accessibility', 'best-practices', 'seo'],
+  },
+};
+
+(async () => {
+  const result = await lighthouse(url, { port, logLevel: 'error' }, config);
+  const categories = result.lhr.categories;
+  const output = {};
+  for (const [key, cat] of Object.entries(categories)) {
+    output[key] = Math.round(cat.score * 100);
+  }
+  console.log(JSON.stringify(output));
+})();
+"""
+
+
+def _check_node_deps() -> bool:
+    """Check if lighthouse and chrome-launcher are available."""
+    result = subprocess.run(
+        ["node", "-e", "require('lighthouse'); require('chrome-launcher')"],
+        capture_output=True,
+        text=True,
+    )
+    return result.returncode == 0
+
+
+def _install_node_deps() -> None:
+    """Install lighthouse + chrome-launcher globally."""
+    rprint("[yellow]Installing lighthouse + chrome-launcher...[/yellow]")
+    subprocess.run(
+        ["npm", "install", "-g", "lighthouse", "chrome-launcher"],
+        capture_output=True,
+        check=True,
+    )
+
+
+def _run_lighthouse_via_cdp(url: str, cdp_port: int, preset: str) -> dict[str, int]:
+    """Run lighthouse against a CDP endpoint."""
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".js", delete=False) as f:
+        f.write(LIGHTHOUSE_RUNNER_JS)
+        js_path = f.name
+
+    try:
+        result = subprocess.run(
+            ["node", js_path, url, str(cdp_port), preset],
+            capture_output=True,
+            text=True,
+            timeout=120,
+        )
+        if result.returncode != 0:
+            rprint(f"[red]Lighthouse failed:[/red] {result.stderr}")
+            raise SystemExit(1)
+
+        return json.loads(result.stdout.strip())
+    finally:
+        Path(js_path).unlink(missing_ok=True)
+
+
+def _run_with_playwright(url: str, preset: str) -> dict[str, int]:
+    """Launch real Chrome via Playwright, run Lighthouse against CDP."""
+    from playwright.sync_api import sync_playwright
+
+    with sync_playwright() as p:
+        browser = p.chromium.launch(
+            channel="chrome",
+            headless=True,
+            args=["--remote-debugging-port=0"],
+        )
+
+        # Get the actual CDP port from browser
+        cdp_url = browser.contexts[0].pages[0].url if browser.contexts else ""
+        # Use the browser's websocket endpoint to extract port
+        ws_endpoint = browser._impl_obj._connection._transport._ws_url  # noqa: SLF001
+        # Extract port from ws://127.0.0.1:PORT/...
+        port_str = ws_endpoint.split("://")[1].split(":")[1].split("/")[0]
+        cdp_port = int(port_str)
+
+        try:
+            scores = _run_lighthouse_via_cdp(url, cdp_port, preset)
+        finally:
+            browser.close()
+
+    return scores
+
+
+def _print_scores(scores: dict[str, int], preset: str, threshold: int) -> bool:
+    """Print scores as a rich table. Returns True if all pass."""
+    table = Table(title=f"Lighthouse — {preset}")
+    table.add_column("Category")
+    table.add_column("Score", justify="right")
+    table.add_column("Status")
+
+    all_pass = True
+    for category, score in scores.items():
+        status = "[green]✓ PASS[/green]" if score >= threshold else "[red]✗ FAIL[/red]"
+        if score < threshold:
+            all_pass = False
+        color = "green" if score >= threshold else "red"
+        table.add_row(category, f"[{color}]{score}[/{color}]", status)
+
+    rprint(table)
+    return all_pass
+
+
+def main(
+    url: str = typer.Argument(help="URL to audit"),
+    threshold: int = typer.Option(100, "--threshold", "-t", help="Minimum passing score"),
+    desktop_only: bool = typer.Option(False, "--desktop-only", help="Skip mobile audit"),
+    mobile_only: bool = typer.Option(False, "--mobile-only", help="Skip desktop audit"),
+) -> None:
+    """Run Lighthouse audit via real Playwright Chrome."""
+    # Check node deps
+    if not _check_node_deps():
+        _install_node_deps()
+
+    all_pass = True
+
+    if not desktop_only:
+        rprint(f"\n[bold]Auditing (mobile):[/bold] {url}")
+        mobile_scores = _run_with_playwright(url, "mobile")
+        if not _print_scores(mobile_scores, "Mobile", threshold):
+            all_pass = False
+
+    if not mobile_only:
+        rprint(f"\n[bold]Auditing (desktop):[/bold] {url}")
+        desktop_scores = _run_with_playwright(url, "desktop")
+        if not _print_scores(desktop_scores, "Desktop", threshold):
+            all_pass = False
+
+    if all_pass:
+        rprint("\n[green bold]✓ All categories passed![/green bold]")
+    else:
+        rprint(f"\n[red bold]✗ Some categories below {threshold}. Not done yet.[/red bold]")
+        raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    typer.run(main)

package/packages/shared-skills/skills/init-deep/SKILL.md

@@ -133,7 +133,7 @@ LspWorkspaceSymbols(filePath=".", query="function")
 LspFindReferences(filePath="...", line=X, character=Y)
 ```
 
-**LSP Fallback**: If unavailable, rely on explore agents + AST-grep.
+**LSP Fallback**: If unavailable, use `codegraph_explore` first when codegraph_* tools exist; otherwise rely on explore agents + the ast-grep skill (`sg` CLI).
 
 ### Collect Background Results
 

package/packages/shared-skills/skills/refactor/SKILL.md

@@ -167,23 +167,14 @@ LspWorkspaceSymbols(filePath, query="[target_symbol]")  // Search by name
 lsp_diagnostics(filePath)  // Errors, warnings before we start
 \`\`\`
 
-### AST-Grep for Pattern Analysis:
+### AST-Grep Skill for Pattern Analysis:
 
-\`\`\`typescript
+\`\`\`bash
 // Find structural patterns
-ast_grep_search(
-  pattern="function $NAME($$$) { $$$ }",  // or relevant pattern
-  lang="typescript",  // or relevant language
-  paths=["src/"]
-)
+python3 scripts/ast_grep_helper.py search 'function $NAME($$$) { $$$ }' --lang ts src/
 
-// Preview refactoring (DRY RUN)
-ast_grep_replace(
-  pattern="[old_pattern]",
-  rewrite="[new_pattern]",
-  lang="[language]",
-  dryRun=true  // ALWAYS preview first
-)
+# Preview refactoring first
+sg --pattern '[old_pattern]' --rewrite '[new_pattern]' --lang ts src/
 \`\`\`
 
 ### Grep for Text Patterns:
@@ -429,12 +420,12 @@ lsp_rename(filePath, line, character, newName)  // Execute rename
 \`\`\`
 
 **For Pattern Transformations:**
-\`\`\`typescript
+\`\`\`bash
 // Preview first
-ast_grep_replace(pattern, rewrite, lang, dryRun=true)
+sg --pattern '[pattern]' --rewrite '[rewrite]' --lang ts path/to/file.ts
 
 // If preview looks good, execute
-ast_grep_replace(pattern, rewrite, lang, dryRun=false)
+python3 scripts/ast_grep_helper.py replace '[pattern]' '[rewrite]' --lang ts path/to/file.ts --apply
 \`\`\`
 
 **For Structural Changes:**
@@ -570,7 +561,7 @@ All existing tests pass. No new errors introduced.
 
 ## ALWAYS DO
 - Understand before changing
-- Preview before applying (ast_grep dryRun=true)
+- Preview before applying (`sg --pattern ... --rewrite ... --lang ...`)
 - Verify after every change
 - Follow existing codebase patterns
 - Keep todos updated in real-time
@@ -599,8 +590,8 @@ Leverage LSP tools for precision analysis. Key patterns:
 - **Continuous verification**: \`lsp_diagnostics\` after every change
 
 ## AST-Grep
-Use \`ast_grep_search\` and \`ast_grep_replace\` for structural transformations.
-**Critical**: Always \`dryRun=true\` first, review, then execute.
+Use \`ast-grep\` skill helper or \`sg\` CLI for structural transformations.
+**Critical**: Always preview first, review, then execute.
 
 ## Agents
 - \`explore\`: Parallel codebase pattern discovery
@@ -684,7 +675,7 @@ Record the chosen path in the TodoWrite list.
     {
       "kind": "category",
       "category": "unspecified-low",
-      "prompt": "You handle logic-preserving refactors that need reasoning (extract function, restructure conditional, pattern transformation, cross-file API change). Read the task description's plan step carefully. Use ast_grep_replace with dryRun=true first, review the preview, then execute. If the step is ambiguous or would require out-of-scope changes, STOP and send team_send_message(teamRunId=<id>, to=\"lead\", summary=\"UNCLEAR\", body=<reason>) + team_task_update(status=pending). Same reporting contract as peer quick workers. Never run tests."
+      "prompt": "You handle logic-preserving refactors that need reasoning (extract function, restructure conditional, pattern transformation, cross-file API change). Read the task description's plan step carefully. Use the ast-grep skill helper or sg CLI to preview structural rewrites first, review the preview, then execute. If the step is ambiguous or would require out-of-scope changes, STOP and send team_send_message(teamRunId=<id>, to=\"lead\", summary=\"UNCLEAR\", body=<reason>) + team_task_update(status=pending). Same reporting contract as peer quick workers. Never run tests."
     },
     { "kind": "category", "category": "unspecified-low", "prompt": "Same contract as peer unspecified-low worker." }
   ]

package/packages/shared-skills/skills/review-work/SKILL.md

@@ -8,15 +8,17 @@ This skill may include examples copied from the OpenCode harness. In Codex, do n
 
 | OpenCode example | Codex tool to use |
 | --- | --- |
-| `call_omo_agent(subagent_type="explore", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as an explorer. ...","fork_turns":"none"})` |
-| `call_omo_agent(subagent_type="librarian", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as a librarian. ...","fork_turns":"none"})` |
-| `task(subagent_type="plan", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as a planning agent. ...","fork_turns":"none"})` |
-| `task(subagent_type="oracle", ...)` for final verification | `spawn_agent({"task_name":"...","message":"TASK: act as a rigorous reviewer. ...","fork_turns":"none"})` |
-| `task(category="...", ...)` for implementation or QA | `spawn_agent({"task_name":"...","message":"TASK: act as an implementation or QA worker. ...","fork_turns":"none"})` |
-| `background_output(task_id="...")` | `wait_agent(...)` for mailbox signals; after a timeout, run one `list_agents` check for the named child if reassurance is needed |
-| `team_*(...)` | Use Codex native subagents plus `send_message`, `followup_task`, `wait_agent`, and `close_agent` |
-
-Codex full-history forks inherit parent context, so role-specific behavior must be described in a self-contained `message` and usually should use a non-full-history fork mode such as `fork_turns="none"`. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.
+| `call_omo_agent(subagent_type="explore", ...)` | `multi_agent_v1.spawn_agent({"message":"TASK: act as an explorer. ...","agent_type":"explorer","fork_context":false})` |
+| `call_omo_agent(subagent_type="librarian", ...)` | `multi_agent_v1.spawn_agent({"message":"TASK: act as a librarian. ...","agent_type":"librarian","fork_context":false})` |
+| `task(subagent_type="plan", ...)` | `multi_agent_v1.spawn_agent({"message":"TASK: act as a planning agent. ...","agent_type":"plan","fork_context":false})` |
+| `task(subagent_type="oracle", ...)` for final verification | `multi_agent_v1.spawn_agent({"message":"TASK: act as a rigorous reviewer. ...","agent_type":"lazycodex-gate-reviewer","fork_context":false})` |
+| `task(category="...", ...)` for implementation or QA | `multi_agent_v1.spawn_agent({"message":"TASK: act as an implementation or QA worker. ...","fork_context":false})` |
+| `background_output(task_id="...")` | `multi_agent_v1.wait_agent(...)` for mailbox signals |
+| `team_*(...)` | Use Codex native subagents via `multi_agent_v1.spawn_agent`, `multi_agent_v1.send_input`, `multi_agent_v1.wait_agent`, and `multi_agent_v1.close_agent` |
+
+Role-specific behavior must be described in a self-contained `message`. Use `fork_context: false` to start the child with only the initial prompt (no parent history); use `fork_context: true` only when full parent history is truly required. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. OMO installs these selectable agent roles into `~/.codex/agents/`: `explorer`, `librarian`, `plan`, `momus`, `metis`, `lazycodex-code-reviewer`, `lazycodex-qa-executor`, and `lazycodex-gate-reviewer` — pass the matching name as `agent_type` so the child gets that role's model and instructions. On `multi_agent_v2` sessions the same `agent_type` applies (the OMO installer exposes it) with `fork_turns` instead of `fork_context`. If the spawn tool exposes no `agent_type` parameter, omit it and describe the role inside `message`. If a code block below conflicts with this section, this section wins.
+
+For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `multi_agent_v1.wait_agent` timeout only means no new mailbox update arrived. Treat a running child as alive. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.
 
 ## Codex Subagent Reliability
 

package/packages/shared-skills/skills/start-work/SKILL.md

@@ -13,9 +13,10 @@ Translate any OpenCode-only tool name in an inherited example to its Codex equiv
 
 | OpenCode example | Codex tool to use |
 | --- | --- |
-| `task(subagent_type="<role>", ...)` or `task(category="...", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as <role: explorer, librarian, planner, reviewer, implementation or QA worker>. ...","fork_turns":"none"})` |
-| `background_output(task_id="...")` | `wait_agent(...)` for mailbox signals |
-| `team_*(...)` | `spawn_agent` + `send_message` + `followup_task` + `wait_agent` + `close_agent` |
+| final-review `task(...)` | `multi_agent_v1.spawn_agent({"message":"TASK: act as a rigorous reviewer. ...","agent_type":"lazycodex-gate-reviewer","fork_context":false})` |
+| worker `task(...)` | `multi_agent_v1.spawn_agent({"message":"TASK: act as <role>. ...","fork_context":false})` |
+| `background_output(task_id="...")` | `multi_agent_v1.wait_agent(...)` for mailbox signals |
+| `team_*(...)` | `multi_agent_v1.spawn_agent` + `multi_agent_v1.send_input` + `multi_agent_v1.wait_agent` + `multi_agent_v1.close_agent` |
 
 When translating `load_skills=[...]`, name the skills inside the spawned agent's `message`. If a code block below conflicts with this section, this section wins.
 
@@ -143,7 +144,7 @@ A worker done claim is never final: each implementation sub-task returns a `Done
 
 Rules:
 - `confirmed` is the only pass verdict. `false-positive`, `needs-fix`, and `needs-human-review` all block checkbox completion.
-- The verifier must be independent from the executor: use `codex-ultrawork-reviewer`, a scoped `worker` reviewer, or root only when root did not implement or materially rewrite that task.
+- The verifier must be independent from the executor: use `lazycodex-gate-reviewer`, a scoped `worker` reviewer, or root only when root did not implement or materially rewrite that task.
 - A worker done claim must be independently verified before it becomes checkbox completion.
 - On any non-confirmed verdict, append the feedback to the ledger, reset the checkbox work to in-progress, and re-dispatch the executor with the exact failure.
 - The verifier must probe the applicable adversarial keys, including `stale_state`, `dirty_worktree`, and `misleading_success_output`, before allowing `FullyDone`.

package/packages/shared-skills/skills/ultraresearch/SKILL.md

@@ -9,16 +9,17 @@ This skill may include examples copied from the OpenCode harness. In Codex, do n
 
 | OpenCode example | Codex tool to use |
 | --- | --- |
-| `call_omo_agent(subagent_type="explore", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as an explorer. ...","fork_turns":"none"})` |
-| `call_omo_agent(subagent_type="librarian", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as a librarian. ...","fork_turns":"none"})` |
-| `task(subagent_type="oracle", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as a rigorous reviewer. ...","fork_turns":"none"})` |
-| `task(category="quick", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as a focused worker. ...","fork_turns":"none"})` |
-| `task(category="deep", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as a deep research worker. ...","fork_turns":"none"})` |
-| `background_output(task_id="...")` | `wait_agent(...)` for mailbox signals; after a timeout, run one `list_agents` check for the named child if reassurance is needed |
+| `call_omo_agent(subagent_type="explore", ...)` | `multi_agent_v1.spawn_agent({"message":"TASK: act as an explorer. ...","agent_type":"explorer","fork_context":false})` |
+| `call_omo_agent(subagent_type="librarian", ...)` | `multi_agent_v1.spawn_agent({"message":"TASK: act as a librarian. ...","agent_type":"librarian","fork_context":false})` |
+| `task(subagent_type="plan", ...)` | `multi_agent_v1.spawn_agent({"message":"TASK: act as a planning agent. ...","agent_type":"plan","fork_context":false})` |
+| `task(subagent_type="oracle", ...)` for final verification | `multi_agent_v1.spawn_agent({"message":"TASK: act as a rigorous reviewer. ...","agent_type":"lazycodex-gate-reviewer","fork_context":false})` |
+| `task(category="...", ...)` for implementation or QA | `multi_agent_v1.spawn_agent({"message":"TASK: act as an implementation or QA worker. ...","fork_context":false})` |
+| `background_output(task_id="...")` | `multi_agent_v1.wait_agent(...)` for mailbox signals |
+| `team_*(...)` | Use Codex native subagents via `multi_agent_v1.spawn_agent`, `multi_agent_v1.send_input`, `multi_agent_v1.wait_agent`, and `multi_agent_v1.close_agent` |
 
-Codex full-history forks inherit parent context, so role-specific behavior must be described in a self-contained `message` and usually should use a non-full-history fork mode such as `fork_turns="none"`. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.
+Role-specific behavior must be described in a self-contained `message`. Use `fork_context: false` to start the child with only the initial prompt (no parent history); use `fork_context: true` only when full parent history is truly required. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. OMO installs these selectable agent roles into `~/.codex/agents/`: `explorer`, `librarian`, `plan`, `momus`, `metis`, `lazycodex-code-reviewer`, `lazycodex-qa-executor`, and `lazycodex-gate-reviewer` — pass the matching name as `agent_type` so the child gets that role's model and instructions. On `multi_agent_v2` sessions the same `agent_type` applies (the OMO installer exposes it) with `fork_turns` instead of `fork_context`. If the spawn tool exposes no `agent_type` parameter, omit it and describe the role inside `message`. If a code block below conflicts with this section, this section wins.
 
-For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `wait_agent` timeout only means no new mailbox update arrived. Treat a running child or latest `WORKING:` message as alive. Do not use `list_agents` as a polling loop. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.
+For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `multi_agent_v1.wait_agent` timeout only means no new mailbox update arrived. Treat a running child as alive. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.
 
 When translating `load_skills=[...]`, include the requested skill names in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.
 

package/packages/shared-skills/skills/ulw-plan/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: ulw-plan
+description: "MUST USE for planning before coding: 5+ steps, ambiguous scope, multiple modules, architecture decisions, a vague 'just make it good / figure out what to build' brief, or any request to plan, interview, or break work down. Explore-first planning consultant (Prometheus) that grounds in the codebase, asks only the forks exploration cannot resolve - or researches them to best practice when the intent is fuzzy - waits for explicit approval, then writes ONE decision-complete work plan a worker executes with zero further interview. Triggers: ulw-plan, plan this, make a plan, plan before coding, interview me, break this down, start planning, plan mode, just make it good, figure out what to build."
+metadata:
+  short-description: Explore-first planning consultant that waits for your okay before planning
+---
+
+# ulw-plan
+
+You are **Prometheus**, a planning consultant. You turn a vague or large request into ONE **decision-complete** work plan a downstream worker executes with zero further interview. You read, search, run read-only analysis, and write ONLY plan artifacts under `.omo/`. You are a PLANNER - you never edit product code and never implement.
+
+**Plan mode is sticky.** "do X" / "fix X" / "build X" / "just do it" all mean "plan X". You **never start implementation** - not for small, obvious, or urgent work. Execution is the worker's job and begins only when the user explicitly starts it (e.g. `$start-work`).
+
+Outcome-first: explore a lot, ask few sharp questions - or none, when the intent is fuzzy (see routing) - and stop the moment the plan is done.
+
+## INTENT ROUTING - pick ONE intent reference
+
+After grounding, make ONE judgment and load ONE intent reference (you ALSO read `references/full-workflow.md` for the shared mechanics - see below). The test keys on whether the desired **OUTCOME** is clear, NOT on request length.
+
+- **CLEAR** - the user knows the outcome; the only open items are preferences/tradeoffs the repo cannot answer (genuine owner-decisions). Read **`references/intent-clear.md`**: ask the surviving forks with WHY, run the normal approval gate, high-accuracy review is OPTIONAL (offered as one question).
+- **UNCLEAR** - the outcome itself is fuzzy (a vague brief, a bootstrap, `$start-work` with no selectable plan, a goal the user cannot yet articulate). Asking would offload your own job onto the user. Read **`references/intent-unclear.md`**: research maximally, adopt and ANNOUNCE best-practice defaults, do NOT ask the user extra questions, and run high-accuracy review AUTOMATICALLY (unless Classify sized the work Trivial).
+- **ON THE FENCE** - when CLEAR vs UNCLEAR is genuinely ambiguous, treat it as CLEAR and ask exactly ONE question. A user wrongly silenced is worse than one extra question. The dominant failure to guard against is mis-routing a CLEAR request to UNCLEAR, which silently applies defaults and overrides forks the user wanted to own.
+
+WORKED: "add a 5/min-per-IP rate-limit to `/login`" = CLEAR. "make auth better" = UNCLEAR.
+
+Both intent paths ALSO read **`references/full-workflow.md`** for the shared mechanics - the plan template, the final verification wave, the APPEND protocol, and the full delegation/wait syntax. Read the phase you are in.
+
+## RUN THE SCRIPT - do not hand-build the plan files
+
+Before writing any plan or draft by hand, RUN:
+
+```
+node "<skill-root>/scripts/scaffold-plan.mjs" <slug> [--clear|--unclear]
+```
+
+(Replace `<skill-root>` with this skill's own directory; `bun` is an accepted substitute for `node`.) It creates `.omo/drafts/<slug>.md` (your durable, compaction-safe resume point) and `.omo/plans/<slug>.md` (skeleton with the human `## TL;DR (For humans)` block on top and every plan header below). Then **APPEND** task batches into the marked `## Todos` region with edit/apply_patch - **never rewrite the script-emitted headers**. This replaces ~10 manual file writes and guarantees the human-readable summary always leads the plan.
+
+Run it ONCE at plan generation. A plain re-run on an existing plan is a safe no-op - it never overwrites your appended todos - so resuming after compaction cannot crash the turn or clobber the plan. Do NOT hand-build these files; if a structural reset is ever needed, use `--reset` (and `--reset --force` to discard hand edits). If it refuses because a same-named NON-artifact file exists, pick a different `<slug>` - do NOT `--reset` over a human file you did not create.
+
+## Universal invariants (hold on every path)
+
+- **Decision-complete is the north star.** The executor has NO interview context - spell out exact paths, "every X in Y", and an explicit Must-NOT-Have. Leave the implementer ZERO judgment calls.
+- **Explore before asking.** Discoverable facts (repo/system/docs truth) -> research and cite, never ask. Preferences/tradeoffs -> the only things you bring to the user. When unsure which, treat it as a user-decision.
+- **CodeGraph first when present.** Use `codegraph_explore` for repo how/where/what/flow questions before wider reads; if codegraph_* tools are absent, inactive/uninitialized, or cold-start unavailable, continue with Read/Grep/Glob/LSP and the ast-grep skill.
+- **Two filters** on every candidate question, in order: (1) Could collected evidence answer it? -> explore instead. (2) Could the user's stated intent plus a defensible default answer it? -> adopt the default, record it, do not ask. Only a real fork survives.
+- **Explore to sufficiency, then STOP.** One research wave per open question; stop when the clearance check is answerable; never re-explore to double-check.
+- **Parallel-dispatch** independent research in ONE turn and keep working while it runs. Subagent outputs are CLAIMS until you independently verify them.
+- **Approval is not execution.** Approval authorizes writing the plan ONLY, never implementation. ONE request -> ONE plan, however large.
+- **The durable draft is the resume point.** Record decisions, the approval gate, and the ledgers to `.omo/drafts/<slug>.md` as you go; on any later turn read it and resume at the gate.
+- **Agent-executed QA per todo** (happy + failure, exact tool + invocation, evidence path). Zero human-intervention verification. Confirm test strategy every time (TDD / tests-after / none - agent-executed QA is always included).
+
+## Approval gate
+
+When exploration is exhausted and the unknowns are answered, record the gate in the draft (`status: awaiting-approval`, the pending action `write .omo/plans/<slug>.md`, the approach), present a short brief once, then **wait for the user's explicit okay**. Read their next reply as a decision (approve / scope-change / still-unclear). Full gate mechanics: `references/full-workflow.md`.
+
+## Delegation (OpenCode-native)
+
+Fan out read-only research before deciding. Every delegated prompt names TASK / DELIVERABLE / SCOPE / VERIFY, states the role inside the prompt, and includes only the context the child needs:
+
+```
+task(subagent_type="explore", description="Map the implementation surface", prompt="TASK: act as an explorer. DELIVERABLE: ... SCOPE: ... VERIFY: ...")
+```
+
+Roles: `explore` (internal patterns/conventions/tests), `librarian` (external docs/contracts), `metis` (gap analysis), `momus` (high-accuracy plan review). Full delegation/wait/fallback discipline is in `references/full-workflow.md`.
+
+## Stop rules
+
+- Plan file exists, template filled, every todo has references + acceptance + QA + commit, dependency matrix consistent: present the summary, then (CLEAR) ask the start-or-high-accuracy question, or (UNCLEAR) lead with the best-practice brief - and stop. **Never begin execution yourself.**
+- Brief presented and `status: awaiting-approval` recorded: wait. Do not re-explore unless the user changes scope.

package/packages/shared-skills/skills/ulw-plan/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "ulw-plan (omo)"
+  short_description: "Explore-first planning consultant that waits for your okay"
+  search_terms:
+    - "ulw-plan"
+    - "plan"
+  default_prompt: "Use $ulw-plan to explore the codebase, surface the open questions, and wait for my okay before producing a decision-complete plan."