@webpresso/codex-plugin 3.1.3

package/.codex-plugin/plugin.json

@@ -0,0 +1,32 @@
+{
+  "name": "agent-kit",
+  "version": "3.1.3",
+  "description": "Webpresso agent-kit: blueprints, skills, hooks, and MCP server",
+  "author": {
+    "name": "Webpresso",
+    "url": "https://github.com/webpresso"
+  },
+  "homepage": "https://github.com/webpresso/agent-kit#readme",
+  "repository": "https://github.com/webpresso/agent-kit",
+  "license": "Elastic-2.0",
+  "keywords": [
+    "agent",
+    "blueprint",
+    "mcp",
+    "skills",
+    "developer-tools"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "hooks": "./hooks/hooks.json",
+  "interface": {
+    "displayName": "Webpresso agent-kit",
+    "shortDescription": "Blueprints, skills, hooks, and MCP tools.",
+    "developerName": "Webpresso",
+    "category": "Development",
+    "capabilities": [
+      "Read",
+      "Write"
+    ]
+  }
+}

package/.mcp.json

@@ -0,0 +1,6 @@
+{
+  "webpresso": {
+    "command": "${PLUGIN_ROOT}/bin/wp",
+    "args": ["mcp"]
+  }
+}

package/LICENSE

@@ -0,0 +1,104 @@
+Elastic License 2.0
+===================
+
+Copyright (c) 2026 Webpresso, Inc.
+
+Acceptance
+----------
+
+By using the software, you agree to all of the terms and conditions below.
+
+Copyright License
+-----------------
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject
+to the limitations and conditions below.
+
+Limitations
+-----------
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key
+functionality in the software, and you may not remove or obscure any
+functionality in the software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other
+notices of the licensor in the software. Any use of the licensor's trademarks
+is subject to applicable law.
+
+Patents
+-------
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software.
+
+If you or your company make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license for the software
+granted under these terms ends immediately. If your company makes such a claim,
+your patent license ends immediately for work on behalf of your company.
+
+Notices
+-------
+
+You must ensure that anyone who gets a copy of any part of the software from
+you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+No Other Rights
+---------------
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+Termination
+-----------
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+No Liability
+------------
+
+As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.
+
+Definitions
+-----------
+
+The licensor is the entity offering these terms, and the software is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+you refers to the individual or entity agreeing to these terms.
+
+your company is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+control means ownership of substantially all the assets of an entity, or the
+power to direct its management and policies by vote, contract, or otherwise.
+Control can be direct or indirect.
+
+your licenses are all the licenses granted to you for the software under these
+terms.
+
+use means anything you do with the software requiring one of your licenses.
+
+trademark means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,25 @@
+# @webpresso/codex-plugin
+
+`@webpresso/codex-plugin` is the Codex CLI host adapter package for Agent Kit.
+It ships the Codex plugin manifest, packaged skills, hook metadata, a
+package-local MCP manifest, and a package-local `bin/wp` shim that forwards to
+an Agent Kit `wp` CLI resolved at runtime.
+
+This adapter does not declare `@webpresso/agent-kit` as a package dependency.
+Its package-local `bin/wp` shim resolves the CLI in this order:
+
+1. `WEBPRESSO_WP_BIN`, when set to an executable file.
+2. The source-checkout root `../../bin/wp`, for local adapter development.
+3. `@webpresso/agent-kit/bin/wp`, when an integrator installed the root package
+   alongside this adapter.
+4. `wp` on `PATH`.
+
+If none of those candidates is available, install or update the root package
+through `wp setup`, `wp update`, or your package manager, or set
+`WEBPRESSO_WP_BIN` to the desired executable. The shim preserves
+`WP_SKIP_UPDATE_CHECK=1` by default for host MCP invocations.
+
+The root `@webpresso/agent-kit` package is CLI/core only: it ships `wp`, MCP
+tools, audits, blueprints, session memory, docs, and catalog sources, but it
+does not ship this Codex payload from the root package. Use this adapter when
+you need the Codex-native plugin delivery surface.

package/bin/wp

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { accessSync, constants, realpathSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, delimiter, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const require = createRequire(import.meta.url);
+const shimPath = fileURLToPath(import.meta.url);
+const shimDir = dirname(shimPath);
+const adapterRoot = dirname(shimDir);
+
+function isExecutableFile(candidate) {
+  try {
+    const stat = statSync(candidate);
+    if (!stat.isFile()) return false;
+    accessSync(candidate, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function sameFile(a, b) {
+  try {
+    return realpathSync(a) === realpathSync(b);
+  } catch {
+    return false;
+  }
+}
+
+function pathWpCandidates() {
+  return (process.env.PATH ?? "")
+    .split(delimiter)
+    .filter(Boolean)
+    .map((entry) => join(entry, process.platform === "win32" ? "wp.cmd" : "wp"));
+}
+
+function resolveAgentKitPackageWp() {
+  try {
+    const packageJsonPath = require.resolve("@webpresso/agent-kit/package.json");
+    return join(dirname(packageJsonPath), "bin", "wp");
+  } catch {
+    return undefined;
+  }
+}
+
+function resolveAgentKitWp() {
+  const explicitPath = process.env.WEBPRESSO_WP_BIN;
+  if (explicitPath) {
+    if (isExecutableFile(explicitPath)) return explicitPath;
+    throw new Error(
+      `WEBPRESSO_WP_BIN points to ${explicitPath}, but that file is not executable. ` +
+        "Set WEBPRESSO_WP_BIN to a valid wp executable, install/update @webpresso/agent-kit, or run wp setup.",
+    );
+  }
+
+  const candidates = [
+    join(adapterRoot, "..", "..", "bin", "wp"),
+    resolveAgentKitPackageWp(),
+    ...pathWpCandidates(),
+  ].filter(Boolean);
+
+  for (const candidate of candidates) {
+    if (isExecutableFile(candidate) && !sameFile(candidate, shimPath)) {
+      return candidate;
+    }
+  }
+
+  throw new Error(
+    "Unable to locate the Webpresso wp CLI. Install or update @webpresso/agent-kit, run wp setup, " +
+      "set WEBPRESSO_WP_BIN to the wp executable, or ensure wp is available on PATH.",
+  );
+}
+
+const result = spawnSync(resolveAgentKitWp(), process.argv.slice(2), {
+  stdio: "inherit",
+  env: {
+    ...process.env,
+    WP_SKIP_UPDATE_CHECK: process.env.WP_SKIP_UPDATE_CHECK ?? "1",
+  },
+});
+
+if (result.error) {
+  throw result.error;
+}
+
+process.exit(result.status ?? (result.signal ? 1 : 0));

package/hooks/hooks.json

@@ -0,0 +1,3 @@
+{
+  "hooks": {}
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@webpresso/codex-plugin",
+  "version": "3.1.3",
+  "private": false,
+  "description": "Codex plugin adapter for Webpresso agent-kit skills, hooks, and MCP runtime.",
+  "homepage": "https://github.com/webpresso/agent-kit#readme",
+  "bugs": {
+    "url": "https://github.com/webpresso/agent-kit/issues"
+  },
+  "license": "Elastic-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/webpresso/agent-kit.git",
+    "directory": "packages/codex-plugin"
+  },
+  "files": [
+    ".codex-plugin",
+    ".mcp.json",
+    "skills",
+    "hooks",
+    "bin/wp",
+    "LICENSE",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}

package/skills/best-practice-research/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: best-practice-research
+description: "Official/upstream best-practice research wrapper with bounded evidence and dated citations."
+argument-hint: "<technology|decision|practice question>"
+---
+
+# Best-Practice Research
+
+Use this skill when a task depends on current external best practices, version-aware guidance, standards, official recommendations, or upstream behavior. This is a workflow wrapper: it routes evidence gathering and synthesis; it is not a new research authority and it does not replace `researcher`.
+
+## Purpose
+
+Produce a cited, reusable best-practice answer or handoff that separates current external evidence from repo-local facts and dependency-selection decisions.
+
+## Activate When
+
+- The user asks for best practices, recommended approach, current guidance, official recommendations, standards, or version-aware external behavior.
+- `$ralplan`, `$deep-interview`, `$team`, or another workflow needs current external evidence before planning or execution can be correct.
+- The task involves an already chosen technology and needs authoritative usage guidance, migration notes, API behavior, lifecycle rules, or current safety guidance.
+
+## Do Not Activate When
+
+- The answer is fully repo-local; use `explore` for codebase facts.
+- The main question is whether to adopt, replace, upgrade, or compare dependencies; use `dependency-expert`.
+- The user only needs implementation against already-grounded requirements; use `executor`, `$ralph`, or `$team` as appropriate.
+- The task can be answered from stable local project conventions without current external lookup.
+
+## Specialist Routing
+
+1. Use `explore` first for brownfield facts: current code usage, local constraints, versions, config, and integration points.
+2. Use `researcher` for official/upstream docs, release notes, standards, migration guides, source-backed examples, and current best-practice evidence for an already chosen technology.
+3. Use `dependency-expert` only for adoption/upgrade/replacement/comparison decisions.
+4. Return to the caller with explicit evidence, uncertainty, and any implementation handoff constraints.
+
+## Source-Quality Rules
+
+- Prefer official documentation, upstream source, release notes, changelogs, standards, and maintainer guidance.
+- Include source URLs for material claims.
+- State date/version context for current best-practice claims.
+- Label third-party summaries as supplemental; do not use them before official/upstream sources.
+- Flag stale, conflicting, undocumented, or version-mismatched evidence.
+- Do not over-fetch: gather the smallest evidence set that can support the decision.
+
+## Workflow
+
+1. Classify the question: conceptual best practice, implementation guidance, migration/version guidance, standards/compliance guidance, or mixed local + external guidance.
+2. Gather repo-local facts with `explore` when local usage or constraints affect the answer.
+3. Gather external evidence with `researcher` when current or version-aware practice affects correctness.
+4. Synthesize a concise answer with source quality, version/date context, caveats, and an implementation or planning handoff.
+5. Stop when the answer is grounded enough for the caller; otherwise report the exact blocker or specialist handoff needed.
+
+## Output Contract
+
+```md
+## Best-Practice Research: <question>
+
+### Direct Recommendation
+
+<actionable guidance or decision support>
+
+### Evidence Used
+
+- Official/upstream: <source URL> — <what it establishes>
+- Supplemental, if any: <source URL> — <why it is secondary>
+
+### Version / Date Context
+
+<versions, dates, release channels, or unknowns>
+
+### Repo-Local Context
+
+<facts from explore, or "not needed">
+
+### Boundaries / Non-goals
+
+<what this research does not decide>
+
+### Handoff
+
+<planning/execution/test implications>
+```
+
+## Stop Rules
+
+- Stop after a source-backed recommendation is reusable by the caller.
+- Stop and route upward if the task becomes dependency comparison, broad architecture, or implementation.
+- Do not continue researching when remaining work would only polish wording rather than change the recommendation.
+
+Task: {{ARGUMENTS}}

package/skills/browse/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: browse
+description: "Browser/page inspection via Webpresso Playwright: inspect DOM, console, network basics, screenshots, and findings."
+license: MIT
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+---
+
+# Browse
+
+Use `wp browser doctor` first if browser availability is unknown; if it reports a missing browser, run `wp browser ensure chromium`. Prefer repo-local preview or dev-server URLs; if none are discoverable, ask for a URL.
+
+## Read-only inspection
+
+The `allowed-tools` frontmatter is an audited disclosure for supported hosts;
+pretool-guard remains the enforced mutation backstop when a host does not prove
+skill-frontmatter enforcement.
+
+1. Identify the URL and whether headed or headless mode is needed.
+2. Use `wp browser open <url> --json` for a lightweight smoke snapshot, or a project Playwright test for deeper flows.
+3. Report URL, title, status evidence, console/page errors when available, and any screenshots/artifacts.
+4. Do not mutate app data unless the user explicitly asks for a mutating browser flow.

package/skills/claude/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: claude
+description: "Claude CLI outside-voice wrapper for review, adversarial challenge, or consultation from non-Claude hosts."
+license: MIT
+---
+
+# Claude outside voice
+
+Use when a non-Claude host needs Claude to review a diff, challenge a plan, or answer a focused repo question. Keep it bounded/read-only unless asked otherwise, and report Claude output as advice, not verified fact.
+
+## Auth check
+
+Use local Claude CLI login directly; do not route through Anthropic API-key env vars.
+
+```bash
+AUTH_STATUS_FILE=$(mktemp -t wp-claude-auth.XXXXXX)
+trap 'rm -f "$AUTH_STATUS_FILE"' EXIT
+if ! claude auth status --json >"$AUTH_STATUS_FILE" 2>/dev/null; then
+  if ! claude auth status >"$AUTH_STATUS_FILE" 2>/dev/null; then
+    echo "CLAUDE_AUTH=missing: run claude auth login with the intended Claude Max account"
+    exit 1
+  fi
+fi
+if grep -E '"(authenticated|loggedIn|success)"[[:space:]]*:[[:space:]]*true' "$AUTH_STATUS_FILE" >/dev/null; then
+  echo "CLAUDE_AUTH=cli-login"
+else
+  echo "CLAUDE_AUTH=missing: claude auth status did not report a recognized Claude CLI login"
+  exit 1
+fi
+```
+
+## Portable prompt file
+
+Use a suffix-free `mktemp -t` pattern so macOS and Linux both work:
+
+```bash
+PROMPT_FILE=$(mktemp -t wp-claude-review.XXXXXX)
+trap 'rm -f "$PROMPT_FILE"' EXIT
+```
+
+## Modes
+
+### Review
+
+Use single-file / single-question first for any non-trivial diff. Do not send a whole PR unless it already fits within the bounded payload below.
+
+**Model policy:** default to `sonnet` via `CLAUDE_REVIEW_MODEL=${CLAUDE_REVIEW_MODEL:-sonnet}`. Override to `opus` only when the review is approval evidence or the user explicitly asks for Opus. Never use `fable` for Claude outside-voice review. Any review used as blueprint approval evidence MUST run with Claude Opus and record `"model": "opus"`.
+
+#### Bounded prompt payload
+
+Always include:
+
+- current branch and base branch
+- `git diff --stat`
+- changed file list
+- one targeted file diff or one narrow snippet/hunk only, capped to a fixed size
+
+Prefer ~12 KB or ~200 lines per call. Split large reviews instead of raising the cap.
+
+```bash
+BASE_BRANCH=${BASE_BRANCH:-origin/main}
+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+TARGET_FILE=${TARGET_FILE:?set TARGET_FILE to one changed file}
+
+{
+  printf 'Outside review mode: focused diff review\n'
+  printf 'Base branch: %s\nCurrent branch: %s\n\n' "$BASE_BRANCH" "$CURRENT_BRANCH"
+  printf 'git diff --stat %s...HEAD\n' "$BASE_BRANCH"
+  git diff --stat "$BASE_BRANCH"...HEAD
+  printf '\nChanged files:\n'
+  git diff --name-only "$BASE_BRANCH"...HEAD
+  printf '\nTarget file: %s\n' "$TARGET_FILE"
+  printf 'Bounded target diff (max 12000 bytes):\n'
+  git diff --unified=3 "$BASE_BRANCH"...HEAD -- "$TARGET_FILE" | \
+    head -c 12000
+  printf '\n\nQuestion: Identify the highest-signal correctness, security, data-loss, or maintainability risk in %s. Quote only the smallest relevant excerpt. If context is insufficient, answer INSUFFICIENT_CONTEXT.\n' "$TARGET_FILE"
+} >"$PROMPT_FILE"
+```
+
+#### Timed Claude artifact wrapper
+
+Run Claude through the bounded Python wrapper. Use `claude --print --model "$CLAUDE_REVIEW_MODEL"`; do not recommend `--bare` for this path. Do not add artificial budget caps unless the user requested one. The wrapper is deterministic:
+
+- it defaults to `CLAUDE_REVIEW_MODEL=sonnet` and allows only `opus` or `sonnet`
+- it never passes `--tools ""`, because Claude's variadic `--tools` option can swallow the prompt
+- it captures stdout and stderr for preflight and the full review
+- it writes the artifact on success, non-zero exit, or timeout
+- it runs one full review attempt only; retry only if you change the command shape for a specific diagnosed reason
+
+Preflight must be only the tiny `claude-ok` prompt with the selected model. Do not use the real review prompt for preflight.
+
+```bash
+CLAUDE_REVIEW_MODEL=${CLAUDE_REVIEW_MODEL:-sonnet}
+CLAUDE_REVIEW_EFFORT=${CLAUDE_REVIEW_EFFORT:-medium}
+CLAUDE_REVIEW_PREFLIGHT_TIMEOUT_SECONDS=${CLAUDE_REVIEW_PREFLIGHT_TIMEOUT_SECONDS:-30}
+CLAUDE_REVIEW_IDLE_TIMEOUT_SECONDS=${CLAUDE_REVIEW_IDLE_TIMEOUT_SECONDS:-180}
+CLAUDE_REVIEW_ARTIFACT=${CLAUDE_REVIEW_ARTIFACT:-"$(pwd)/.webpresso/claude-review-$(date +%Y%m%dT%H%M%S).json"}
+export CLAUDE_REVIEW_MODEL CLAUDE_REVIEW_EFFORT CLAUDE_REVIEW_PREFLIGHT_TIMEOUT_SECONDS CLAUDE_REVIEW_IDLE_TIMEOUT_SECONDS CLAUDE_REVIEW_ARTIFACT
+mkdir -p "$(dirname "$CLAUDE_REVIEW_ARTIFACT")"
+
+python3 - "$PROMPT_FILE" "$CLAUDE_REVIEW_ARTIFACT" <<'PY'
+from __future__ import annotations
+
+import json, os, subprocess, sys, time
+from pathlib import Path
+
+prompt_path = Path(sys.argv[1])
+artifact_path = Path(sys.argv[2])
+model = os.environ.get("CLAUDE_REVIEW_MODEL", "sonnet")
+effort = os.environ.get("CLAUDE_REVIEW_EFFORT", "medium")
+preflight_timeout = float(os.environ.get("CLAUDE_REVIEW_PREFLIGHT_TIMEOUT_SECONDS", "30"))
+review_idle_timeout = float(os.environ.get("CLAUDE_REVIEW_IDLE_TIMEOUT_SECONDS", "180"))
+if model not in {"opus", "sonnet"}: raise SystemExit("CLAUDE_REVIEW_MODEL must be one of: opus, sonnet")
+if effort not in {"medium", "high"}: raise SystemExit("CLAUDE_REVIEW_EFFORT must be one of: medium, high")
+if preflight_timeout <= 0 or review_idle_timeout <= 0: raise SystemExit("Claude timeout values must be positive numbers")
+
+
+def utc_now() -> str: return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+artifact: dict[str, object] = {"tool": "claude-outside-voice", "model": model, "effort": effort, "startedAt": utc_now(), "artifactPath": str(artifact_path), "runs": []}
+
+
+def write_artifact(status: str, exit_code: int) -> None:
+    artifact.update({"finishedAt": utc_now(), "status": status, "exitCode": exit_code})
+    artifact_path.parent.mkdir(parents=True, exist_ok=True)
+    artifact_path.write_text(json.dumps(artifact, indent=2) + "\n", encoding="utf-8")
+
+
+def as_text(value: str | bytes | None) -> str:
+    return value.decode(errors="replace") if isinstance(value, bytes) else (value or "")
+
+
+def run_claude(stage: str, prompt: str, timeout_seconds: float, timeout_kind: str) -> int:
+    command = ["claude", "--print", "--model", model, "--effort", effort, prompt]
+    started = last_progress = time.monotonic()
+    last_progress_at = utc_now()
+    out = err = ""
+    record: dict[str, object] = {"stage": stage, "command": [*command[:-1], "<prompt>"], "timeoutKind": timeout_kind, "timeoutSeconds": timeout_seconds, "idleTimeoutSeconds": timeout_seconds if timeout_kind == "idle" else None, "startedAt": last_progress_at}
+    try:
+        process = subprocess.Popen(command, text=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+        while True:
+            try:
+                new_out, new_err = process.communicate(timeout=0.5)
+                out, err = as_text(new_out), as_text(new_err)
+                code = int(process.returncode)
+                timed_out = False
+                break
+            except subprocess.TimeoutExpired as exc:
+                new_out, new_err = as_text(exc.stdout), as_text(exc.stderr)
+                if new_out != out or new_err != err:
+                    out, err, last_progress, last_progress_at = new_out, new_err, time.monotonic(), utc_now()
+                reference = last_progress if timeout_kind == "idle" else started
+                if time.monotonic() - reference > timeout_seconds:
+                    process.kill()
+                    final_out, final_err = process.communicate()
+                    out += as_text(final_out)[len(out):]
+                    err += as_text(final_err)[len(err):]
+                    code, timed_out = 124, True
+                    break
+    except OSError as exc:
+        out, err, code, timed_out = "", str(exc), 1, False
+    record.update({"exitCode": code, "timedOut": timed_out, "stdout": out, "stderr": err, "finishedAt": utc_now(), "lastProgressAt": last_progress_at, "elapsedSeconds": round(time.monotonic() - started, 3)})
+    artifact["runs"].append(record)
+    return code
+
+preflight_code = run_claude("preflight", "claude-ok", preflight_timeout, "wall-clock")
+if preflight_code != 0:
+    write_artifact("preflight-timeout" if preflight_code == 124 else "preflight-failed", preflight_code)
+    print(f"CLAUDE_REVIEW_PREFLIGHT_EXIT={preflight_code}", file=sys.stderr)
+    print(f"CLAUDE_REVIEW_ARTIFACT={artifact_path}", file=sys.stderr)
+    raise SystemExit(preflight_code)
+review_code = run_claude("review", prompt_path.read_text(encoding="utf-8"), review_idle_timeout, "idle")
+write_artifact("idle-timeout" if review_code == 124 else ("success" if review_code == 0 else "failed"), review_code)
+print(f"CLAUDE_REVIEW_EXIT={review_code}", file=sys.stderr)
+print(f"CLAUDE_REVIEW_ARTIFACT={artifact_path}", file=sys.stderr)
+raise SystemExit(review_code)
+PY
+```
+
+After the wrapper exits, verify both the exit code and artifact path before summarizing Claude's raw output:
+
+```bash
+test -f "$CLAUDE_REVIEW_ARTIFACT" || {
+  echo "CLAUDE_REVIEW_ARTIFACT=missing: $CLAUDE_REVIEW_ARTIFACT" >&2
+  exit 1
+}
+echo "CLAUDE_REVIEW_ARTIFACT=$CLAUDE_REVIEW_ARTIFACT"
+```
+
+#### Retry policy
+
+Do not perform blind retries. Run the full review once. Retry only after diagnosing and changing a command-shape problem; record the reason and artifact path. Do not fall back to an unbounded whole-PR prompt.
+
+Summarize findings with severity, evidence, model, artifact path, and whether you independently verified them.
+
+### Challenge
+
+Ask Claude to argue against the current plan: hidden assumptions, failure modes, missing tests, and simpler alternatives.
+
+### Consult
+
+Ask a focused repo question. Include only the necessary file paths and snippets; do not send secrets.

package/skills/codex/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: codex
+description: "Codex CLI outside-voice wrapper for code review, plan challenge, or consultation from non-Codex hosts."
+license: MIT
+---
+
+# Codex outside voice
+
+Use this skill from Claude or another non-Codex host when the user wants Codex to independently review a diff, challenge a plan, or answer a repo question. Keep Codex read-only by default and treat its answer as external advice until independently verified.
+
+## Auth check
+
+```bash
+if ! codex login status >/dev/null 2>&1; then
+  echo "CODEX_AUTH=missing: run codex login before using the codex outside-voice skill"
+  exit 1
+fi
+echo "CODEX_AUTH=ok"
+```
+
+## Portable prompt file
+
+```bash
+PROMPT_FILE=$(mktemp -t wp-codex-review.XXXXXX)
+trap 'rm -f "$PROMPT_FILE"' EXIT
+```
+
+## Modes
+
+### Review
+
+1. Capture the current branch, base branch, and `git diff --stat`.
+2. Write a concise prompt asking Codex to find correctness, security, data-loss, and maintainability risks.
+3. Run Codex non-interactively in read-only mode:
+
+```bash
+CODEX_REVIEW_EFFORT=${CODEX_REVIEW_EFFORT:-medium}
+case "$CODEX_REVIEW_EFFORT" in
+  medium|high) ;;
+  *) echo "CODEX_REVIEW_EFFORT must be one of: medium, high" >&2; exit 2 ;;
+esac
+codex exec -c model_reasoning_effort="\"$CODEX_REVIEW_EFFORT\"" --sandbox read-only --cd "$PWD" - <"$PROMPT_FILE"
+```
+
+4. Summarize findings with severity, evidence, and whether you independently verified them.
+
+### Challenge
+
+Ask Codex to argue against the current plan: hidden assumptions, failure modes, missing tests, and simpler alternatives.
+
+### Consult
+
+Ask a focused repo question. Include only the necessary file paths and snippets; do not send secrets.