@sabaiway/agent-workflow-kit 1.6.0 → 1.7.0

package/bridges/antigravity-cli-bridge/bin/agy.test.mjs

@@ -0,0 +1,59 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, chmodSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const WRAPPER = join(HERE, 'agy.sh');
+
+// Build a sandbox HOME whose ~/.local/bin holds a STUB `agy`. The wrapper prepends
+// "$HOME/.local/bin" to PATH, so it resolves our stub instead of the real binary — no network,
+// no real subscription CLI, fully hermetic.
+const makeSandbox = (stubBody) => {
+  const home = mkdtempSync(join(tmpdir(), 'agy-wrapper-test-'));
+  const bin = join(home, '.local', 'bin');
+  mkdirSync(bin, { recursive: true });
+  const stub = join(bin, 'agy');
+  writeFileSync(stub, stubBody, { mode: 0o755 });
+  chmodSync(stub, 0o755);
+  return home;
+};
+
+const runWrapper = (home, env, prompt = 'hello') =>
+  spawnSync('bash', [WRAPPER, prompt], {
+    env: { HOME: home, PATH: `${join(home, '.local', 'bin')}:${process.env.PATH}`, ...env },
+    encoding: 'utf8',
+    timeout: 20000,
+  });
+
+describe('agy.sh — hard wall-clock cap (timeout(1))', () => {
+  it('kills a hung agy at AGY_HARD_TIMEOUT and reports it (non-zero + actionable guidance)', () => {
+    const home = makeSandbox('#!/usr/bin/env bash\nsleep 30\n');
+    const started = Date.now();
+    const r = runWrapper(home, { AGY_HARD_TIMEOUT: '2s', AGY_TIMEOUT: '2s', AGY_MODEL: '' });
+    const elapsed = Date.now() - started;
+    rmSync(home, { recursive: true, force: true });
+    assert.ok(elapsed < 13000, `wrapper must return well under the kill-after window, took ${elapsed}ms`);
+    assert.notEqual(r.status, 0, 'a timed-out run must exit non-zero');
+    assert.match(r.stderr, /exceeded the hard cap/, 'must explain the hard-cap kill');
+  });
+
+  it('passes a fast agy run through unchanged (exit 0, stdout preserved)', () => {
+    const home = makeSandbox('#!/usr/bin/env bash\necho "OK reply"\nexit 0\n');
+    const r = runWrapper(home, { AGY_HARD_TIMEOUT: '10s', AGY_TIMEOUT: '10s', AGY_MODEL: '' });
+    rmSync(home, { recursive: true, force: true });
+    assert.equal(r.status, 0, `expected clean exit, got ${r.status}; stderr=${r.stderr}`);
+    assert.match(r.stdout, /OK reply/);
+  });
+
+  it('propagates a non-timeout agy failure code verbatim (no false hard-cap message)', () => {
+    const home = makeSandbox('#!/usr/bin/env bash\necho "boom" >&2\nexit 3\n');
+    const r = runWrapper(home, { AGY_HARD_TIMEOUT: '10s', AGY_TIMEOUT: '10s', AGY_MODEL: '' });
+    rmSync(home, { recursive: true, force: true });
+    assert.equal(r.status, 3, 'a genuine agy failure code must pass through');
+    assert.doesNotMatch(r.stderr, /exceeded the hard cap/, 'must not mislabel a non-timeout failure');
+  });
+});

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

@@ -0,0 +1,22 @@
+{
+  "family": "agent-workflow",
+  "schema": 1,
+  "name": "antigravity-cli-bridge",
+  "kind": "execution-backend",
+  "version": "1.0.0",
+  "provides": ["review", "probe"],
+  "roles": {
+    "review": { "cmd": "agy-run", "source": "bin/agy.sh", "template": "references/review-prompt.md", "output": "advisory" },
+    "probe": { "cmd": "agy-run", "source": "bin/agy.sh", "output": "advisory" }
+  },
+  "detect": {
+    "installed": {
+      "env": "ANTIGRAVITY_CLI_BRIDGE_DIR",
+      "default": "~/.claude/skills/antigravity-cli-bridge",
+      "file": "SKILL.md"
+    }
+  },
+  "cost": "subscription",
+  "quota": { "kind": "subscription", "finite": true },
+  "provenance": { "author": "sabaiway", "source": "github:sabaiway/agent-workflow" }
+}

package/bridges/antigravity-cli-bridge/references/driving-agy.md

@@ -0,0 +1,108 @@
+# How the main agent drives `agy`
+
+`agy` is a **delegated-execution backend**: the main agent stays the orchestrator and hands `agy` a
+bounded, self-contained sub-task. `agy` answers from the **subscription** quota, so the goal is
+maximum useful output per token of that quota. Treat its output as **advisory** — the main agent owns
+edits, verification, and final judgment.
+
+## Delegation checklist
+
+1. Pick the narrowest useful question.
+2. Choose the cheapest model that can answer it.
+3. Include only the relevant excerpts, paths, constraints, and the expected output shape.
+4. State permission boundaries in the prompt (no edits, no git writes).
+5. Run `agy-run` headlessly.
+6. Treat the response as advisory and verify before acting.
+
+## Model selection
+
+| Task | Model |
+|---|---|
+| Reachability / smoke / "is it wired?" | `Gemini 3.5 Flash (Low)` |
+| Cheap probes, summaries | `Gemini 3.5 Flash (Medium)` |
+| Quick review with a little more effort | `Gemini 3.5 Flash (High)` |
+| Reasoning, plan critique, careful drafting | `Gemini 3.1 Pro (High)` (wrapper default) |
+| Same reasoning, lower quota cost | `Gemini 3.1 Pro (Low)` |
+| A different engine's opinion | `Claude Sonnet 4.6 (Thinking)`, `Claude Opus 4.6 (Thinking)`, or `GPT-OSS 120B (Medium)` |
+
+Don't reach for Pro by reflex — Flash answers most reachability/probe questions for a fraction of the
+quota.
+
+## Quota economy
+
+Subscription quota is finite. Prefer:
+
+- A short probe on Flash before a large Pro run.
+- One sharp question over broad "review everything" prompts.
+- Prompt files with trimmed excerpts instead of whole repositories.
+- `AGY_TIMEOUT=2m` for probes, longer timeouts only for deep reviews.
+- Reusing a conversation with `--continue` when the context is already loaded.
+
+## Continue vs. fresh
+
+```bash
+# Continue the most recent conversation (cheaper than re-sending context):
+agy-run "Given your previous review, list only the top three risks." -- --continue
+
+# Resume a specific conversation by id:
+agy-run "Continue from the prior architecture critique; focus on test gaps." -- --conversation <id>
+```
+
+Use conversation state only when it saves quota or preserves useful context. For auditable decisions,
+prefer self-contained prompts.
+
+## Escalation policy (edits, network, git)
+
+The wrapper passes no `--add-dir`, no `--dangerously-skip-permissions`, and no `--sandbox`. Treat this
+as a **policy boundary you enforce in the prompt, not an enforced sandbox** — so prompt `agy` as a
+read-only reviewer, and reach for `-- --sandbox` for anything that might trigger terminal/tool work:
+
+```text
+Do not edit files. Do not run git write commands. Do not branch, add, commit, stash, reset, or
+rewrite history. Return findings and suggested changes only.
+```
+
+- **Repo edits** stay with the orchestrator. If a flow truly needs `agy` to write files, opt in
+  explicitly — `agy-run "..." -- --add-dir . --dangerously-skip-permissions` — and review the diff.
+- **New dependencies / network installs** are done by hand, not by `agy`.
+- **Git writes** (branch/commit) are never delegated — the orchestrator commits after review.
+- Prefer `-- --sandbox` for any prompt that might trigger terminal work.
+
+## Project-context prompts
+
+Probe reachability from a project root (cheap model):
+
+```bash
+AGY_MODEL="Gemini 3.5 Flash (Low)" agy-run \
+  "Read the cwd context file and report the dialogue language plus one Hard Constraint."
+AGY_MODEL="Gemini 3.5 Flash (Low)" agy-run \
+  "Without using a file pointer, is there a project-specific planning skill in this repo? Name it and cite its path."
+```
+
+Plan-review prompt shape:
+
+```text
+You are reviewing the plan below from the current repository root.
+Use the root context file and per-workspace skills if they are reachable.
+Do not edit files. Do not run git write commands.
+Return: 1) blocking issues  2) non-blocking risks  3) missing verification  4) a concise recommendation.
+The implementation plan text follows in this same prompt.
+```
+
+Diff/code-review prompt shape (provide the diff as text):
+
+```text
+Review this diff against the stated constraints.
+Focus on bugs, behavioural regressions, missing tests, and violations of the project rules.
+Cite file paths and line hints from the diff where possible. Do not summarise unless there are no findings.
+The project constraints and diff text follow in this same prompt.
+```
+
+## Handling output
+
+`agy` returns plain text. Do not assume it is complete, current, or machine-valid. Before acting:
+
+- Check claims against local files or primary sources available to the main agent.
+- Re-run local tests and linters yourself.
+- Reject advice that conflicts with user instructions, repository rules, or security boundaries.
+- Summarise uncertainty clearly when reporting back to the user.

package/bridges/antigravity-cli-bridge/references/models-and-flags.md

@@ -0,0 +1,93 @@
+# `agy` models & flags (reference)
+
+The source of truth is the live binary: `agy --version`, `agy --help`, `agy models`. The tables below
+were captured from **v1.0.10**; if the binary disagrees, the binary wins. The wrapper command is
+`agy-run`, backed by `bin/agy.sh`.
+
+## Headless behaviour
+
+Use `-p`, `--print`, or `--prompt` to run one non-interactive prompt and print the text response. The
+wrapper always uses headless `-p`. **There is no JSON output mode in v1.0.10** — ask for Markdown,
+bullets, tables, or fenced blocks when the caller needs structure, then validate the text yourself.
+
+## Wrapper contract
+
+```bash
+agy-run <prompt | - | @file> [-- extra agy flags...]
+```
+
+Inputs:
+
+- Prompt text: `agy-run "say OK"`.
+- Stdin: `echo "say OK" | agy-run -`.
+- Prompt file: `agy-run @prompt.md`.
+- Extra `agy` flags after `--`: `agy-run @prompt.md -- --add-dir . --continue`. Extra args **without**
+  the `--` separator are rejected with a usage error (they are never silently dropped).
+- A literal prompt that **begins with `@`** is read as a file path. Pass such prompts via stdin
+  instead: `printf '%s' '@handle, review this' | agy-run -`.
+
+Environment:
+
+| Var | Default | Effect |
+|---|---|---|
+| `AGY_MODEL` | `Gemini 3.1 Pro (High)` | model display string; set empty (`AGY_MODEL=`) to drop `--model` and let `agy` use `settings.json` |
+| `AGY_TIMEOUT` | `5m` | value passed to `--print-timeout` |
+
+Subscription invariant: the wrapper prepends `$HOME/.local/bin` to `PATH` and clears
+`ANTIGRAVITY_API_KEY` / `GEMINI_API_KEY` / `GOOGLE_API_KEY` / `GOOGLE_GENAI_API_KEY` before execution.
+Auth comes from the user's cached OAuth token, never from bundled credentials.
+
+## Models
+
+Pass the **exact display string** from `agy models`, or set `AGY_MODEL`.
+
+| Model string | Practical use |
+|---|---|
+| `Gemini 3.5 Flash (Low)` | lowest-cost smoke tests and simple rewrites |
+| `Gemini 3.5 Flash (Medium)` | cheap probes, fast summaries, context-reachability checks |
+| `Gemini 3.5 Flash (High)` | fast review when a little more reasoning effort is useful |
+| `Gemini 3.1 Pro (Low)` | cheaper Pro pass for medium reasoning |
+| `Gemini 3.1 Pro (High)` | wrapper default; hard reasoning, plan critique, architecture review |
+| `Claude Sonnet 4.6 (Thinking)` | cross-vendor reasoning comparison |
+| `Claude Opus 4.6 (Thinking)` | expensive deep critique when the user wants another high-end pass |
+| `GPT-OSS 120B (Medium)` | open-weights-style comparison / diversity pass |
+
+Examples:
+
+```bash
+AGY_MODEL="Gemini 3.5 Flash (Medium)" agy-run "Read AGENTS.md and report one Hard Constraint."
+AGY_MODEL="Claude Sonnet 4.6 (Thinking)" AGY_TIMEOUT=10m agy-run @review-prompt.md
+```
+
+## Flags (from `agy --help`, v1.0.10)
+
+| Flag | Meaning | Notes |
+|---|---|---|
+| `-p`, `--print`, `--prompt` | run one headless prompt and print the text response | the wrapper uses `-p` |
+| `--print-timeout <dur>` | cap headless wait time | CLI default `5m0s`; wrapper default `5m` via `AGY_TIMEOUT` |
+| `--model <string>` | select a model | must match an `agy models` display string exactly |
+| `-i`, `--prompt-interactive` | run an initial prompt, then continue interactively | not used by the wrapper |
+| `-c`, `--continue` | continue the most recent conversation | pass after the wrapper's `--` |
+| `--conversation <id>` | resume a specific conversation by id | use only when the user provides/records the id |
+| `--add-dir <dir>` | add a directory to the workspace | repeatable; for explicit extra context |
+| `--dangerously-skip-permissions` | auto-approve all tool permissions | avoid by default; use only with explicit user approval |
+| `--sandbox` | run with terminal restrictions enabled | prefer when delegating a prompt that might trigger tool/terminal work |
+| `--log-file <path>` | override the CLI log-file path | keep logs secret-free and out of committed artifacts |
+
+## Subcommands (v1.0.10)
+
+`changelog`, `help`, `install`, `models`, `plugin` / `plugins`, `update`.
+
+**Not available in v1.0.10:** any JSON output mode, and any `agy inspect`. Output is plain text.
+
+## Project-context flags
+
+`agy` reads context from its current working directory:
+
+```text
+.antigravity.md > GEMINI.md > AGENTS.md
+.agents/skills/
+```
+
+Use `--add-dir` for extra directories not already reachable from cwd. Subdirectory `CLAUDE.md` files
+are **not** auto-loaded — include those local rules manually in the prompt when they matter.

package/bridges/antigravity-cli-bridge/references/review-prompt.md

@@ -0,0 +1,51 @@
+# Review prompt template — `agy-run` (review role)
+
+The `review` role of `antigravity-cli-bridge` delegates a **read-only second opinion** to `agy`.
+`agy` cannot see the conversation and (in v1.0.10) has no JSON output, so the prompt must be
+**self-contained** and ask for **plain-Markdown findings only** — no repo edits, no git writes.
+Fill the `{{…}}` slots, pipe it to `agy-run`, then verify every finding locally before acting.
+
+```text
+You are a meticulous staff-level reviewer giving a SECOND OPINION. You are read-only:
+do not propose to edit files, run commands, or make git changes — return findings only.
+
+## What to review
+{{TARGET}}   # e.g. "the implementation plan below" or "the working-tree diff below"
+
+## Project rules
+Read the repo's root AGENTS.md (your cwd) and obey its Hard Constraints and conventions.
+If AGENTS.md declares a verification/gate set, judge the change against it; if it declares
+none, say so — do NOT invent checks.
+
+## Material
+{{CONTENT}}  # paste the plan text, or the unified diff, or the file excerpts under review
+
+## Focus (optional)
+{{FOCUS}}    # e.g. "correctness of the new reducer", "backward-compat of the stamp takeover"
+
+## Output — Markdown, this exact shape, nothing else
+### Verdict
+One line: SHIP / SHIP WITH NITS / REWORK, plus a one-sentence reason.
+### Blocking
+Numbered. Correctness bugs, contract violations, data loss, security. Cite file:line.
+Empty? write "none".
+### Non-blocking
+Numbered. Simplifications, reuse, naming, missing tests. Cite file:line.
+### Questions
+Anything ambiguous that changes your verdict if answered.
+```
+
+## Usage
+
+```bash
+# critique a plan
+AGY_MODEL="Gemini 3.1 Pro (High)" agy-run @/tmp/review-prompt.filled.md
+
+# critique the current diff (build the prompt with the diff pasted into {{CONTENT}})
+git diff | ...  # assemble the filled prompt, then:
+agy-run @/tmp/review-prompt.filled.md
+```
+
+Treat the result as **advisory** — `agy` output may be incomplete or out of date. The orchestrator
+re-runs the project's real gates and owns every accepted change. See
+[`driving-agy.md`](./driving-agy.md).

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 init`, or bootstrap the whole
+  family via the **`agent-workflow-kit`** orchestrator (`npx @sabaiway/agent-workflow-kit 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.