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 agents-shipgate-reports/verifier.json, agents-shipgate-reports/report.json, and agents-shipgate-reports/pr-comment.md. Treat release_decision.decision as the wire gating signal.

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 compact agent result. 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 agent-json

The canonical single call for a coding agent (--agent codex|claude-code|cursor): it returns the stable agent_result_v1 contract — completion, stop, repair, human-review, policy-provenance, and exit-code fields — on stdout.

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.13.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 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.