@sabaiway/agent-workflow-kit 1.6.0 → 1.7.0

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.

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

@@ -0,0 +1,78 @@
+# Setting up OpenAI Codex CLI (`codex`) on a clean machine
+
+This setup is **secret-free**. `codex` itself is **not** bundled — it requires a binary install and a
+one-time interactive sign-in with your own ChatGPT subscription. Do this once per machine, then the
+skill works in any git repository that has a root `AGENTS.md`.
+
+## 1. Install the binary
+
+Install the official OpenAI Codex CLI using the current official channel for your platform, then
+confirm it is on `PATH`:
+
+```bash
+npm install -g @openai/codex     # or: brew install codex  (use the current official channel)
+codex --version                  # this skill was verified with codex-cli 0.140.0 or newer
+```
+
+The binary is **`codex`**. If `codex --version` works but the wrappers can't find it, fix your
+`PATH`. If the installed binary's help disagrees with this skill's references, the live binary wins.
+
+## 2. Sign in once (subscription only)
+
+Run `codex login` once and complete the **ChatGPT** sign-in:
+
+```bash
+codex login
+codex login status               # expect: Logged in using ChatGPT
+```
+
+This caches credentials under `CODEX_HOME` (`~/.codex`, e.g. `~/.codex/auth.json`). That directory is
+**personal** — never copy, commit, package, print, or share it. This skill needs **no API keys** and
+must not be configured with api-key billing; both wrappers unset every `*_API_KEY` (and
+`OPENAI_BASE_URL`) and pass `--ignore-user-config`, so billing can never silently fall back to
+pay-as-you-go and a personal `~/.codex/config.toml` can never change behaviour.
+
+## 3. Put the wrappers on `PATH`
+
+The skill ships two wrappers: `bin/codex-exec.sh` and `bin/codex-review.sh`. Expose them on `PATH`
+under the stable names `codex-exec` / `codex-review` via idempotent managed symlinks (refuse to
+clobber a non-symlink):
+
+```bash
+mkdir -p "$HOME/.local/bin"
+skill_dir="$HOME/.claude/skills/codex-cli-bridge"   # adjust if installed elsewhere
+for w in codex-exec codex-review; do
+  src="$skill_dir/bin/$w.sh"
+  dst="$HOME/.local/bin/$w"
+  if [ -e "$dst" ] && [ ! -L "$dst" ]; then
+    echo "STOP: $dst exists and is not a symlink"; exit 1
+  fi
+  chmod +x "$src"
+  ln -sfn "$src" "$dst"
+done
+export PATH="$HOME/.local/bin:$PATH"   # add to ~/.bashrc / ~/.zshrc to persist
+command -v codex-exec && command -v codex-review
+```
+
+## 4. Smoke test
+
+```bash
+codex --version                                          # version prints
+env -u OPENAI_API_KEY -u CODEX_API_KEY -u OPENAI_BASE_URL codex login status
+```
+
+Expected: the version prints, and login status includes exactly `Logged in using ChatGPT` (the
+`env -u …` mirrors the wrappers, so stray keys can't mask the real auth mode). If the status does not
+include that text, redo step 2. If a wrapper reports `'codex' not found`, fix your `PATH` (step 1);
+if it reports a missing git work tree or root `AGENTS.md`, run it from a project root that has them.
+
+## Notes
+
+- The wrappers are **subscription-only** by design and will not use api-key billing.
+- `codex-exec` runs a **workspace-write** sandbox with **network OFF**; `codex-review` runs
+  **read-only**. See [`../references/sandbox-and-flags.md`](../references/sandbox-and-flags.md).
+- `codex exec` requires a git repository, and the wrappers also require a root `AGENTS.md`. The
+  orchestrator commits, not codex. Re-run `codex login` only when the cached login expires or the
+  account changes.
+- On Linux, install `bubblewrap` (`sudo apt install bubblewrap` or equivalent) to silence the
+  "could not find bubblewrap" warning; codex otherwise uses a bundled copy.

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",
@@ -49,7 +49,8 @@
     "references/",
     "launchers/",
     "migrations/",
-    "tools/"
+    "tools/",
+    "bridges/"
   ],
   "engines": {
     "node": ">=18"

package/tools/detect-backends.mjs

@@ -58,6 +58,9 @@ export const KNOWN_BACKENDS = [
     credential: { env: 'CODEX_HOME', default: '~/.codex', file: 'auth.json' },
     setupUrl: 'https://github.com/sabaiway/agent-workflow/blob/main/codex-cli-bridge/setup/README.md',
     setupPathLocal: 'setup/README.md',
+    // The short canonical guided commands. Binary-install is platform-variant and longer, so it is
+    // REFERENCED via setupRef (§1 of that README), never duplicated here (would drift with the README).
+    guide: { setupRef: 'codex-cli-bridge/setup/README.md', loginCmd: 'codex login', verifyCmd: 'codex login status' },
   },
   {
     name: 'antigravity-cli-bridge',
@@ -66,6 +69,7 @@ export const KNOWN_BACKENDS = [
     credential: { env: null, default: '~/.gemini/antigravity-cli', file: 'antigravity-oauth-token' },
     setupUrl: 'https://github.com/sabaiway/agent-workflow/blob/main/antigravity-cli-bridge/setup/README.md',
     setupPathLocal: 'setup/README.md',
+    guide: { setupRef: 'antigravity-cli-bridge/setup/README.md', loginCmd: 'agy', verifyCmd: 'echo "say OK" | agy-run -' },
   },
 ];
 
@@ -257,6 +261,38 @@ export const detectBackend = (entry, deps = {}) => {
 
 export const detectBackends = (deps = {}) => KNOWN_BACKENDS.map((entry) => detectBackend(entry, deps));
 
+// ── guidance (axis-aware, for the `setup` flow) ───────────────────────────────
+
+const registryEntry = (name) => KNOWN_BACKENDS.find((b) => b.name === name);
+
+// The skill axis can't be auto-fixed in every state: an absent dir IS placeable from the bundled
+// kit; any other non-ok state (stub/foreign/invalid/unsupported, or an `unknown` marker fs error)
+// is a STOP — never overwrite a dir we don't provably own.
+const skillHint = (status, guide) =>
+  status.manifestState === NOT_INSTALLED
+    ? `place the bundled bridge skill — run \`/agent-workflow-kit setup ${status.name}\``
+    : `bridge skill dir is "${status.manifestState}" — STOP and inspect ${status.skillDir ?? 'the skill dir'} (see ${guide?.setupRef ?? status.setupHint?.url})`;
+
+// guideFor inspects the manifest/cli/credentials axes INDEPENDENTLY (never the collapsed readiness)
+// and returns an ORDERED list of the manual steps still owed — possibly several at once (e.g. a
+// fresh machine needs both the CLI and a login). `[]` ⇒ nothing manual left (the linker handles the
+// wrappers). Each step is `{ need: 'skill'|'cli'|'credentials', hint }`. Pure; no fs, no side effects.
+export const guideFor = (status) => {
+  const guide = registryEntry(status.name)?.guide;
+  const out = [];
+  if (status.manifestState !== OK) out.push({ need: 'skill', hint: skillHint(status, guide) });
+  if (status.cli.state !== PRESENT) {
+    out.push({ need: 'cli', hint: `install the "${status.cli.bin}" CLI — see ${guide?.setupRef ?? status.setupHint?.url} §1` });
+  }
+  if (status.credentials.state !== PRESENT) {
+    out.push({
+      need: 'credentials',
+      hint: `sign in once (subscription): ${guide?.loginCmd ?? 'see the setup README'}  (verify: ${guide?.verifyCmd ?? 'see the setup README'})`,
+    });
+  }
+  return out;
+};
+
 // ── report ───────────────────────────────────────────────────────────────────
 
 const MARK = { [PRESENT]: '✓', [MISSING]: '✗', [UNKNOWN]: '?' };