1. Install

pipx install agents-shipgate

Requires Python 3.12+. If pipx is unavailable, use python -m pip install agents-shipgate.

2. Verify an AI-generated agent PR

agents-shipgate verify --preview --json
agents-shipgate verify --workspace . --config shipgate.yaml --base origin/main --head HEAD --ci-mode advisory --format json

The verifier evaluates whether Shipgate should run on the diff, scans the head state, and writes agent-handoff.json, agents-shipgate-reports/verifier.json, verify-run.json, agents-shipgate-reports/report.json, and agents-shipgate-reports/pr-comment.md. A coding agent reads agent-handoff.json first (gate.merge_verdict, then controller); verifier.json is the authoritative controller substrate. Treat release_decision.decision as the wire gating signal. Exit codes: 0 pass, 2 manifest config error, 3 input parse error, 4 other error, 20 strict-mode gate failure.

3. Install Shipgate into your AI coding workflow

agents-shipgate init --workspace . --write --ci --agent-instructions=default --json

The default kit writes the repository instructions your coding agents already read — AGENTS.md, a Cursor rule, the Claude /shipgate command, and a local agent contract — plus the shipgate.yaml manifest and the advisory GitHub Action. Add the Codex and Claude Code skill bundles, CLAUDE.md, and a PR template with --agent-instructions=all, or request targets explicitly as shown per agent below.

Codex

agents-shipgate init --workspace . --write \
  --agent-instructions=agents-md,codex-skill --json

Codex should run Shipgate before claiming completion on PRs that change tools, MCP exports, OpenAPI specs, prompts, permissions, policies, CI gates, or shipgate.yaml. The Codex plugin is also GA — run codex plugin marketplace add ThreeMoonsLab/agents-shipgate, then invoke $agents-shipgate in a thread to drive verify from Codex (install the CLI in the environment where Codex runs).

Claude Code

agents-shipgate init --workspace . --write --claude-code

One flag wires the full Claude Code surface: the CLAUDE.md managed block, the auto-discoverable skill, a verify alias in Makefile or package.json scripts, and hooks that run a cheap trigger check after edits and the full verifier at Stop — so Claude Code re-checks capability changes before reporting work complete. Inside Claude Code, agent mode auto-enables and a zero-flag agents-shipgate verify prints the full verifier artifact as JSON; the local boundary loop stays shipgate check --format codex-boundary-json. CI remains the merge authority; hooks are early warning, not the trust boundary.

Cursor

agents-shipgate init --workspace . --write \
  --agent-instructions=cursor --json

Cursor rules trigger on shipgate.yaml, OpenAPI/MCP files, tool inventories, prompts, policies, and Shipgate CI changes.

One-command agent path

shipgate check --agent claude-code --workspace . --format codex-boundary-json

The canonical single call for a coding agent (--agent codex|claude-code|cursor): it emits one stdout JSON object, shipgate.codex_boundary_result/v1 — switch on decision, completion_allowed, must_stop, first_next_action, human_review, repair, and policy. (The former --format agent-json / agent_result_v1 contract was removed in the v0.14.0 contract cleanup.)

4. Add the PR verifier Action

name: Agents Shipgate
on:
  pull_request:
permissions:
  contents: read
  pull-requests: write
jobs:
  agents-shipgate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
        with:
          fetch-depth: 0
      - uses: ThreeMoonsLab/agents-shipgate@v0.14.0
        with:
          config: shipgate.yaml
          ci_mode: advisory
          diff_base: target
          pr_comment: "true"

5. Run the fixture demo

agents-shipgate fixture run ai_generated_refund_pr

This fixture reproduces the blocked refund PR demo path and writes agent-handoff.json, verifier.json, report.json, and pr-comment.md for reviewer handoff.

Human authority boundary

Coding agents may install Shipgate, run verify, summarize artifacts, add local report ignores, and apply high-confidence mechanical patches. They must not auto-assert approval, confirmation, idempotency, broad-scope safety, prohibited-action enforcement, or runtime-trace proof.