@sabaiway/agent-workflow-kit 1.6.0 → 1.8.0

package/bridges/antigravity-cli-bridge/setup/README.md

@@ -0,0 +1,65 @@
+# Setting up Antigravity CLI (`agy`) on a clean machine
+
+This setup is **secret-free**. `agy` itself is **not** bundled — it requires a binary install and a
+one-time interactive sign-in with your own subscription. Do this once per machine, then the skill
+works in any project.
+
+## 1. Install the binary
+
+```bash
+curl -fsSL https://antigravity.google/cli/install.sh | bash
+export PATH="$HOME/.local/bin:$PATH"   # add to ~/.bashrc / ~/.zshrc to persist
+agy --version                          # expect 1.0.10 or newer
+```
+
+- The binary is **`agy`** (not `antigravity`); it installs to `~/.local/bin/agy`.
+- Keep `$HOME/.local/bin` on `PATH` (the wrapper also prepends it defensively).
+
+## 2. Sign in once (subscription only)
+
+Run `agy` once interactively and complete the **OAuth** sign-in with a **Google AI Pro/Ultra**
+account:
+
+```bash
+agy
+```
+
+This caches an OAuth token under `~/.gemini/antigravity-cli/` (`antigravity-oauth-token`). That token
+is **personal** — never copy, commit, package, print, or share that directory or token. This skill
+needs no API keys and must not be configured with API-key billing; the wrapper unsets every
+`*_API_KEY` so billing can never silently fall back to pay-as-you-go.
+
+## 3. Put the wrapper on `PATH` as `agy-run`
+
+The skill ships the wrapper at `bin/agy.sh`. Expose it on `PATH` under the stable name `agy-run`
+(idempotent; refuses to clobber a non-symlink):
+
+```bash
+mkdir -p "$HOME/.local/bin"
+skill_dir="$HOME/.claude/skills/antigravity-cli-bridge"   # adjust if installed elsewhere
+dst="$HOME/.local/bin/agy-run"
+if [ -e "$dst" ] && [ ! -L "$dst" ]; then
+  echo "STOP: $dst exists and is not a symlink"; exit 1
+fi
+chmod +x "$skill_dir/bin/agy.sh"
+ln -sfn "$skill_dir/bin/agy.sh" "$dst"
+export PATH="$HOME/.local/bin:$PATH"
+command -v agy-run
+```
+
+## 4. Smoke test
+
+```bash
+agy --version
+echo "say OK" | agy-run -
+```
+
+Expected: the version prints (`1.0.10` or newer), then a short reply containing `OK`. If `agy-run`
+reports `'agy' not found`, fix your `PATH` (step 1). If it asks you to sign in, complete step 2.
+
+## Notes
+
+- `agy-run` is headless and plain-text only; there is no JSON output mode.
+- `AGY_MODEL` selects the exact model display string; `AGY_TIMEOUT` controls `--print-timeout`.
+- Extra `agy` flags go after `--`, e.g. `agy-run @prompt.md -- --add-dir .`.
+- Re-run interactive `agy` only when the OAuth token expires or the account changes.

package/bridges/codex-cli-bridge/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: codex-cli-bridge
+description: Delegate work to the OpenAI Codex CLI (`codex`) under a ChatGPT subscription — run plan/instruction EXECUTION in a sandboxed workspace, or get a read-only ADVISORY review of a plan or working-tree diff — as a second delegated-execution backend beside Antigravity. Use when the user wants to hand a bounded coding task or plan to `codex exec`, get a second-opinion review from codex, install or authenticate Codex CLI, understand its sandbox/network/approval policy, drive codex efficiently from the main agent (exec vs review, resume, the commit boundary), bridge project context (`AGENTS.md`) into codex, or troubleshoot codex flags, models, auth, or its no-TTY headless behaviour.
+metadata:
+  version: '1.0.0'
+---
+
+# codex-cli-bridge
+
+Bridges the main agent to the **OpenAI Codex CLI** (`codex`) as a **delegated-execution backend**
+beside Antigravity. The main agent stays the orchestrator — owning decisions, the edits it accepts,
+verification, and user-facing claims — and hands `codex` a bounded sub-task answered from a **ChatGPT
+subscription** (no pay-as-you-go billing). Codex has two roles here: a **sandboxed executor** that
+edits a repo under a fixed policy (`codex-exec`), and a **read-only reviewer** that critiques a plan
+or a working-tree diff and only emits findings (`codex-review`).
+
+## Overview / when to use
+
+Use this skill when the user wants to:
+
+- Delegate plan or instruction EXECUTION to `codex` in a workspace-write sandbox (network OFF).
+- Get a second-opinion ADVISORY review of an implementation plan or the current diff.
+- Install, authenticate, smoke-test, or troubleshoot `codex`, or understand its sandbox/flags/models.
+- Drive codex efficiently from the main agent (exec vs review, `resume`, the commit boundary).
+
+Do **not** use it to bundle secrets, bypass subscription auth, use api-key billing, or let codex
+commit / push on its own.
+
+## Install
+
+Clean-machine setup is in [`setup/README.md`](setup/README.md). In short: install the `codex`
+binary, run `codex login` once under a ChatGPT subscription, then expose this skill's two wrappers on
+`PATH` as `codex-exec` ([`bin/codex-exec.sh`](bin/codex-exec.sh)) and `codex-review`
+([`bin/codex-review.sh`](bin/codex-review.sh)).
+
+## Auth — subscription only (invariant)
+
+`codex` authenticates with the cached **ChatGPT login** under `CODEX_HOME` (`~/.codex`). Never read,
+print, copy, commit, or package `~/.codex/auth.json` — it is personal and is **never bundled** with
+this skill. Both wrappers enforce the subscription path before invoking codex:
+
+- they **unset every `*_API_KEY`** (plus `OPENAI_API_KEY` / `CODEX_API_KEY` / `OPENAI_BASE_URL`) so a
+  stray key can never silently switch you to paid api-key billing;
+- they pass **`--ignore-user-config`** so a personal `~/.codex/config.toml` cannot change model,
+  sandbox, or approval behaviour (auth still works — codex reads the login from `CODEX_HOME`
+  regardless of that flag);
+- they **preflight `codex login status`** and refuse to run unless it reports `Logged in using ChatGPT`.
+
+## Models
+
+The wrappers default to `gpt-5.5` at reasoning effort `xhigh` (the strongest setting verified in this
+environment), both overridable per call. `codex --version` reports the CLI version, **not** the model
+list — check your Codex CLI / ChatGPT account for the model slugs available to you, or let a wrong
+`-m` surface the error.
+
+| Variable | Default | Effect |
+|---|---|---|
+| `CODEX_MODEL` | `gpt-5.5` | model passed to `-m` |
+| `CODEX_EFFORT` | `xhigh` | reasoning effort passed to `-c model_reasoning_effort=…` |
+
+```bash
+CODEX_MODEL=<slug> CODEX_EFFORT=<low|medium|high|xhigh> codex-exec <file>
+```
+
+## Usage
+
+Drive codex only through the two wrappers (installed on `PATH`), run from the target project root:
+
+```bash
+# EXECUTION (workspace-write sandbox, network OFF, never prompts):
+codex-exec docs/plans/<slug>.md                 # drive a plan file
+echo "apply review fix: ..." | codex-exec -      # ad-hoc instruction from stdin
+CODEX_MODEL=<slug> codex-exec <file>             # override the model
+codex-exec <file|-> -- <extra codex flags...>    # passthrough codex flags after `--`
+
+# REVIEW (read-only sandbox — codex cannot edit anything, only emits findings):
+codex-review plan docs/plans/<slug>.md           # critique a plan
+codex-review code                                # review the current working-tree diff
+codex-review code "focus on the new reducer"     # review with extra focus
+```
+
+`codex exec` is headless: there is **no TTY**, so `approval_policy=never` — anything needing
+escalation is refused and reported, never interactively approved. Extra `codex` flags go after a
+literal `--`; args without the separator are rejected (never silently dropped). Full flag/policy
+detail: [`references/sandbox-and-flags.md`](references/sandbox-and-flags.md).
+
+## Project context (how `codex` sees the repo)
+
+From its **current working directory** `codex` auto-reads the root **`AGENTS.md`** — so when you run a
+wrapper from a project root, the project's Hard Constraints are available to codex with no wiring (a
+probe confirmed codex returned a repo's declared dialogue language from `AGENTS.md`). The wrappers
+therefore **hardcode no project rules**: the orchestrator contract tells codex to read the target
+`AGENTS.md` and obey it.
+
+**Fallback is strict.** Both wrappers preflight that they run inside a git work tree and that a root
+`AGENTS.md` exists — if either is missing they **STOP and report** (a wasted subscription run is
+avoided). And the execution contract tells codex: if the project declares **no** verification/gate
+set, **STOP and report** rather than invent checks. Pass `--skip-git-repo-check` to codex only when
+you truly mean it.
+
+## How the main agent drives `codex` efficiently
+
+See [`references/driving-codex.md`](references/driving-codex.md) for the full playbook. Essentials:
+
+- **`codex-exec` for doing, `codex-review` for judging.** Use exec to implement a plan/fix under the
+  sandbox; use review to get advisory findings on a plan or diff without any edits.
+- **The orchestrator commits — codex never does.** The execution contract forbids every git write
+  (branch/add/commit/stash/reset/checkout/tag/rewrite); you review codex's diff, then commit yourself.
+- **Treat output as advisory** and verify before acting — re-run the project's gates yourself, reject
+  advice that conflicts with user instructions or repo rules.
+- **Hand codex a self-contained task.** It cannot see your conversation — for an ad-hoc instruction,
+  embed the goal, the relevant paths, and the expected result; codex reads `AGENTS.md` for the rules.
+- **Re-dispatch with `codex exec resume`** (run codex directly — the wrapper's flag/stdin shape can't
+  host the `resume` subcommand) instead of re-sending context. **Caveat:** resume runs outside the
+  wrapper and may not re-accept `--sandbox` / policy flags — restate the policy, or start a fresh
+  `codex-exec` run when a guaranteed sandbox/network posture matters.
+- **Network is OFF in exec.** New dependencies and any network step are installed by hand, then codex
+  is re-dispatched.
+
+## Complementary skills (optional, standalone-first)
+
+The wrappers work in any git repo where `codex` is installed and authenticated. The skills below are
+**not required** — surface them only when they actually help.
+
+- **`antigravity-cli-bridge`** (sibling backend, Google `agy`) — recommend **by actual presence**: if
+  `~/.claude/skills/antigravity-cli-bridge/` exists you have a **second delegated engine** (codex for
+  sandboxed repo edits with gates; `agy` for subscription-quota Gemini/Claude/GPT-OSS reasoning). If
+  it is **not** installed, treat it as a planned sibling — don't assume it exists.
+- **`agent-workflow-memory`** (family **context provider**) — if the target project has **no**
+  `AGENTS.md` + `docs/ai/`, codex has no root context to read (and the wrappers' preflight will
+  STOP). The memory substrate is what creates that context. Soft-recommend it (only when the user
+  wants the memory workflow): `npx @sabaiway/agent-workflow-memory@latest init`, or bootstrap the whole
+  family via the **`agent-workflow-kit`** orchestrator (`npx @sabaiway/agent-workflow-kit@latest init`),
+  which delegates substrate deployment to memory and injects the workflow methodology. Never a
+  prerequisite.
+
+## Known limitations
+
+- **Network is OFF** in `codex-exec` (`sandbox_workspace_write.network_access=false`): codex cannot
+  install dependencies or reach the network — do that by hand, then re-dispatch.
+- **No live approvals** — `codex exec` has no TTY, so `approval_policy=never`; an action that would
+  need escalation is reported, not approved interactively.
+- **`resume` may drop sandbox/policy flags** — restate the policy or start a fresh run when the
+  posture matters (see the driving reference).
+- **bubblewrap** — on Linux, if `bubblewrap` is not on `PATH` codex prints a warning and uses a
+  bundled copy; install it via your package manager to silence the warning.
+- codex output is advisory and may be incomplete or out of date — the main agent verifies before
+  acting.

package/bridges/codex-cli-bridge/bin/codex-exec.sh

@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+# Delegate plan/instruction EXECUTION to the OpenAI Codex CLI (`codex exec`).
+#
+# Project-agnostic wrapper for the codex-cli-bridge skill. It encodes one fixed,
+# deterministic execution policy and prepends an ORCHESTRATOR EXECUTION CONTRACT
+# so codex never wastes a run rediscovering it. Codex reads the TARGET project's
+# Hard Constraints itself, from the root AGENTS.md in its working directory
+# (codex auto-reads AGENTS.md from cwd) — this wrapper hardcodes no project rules.
+#
+# Fixed policy (single source of truth — passed via flags + --ignore-user-config,
+# so behaviour is deterministic regardless of ~/.codex/config.toml):
+#   - workspace-write sandbox: codex may edit the repo, nothing outside it
+#   - network access OFF: new dependencies / network installs are done by a human
+#   - approval_policy=never: there is no TTY in exec; anything needing escalation
+#     is refused and reported, then handled by hand
+#   - strongest model at maximum reasoning effort (override CODEX_MODEL/CODEX_EFFORT)
+#
+# Auth: SUBSCRIPTION ONLY. Uses the cached ChatGPT login under CODEX_HOME
+# (~/.codex). The wrapper unsets every *_API_KEY plus OPENAI_BASE_URL and passes
+# --ignore-user-config, so a stray key or a personal ~/.codex/config.toml can
+# never silently switch billing or change behaviour. No credentials are bundled.
+#
+# Usage (installed on PATH as `codex-exec`):
+#   codex-exec docs/plans/<slug>.md                 # drive a plan file
+#   echo "apply review fix: ..." | codex-exec -      # ad-hoc instruction (stdin)
+#   CODEX_MODEL=<slug> codex-exec <file>             # override the model
+#   codex-exec <file|-> -- <extra codex flags...>    # passthrough codex flags
+set -euo pipefail
+
+CODEX_MODEL="${CODEX_MODEL:-gpt-5.5}"   # default coding model (verified locally); override per call
+CODEX_EFFORT="${CODEX_EFFORT:-xhigh}"   # maximum reasoning effort
+CHATGPT_LOGIN_GUARD="Logged in using ChatGPT"
+
+# --- Subscription-only guard -------------------------------------------------
+# Never let an API key (or a user config) silently switch codex to paid api-key
+# billing or alternate behaviour. Clear the explicit vars first, then any other
+# *_API_KEY that may have been added later (`compgen` is a bash builtin).
+unset OPENAI_API_KEY CODEX_API_KEY OPENAI_BASE_URL 2>/dev/null || true
+while IFS= read -r _api_key_var; do
+  unset "$_api_key_var" 2>/dev/null || true
+done < <(compgen -v 2>/dev/null | grep '_API_KEY$' || true)
+
+# --- Environment preflight (fail fast, before spending a subscription run) ----
+if ! command -v codex >/dev/null 2>&1; then
+  echo "error: 'codex' (OpenAI Codex CLI) not found on PATH. See this skill's setup/README.md." >&2
+  exit 127
+fi
+if ! codex login status 2>&1 | grep -qF "$CHATGPT_LOGIN_GUARD"; then
+  echo "error: codex is not on a ChatGPT subscription (expected '$CHATGPT_LOGIN_GUARD')." >&2
+  echo "       Run 'codex login' once; this skill is subscription-only and won't use api-key billing." >&2
+  exit 1
+fi
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  echo "error: codex-exec must run inside a git working tree (codex exec needs one; the diff is your review surface)." >&2
+  exit 2
+fi
+if [[ ! -f AGENTS.md ]]; then
+  echo "error: no root AGENTS.md in the current directory — run from the target project root." >&2
+  echo "       (codex reads AGENTS.md for the project's Hard Constraints and declared gates)" >&2
+  exit 2
+fi
+
+read -r -d '' ORCHESTRATOR_DIRECTIVE <<'DIRECTIVE' || true
+ORCHESTRATOR EXECUTION CONTRACT — read before the task, follow it exactly:
+1. Work directly in the current working tree on the current git branch. NEVER run
+   any git write command (no branch, add, commit, stash, reset, checkout, tag, or
+   history rewrite) — the orchestrator commits after review.
+2. Read the target project's root AGENTS.md and obey EVERY Hard Constraint it
+   declares, plus this task's own "do NOT" / out-of-scope section.
+3. After implementing, run a SELF-REVIEW pass over your own changes — `git status`
+   for untracked files and `git diff` for tracked ones, reading the contents of
+   any new untracked files — against the task and those Hard Constraints; fix
+   anything that drifts so the handed-back work is clean.
+4. Run the verification / gate set the project declares (in AGENTS.md or the
+   task). If the project declares NO gate set, STOP and report — do NOT invent
+   checks. Fix every failure before finishing.
+5. Do NOT commit. If you hit a blocker needing escalation (network access, writes
+   outside the repo, a live approval, or an ambiguous decision), STOP and report
+   it clearly — never guess.
+
+TASK:
+DIRECTIVE
+
+if [[ $# -lt 1 ]]; then
+  echo "usage: $0 <plan-file|-> [-- extra codex args...]" >&2
+  exit 2
+fi
+
+prompt_src="$1"; shift
+
+# Split off passthrough codex flags after a literal `--`. Extra args WITHOUT the
+# `--` separator are a mistake — they would be silently dropped, so fail loudly.
+passthrough=()
+if [[ $# -gt 0 ]]; then
+  if [[ "$1" == "--" ]]; then
+    shift
+    passthrough=("$@")
+  else
+    echo "error: unexpected argument '$1'. Pass extra codex flags after a literal '--':" >&2
+    echo "       $0 <plan-file|-> -- <codex flags...>" >&2
+    exit 2
+  fi
+fi
+
+# This wrapper OWNS the safety policy (sandbox level, approval policy, network
+# access, and every -c config override). Reject passthrough flags that would
+# defeat it — appended flags can otherwise override the fixed ones. Benign flags
+# (--add-dir, --cd, --ephemeral, -m, --image, ...) still pass through.
+if [[ ${#passthrough[@]} -gt 0 ]]; then
+  for _arg in "${passthrough[@]}"; do
+    case "$_arg" in
+      -c*|--config*|-s*|--sandbox*|--dangerously-bypass-approvals-and-sandbox|--dangerously-bypass-hook-trust|--full-auto)
+        echo "error: passthrough flag '$_arg' is not allowed — this wrapper fixes the sandbox / approval / network / config policy." >&2
+        echo "       Drop it, or invoke 'codex' directly if you truly need a different policy." >&2
+        exit 2
+        ;;
+    esac
+  done
+fi
+
+if [[ "$prompt_src" == "-" ]]; then
+  task="$(cat)"
+elif [[ -f "$prompt_src" ]]; then
+  task="$(cat "$prompt_src")"
+else
+  echo "error: '$prompt_src' is not a file (use '-' to read the prompt from stdin)" >&2
+  exit 2
+fi
+
+if [[ -z "${task//[[:space:]]/}" ]]; then
+  echo "error: empty plan/instruction" >&2
+  exit 2
+fi
+
+printf '%s\n\n%s' "$ORCHESTRATOR_DIRECTIVE" "$task" | codex exec \
+  --ignore-user-config \
+  --sandbox workspace-write \
+  -c approval_policy="never" \
+  -c sandbox_workspace_write.network_access=false \
+  -c model_reasoning_effort="$CODEX_EFFORT" \
+  -m "$CODEX_MODEL" \
+  "${passthrough[@]+"${passthrough[@]}"}" \
+  -

package/bridges/codex-cli-bridge/bin/codex-review.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# Read-only ADVISORY review BY the OpenAI Codex CLI. Runs under the read-only
+# sandbox, so codex structurally CANNOT edit/create/delete files or write to git
+# — it can only read and emit findings. The orchestrator reads those findings and
+# decides what to act on; codex never applies them itself.
+#
+# Project-agnostic wrapper for the codex-cli-bridge skill. Codex reads the target
+# project's Hard Constraints itself, from the root AGENTS.md in its cwd.
+#
+# Modes:
+#   codex-review plan <plan-file>       # critique an implementation plan
+#   codex-review code [extra focus...]  # review the current working-tree diff
+#
+# Auth/policy: subscription-only, identical to codex-exec.sh. The read-only
+# sandbox grants no writes and no network in v0.140.0, so review needs no separate
+# network flag (the sandbox_workspace_write.* config applies only to workspace-write).
+set -euo pipefail
+
+CODEX_MODEL="${CODEX_MODEL:-gpt-5.5}"
+CODEX_EFFORT="${CODEX_EFFORT:-xhigh}"
+CHATGPT_LOGIN_GUARD="Logged in using ChatGPT"
+
+# --- Subscription-only guard (see codex-exec.sh) -----------------------------
+unset OPENAI_API_KEY CODEX_API_KEY OPENAI_BASE_URL 2>/dev/null || true
+while IFS= read -r _api_key_var; do
+  unset "$_api_key_var" 2>/dev/null || true
+done < <(compgen -v 2>/dev/null | grep '_API_KEY$' || true)
+
+# --- Environment preflight (fail fast) ---------------------------------------
+if ! command -v codex >/dev/null 2>&1; then
+  echo "error: 'codex' (OpenAI Codex CLI) not found on PATH. See this skill's setup/README.md." >&2
+  exit 127
+fi
+if ! codex login status 2>&1 | grep -qF "$CHATGPT_LOGIN_GUARD"; then
+  echo "error: codex is not on a ChatGPT subscription (expected '$CHATGPT_LOGIN_GUARD'). Run 'codex login' once." >&2
+  exit 1
+fi
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  echo "error: codex-review must run inside a git working tree." >&2
+  exit 2
+fi
+if [[ ! -f AGENTS.md ]]; then
+  echo "error: no root AGENTS.md in the current directory — run from the target project root." >&2
+  exit 2
+fi
+
+mode="${1:-}"
+shift || true
+
+case "$mode" in
+  plan)
+    target="${1:-}"
+    shift || true
+    if [[ ! -f "$target" ]]; then
+      echo "error: plan file '$target' not found" >&2
+      exit 2
+    fi
+    if [[ $# -gt 0 ]]; then
+      echo "error: unexpected arguments after plan file: $*" >&2
+      exit 2
+    fi
+    directive="You are REVIEWING an implementation plan — ADVISORY ONLY. You are in a read-only sandbox: do NOT edit, create, or delete any file, and do NOT rewrite the plan. Read the plan below, the project's root AGENTS.md, and the relevant repository code it references. Output findings ONLY, one per line, as: [blocker|major|minor|nit] — location — issue — suggested change. Cover: correctness risks, missing or mis-ordered steps, ambiguities a cold executor would trip on, violated project Hard Constraints (AGENTS.md), scope creep, and missing verification/gates. End with a one-line overall verdict (ship / revise / rethink)."
+    prompt="${directive}"$'\n\nPLAN:\n'"$(cat "$target")"
+    ;;
+  code)
+    directive="You are REVIEWING the current uncommitted working-tree changes — ADVISORY ONLY. You are in a read-only sandbox: do NOT edit, create, or delete any file and do NOT run any git write command. Run \`git status --short\` to list ALL changes, \`git diff\` for the tracked changes, and for every path marked \`??\` by git status READ that file's full contents (plain \`git diff\` omits untracked files). Also read the project's root AGENTS.md. Then output findings ONLY, one per line, as: [blocker|major|minor|nit] — file:line — issue — suggested fix. Focus on correctness bugs, project Hard Constraints (AGENTS.md), behaviour drift vs the intended change, and test/gate gaps. End with a one-line overall verdict (ship / revise / rethink)."
+    if [[ $# -gt 0 ]]; then
+      directive="${directive} Extra focus: $*"
+    fi
+    prompt="$directive"
+    ;;
+  *)
+    echo "usage: $0 plan <plan-file> | code [extra focus...]" >&2
+    exit 2
+    ;;
+esac
+
+printf '%s' "$prompt" | codex exec \
+  --ignore-user-config \
+  --sandbox read-only \
+  -c approval_policy="never" \
+  -c model_reasoning_effort="$CODEX_EFFORT" \
+  -m "$CODEX_MODEL" \
+  -

package/bridges/codex-cli-bridge/capability.json

@@ -0,0 +1,22 @@
+{
+  "family": "agent-workflow",
+  "schema": 1,
+  "name": "codex-cli-bridge",
+  "kind": "execution-backend",
+  "version": "1.0.0",
+  "provides": ["execute", "review"],
+  "roles": {
+    "execute": { "cmd": "codex-exec", "source": "bin/codex-exec.sh", "output": "diff" },
+    "review": { "cmd": "codex-review", "source": "bin/codex-review.sh", "modes": ["plan", "code"], "output": "advisory" }
+  },
+  "detect": {
+    "installed": {
+      "env": "CODEX_CLI_BRIDGE_DIR",
+      "default": "~/.claude/skills/codex-cli-bridge",
+      "file": "SKILL.md"
+    }
+  },
+  "cost": "subscription",
+  "quota": { "kind": "subscription", "finite": true },
+  "provenance": { "author": "sabaiway", "source": "github:sabaiway/agent-workflow" }
+}

package/bridges/codex-cli-bridge/references/driving-codex.md

@@ -0,0 +1,97 @@
+# How the main agent drives `codex`
+
+`codex` is a **delegated-execution backend**: the main agent stays the orchestrator and hands codex a
+bounded sub-task answered from the **ChatGPT subscription**. Codex has two modes here — a sandboxed
+**executor** (`codex-exec`) and a read-only **reviewer** (`codex-review`). Treat all codex output as
+**advisory**: the orchestrator owns the accepted edits, the verification, the commit, and the final
+judgment.
+
+## Delegation checklist
+
+1. Decide the mode: `codex-exec` to *do* (edit the repo under the sandbox), `codex-review` to *judge*
+   (advisory findings, no edits).
+2. Run the wrapper from the **target project root** so codex auto-reads its `AGENTS.md` (the wrappers
+   also preflight that a root `AGENTS.md` and a git work tree exist).
+3. For an ad-hoc instruction, make it self-contained: codex cannot see your conversation — embed the
+   goal, the relevant paths, the non-goals, and the expected result. The project's rules come from
+   `AGENTS.md`.
+4. Let codex run; then **review its diff yourself** and re-run the project's gates.
+5. **Commit yourself** — codex never commits.
+
+## Exec vs review
+
+Use **`codex-exec`** when there is a concrete plan or focused instruction to implement, the project
+declares Hard Constraints + gates in `AGENTS.md`, the work fits network-off `workspace-write`, and you
+can review the resulting diff.
+
+Use **`codex-review plan`** for a cold second opinion on a plan before executing it (risks, missing or
+mis-ordered steps, scope creep, missing gates).
+
+Use **`codex-review code`** for advisory, severity-tagged findings on uncommitted changes — including
+when **untracked** files matter: the wrapper prompt tells codex to run `git status --short` and read
+the contents of `??` files, because plain `git diff` omits them.
+
+## Usage
+
+```bash
+codex-exec docs/plans/<slug>.md                  # drive a plan file
+echo "apply review fix: tighten the guard in X, keep tests green" | codex-exec -
+CODEX_MODEL=<slug> CODEX_EFFORT=high codex-exec <file>     # tune model/effort
+codex-exec <file|-> -- --add-dir ../shared        # passthrough codex flags after `--`
+
+codex-review plan docs/plans/<slug>.md            # critique a plan before executing it
+codex-review code                                 # review the current working-tree diff
+codex-review code "focus on the reducer and its tests"
+```
+
+`codex-exec` prepends an **orchestrator execution contract**: work in the current tree, never
+git-write, obey the target `AGENTS.md`, self-review the diff (incl. untracked files), run the
+project's declared gates (STOP if none are declared), don't commit, report blockers.
+
+## Prompt shapes (for ad-hoc `codex-exec -` instructions)
+
+Execution:
+
+```text
+Implement the change below from the current project root.
+Respect root AGENTS.md, especially its Hard Constraints and declared gates.
+Do not run git write commands. Do not commit.
+If a dependency install, network call, missing gate set, or out-of-repo write is needed, STOP and report.
+
+<the focused instruction + relevant paths>
+```
+
+The review prompt shapes are built into `codex-review` itself — you only pass `plan <file>` or
+`code [focus]`; the wrapper supplies the severity-tagged-findings + verdict directive.
+
+## Re-dispatch vs. fresh run
+
+```bash
+codex exec resume --last      # run codex DIRECTLY — not through codex-exec
+```
+
+Resume is **not** reachable through `codex-exec`: the wrapper's shape (fixed flags + a trailing `-`
+that reads the prompt from stdin) can't host the `resume` subcommand, and the wrapper rejects
+policy-affecting passthrough flags anyway. Run `codex exec resume` directly when you want to continue
+a session without re-sending context — but note it runs **outside** the wrapper, so it does not
+inherit the enforced sandbox/network/approval policy and **may not re-accept those flags**. Restate
+the policy in the resumed instruction, or just start a fresh `codex-exec` run when the posture must be
+guaranteed (see `sandbox-and-flags.md`).
+
+## Escalation policy (edits, network, git)
+
+- **Repo edits** are codex's job *inside* `codex-exec`'s workspace-write sandbox — but you **review the
+  diff** before accepting/committing it. `codex-review` makes no edits at all.
+- **New dependencies / network installs** are done by hand (exec has network OFF), then codex is
+  re-dispatched.
+- **Git writes** (branch/add/commit/stash/reset/checkout/tag/rewrite) are never delegated — the
+  orchestrator commits after review. The execution contract forbids them.
+
+## Handling output
+
+codex output is advisory. Before acting:
+
+- Re-run the project's gates yourself; don't trust a "green" claim you didn't see.
+- Inspect the diff yourself; check edits against the project's `AGENTS.md` rules.
+- Reject advice that conflicts with user instructions, repository rules, or security boundaries.
+- Report uncertainty clearly, and summarise only verified claims back to the user.

package/bridges/codex-cli-bridge/references/sandbox-and-flags.md

@@ -0,0 +1,105 @@
+# `codex` sandbox, flags & policy (reference)
+
+The source of truth is the live binary: `codex --version`, `codex --help`, `codex exec --help`. The
+tables below were captured from **codex-cli 0.140.0**; if the binary disagrees, the binary wins. The
+wrapper commands are `codex-exec` and `codex-review`, backed by `bin/codex-exec.sh` /
+`bin/codex-review.sh`.
+
+## Sandbox levels — when to use which
+
+| Level | Can write? | Network? | Wrapper that uses it |
+|---|---|---|---|
+| `read-only` | no | no | `codex-review` (codex only reads + emits findings) |
+| `workspace-write` | repo (cwd) only | OFF (we force it off) | `codex-exec` (codex edits the repo) |
+| `danger-full-access` | anywhere | yes | never used by this skill |
+
+`codex-exec` always passes:
+
+```bash
+--sandbox workspace-write \
+-c approval_policy="never" \
+-c sandbox_workspace_write.network_access=false
+```
+
+`codex-review` always passes:
+
+```bash
+--sandbox read-only \
+-c approval_policy="never"
+```
+
+Under `read-only`, codex *structurally* cannot edit, create, delete, or git-write — it can only read
+and report. In v0.140.0 `read-only` also grants **no network**, so `codex-review` relies on that and
+passes no separate network flag — the `sandbox_workspace_write.*` config (including
+`network_access`) applies **only** to `workspace-write`.
+
+## Network-OFF invariant (exec)
+
+`codex-exec` keeps network access OFF on purpose: **new dependencies and any network step are
+installed by a human**, not by codex. If a task needs a new package, codex must STOP and report it;
+the orchestrator installs it, then re-dispatches.
+
+## Escalation & approvals
+
+There is **no TTY** in `codex exec`, so `approval_policy=never`: codex never pauses for an interactive
+approval. Any action that would need escalation (network, writes outside the repo, an ambiguous
+decision) is **refused and reported**, and the orchestrator handles it by hand. Codex must never run a
+git write command — the orchestrator commits after reviewing the diff.
+
+## Commit prohibition
+
+Delegated codex runs do not own repository history. The wrappers' contract prohibits every git write:
+no branch, add, commit, stash, reset, checkout, tag, or history rewrite. The orchestrator reviews the
+diff, runs final verification, and commits only when that is the desired next step.
+
+## `resume` caveat
+
+`codex exec resume` re-dispatches an existing session without re-sending context. **It may not
+re-accept `--sandbox` / `approval_policy` / network flags** — do not assume the original posture
+carries over. Restate the policy in the resumed instruction, or start a fresh `codex-exec` run when a
+guaranteed sandbox/network posture matters.
+
+## Subscription / config invariant
+
+Both wrappers, before invoking codex:
+
+- **unset** `OPENAI_API_KEY`, `CODEX_API_KEY`, `OPENAI_BASE_URL`, and every other `*_API_KEY`, so a
+  stray key can't switch to paid api-key billing;
+- pass **`--ignore-user-config`** so a personal `~/.codex/config.toml` cannot change behaviour. Auth
+  still works: codex reads the cached login from `CODEX_HOME` (`~/.codex`) regardless of that flag;
+- preflight `codex login status` and refuse unless it contains `Logged in using ChatGPT`;
+- preflight a git work tree and a root `AGENTS.md`, failing fast (before a run is spent) if missing.
+
+## Verified commands & flags (v0.140.0)
+
+| Command / flag | Verified behaviour |
+|---|---|
+| `codex exec` | non-interactive run from stdin / a prompt arg (headless, no TTY) |
+| `codex exec resume` | resume an exec session (see the resume caveat) |
+| `codex exec review` | review path reachable under `exec` |
+| `codex review` | repository review path; supports reviewing uncommitted changes |
+| `codex login` / `codex login status` | subscription auth flow + status check |
+| `codex sandbox` / `codex apply` / `codex resume` | sandbox / apply / resume helper subcommands |
+| `-c key=value` | override a config value (dotted path, TOML-parsed) — how policy is set deterministically |
+| `--sandbox <mode>` | `read-only` \| `workspace-write` \| `danger-full-access` (this skill uses the first two) |
+| `-c approval_policy=never` | never pause for interactive approval (required: exec has no TTY) |
+| `-c sandbox_workspace_write.network_access=false` | network OFF under workspace-write (the exec invariant) |
+| `-m <model>` | model to use (wrapper default `gpt-5.5` via `CODEX_MODEL`) |
+| `-c model_reasoning_effort=<effort>` | reasoning effort (wrapper default `xhigh` via `CODEX_EFFORT`) |
+| `--ignore-user-config` | do NOT load `$CODEX_HOME/config.toml`; auth still uses `CODEX_HOME` |
+| `--add-dir <dir>` | extra writable dir alongside the workspace |
+| `-C, --cd <dir>` | use `<dir>` as the working root |
+| `--skip-git-repo-check` | allow running outside a git repo (exec normally requires one) |
+| `--ephemeral` | do not persist session files |
+
+## Troubleshooting
+
+- **`could not find bubblewrap on PATH`** (Linux): codex falls back to a bundled bubblewrap. Install
+  `bubblewrap` (`sudo apt install bubblewrap` or equivalent) to silence the warning; it is only a
+  blocker if sandbox startup actually fails.
+- **`not on a ChatGPT subscription`** (wrapper preflight): run `codex login`; confirm with
+  `codex login status` → `Logged in using ChatGPT`.
+- **`must run inside a git working tree` / `no root AGENTS.md`** (wrapper preflight): run the wrapper
+  from the target project root.
+- **codex wants to install a dependency**: it can't (network OFF in exec) — install it by hand, then
+  re-dispatch.