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=all

This installs the repository instructions and skills your coding agents already read: AGENTS.md for Codex, Claude Code skill and instructions, Cursor rules, a PR template, and the GitHub Action.

Codex

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

Codex should run Shipgate before claiming completion on PRs that change tools, MCP exports, OpenAPI specs, prompts, permissions, policies, CI gates, or shipgate.yaml.

Claude Code

agents-shipgate init --workspace . --write --ci \
  --agent-instructions=claude-md,claude-code-skill

Claude Code can get fast local feedback while editing. CI remains the merge authority; hooks or local commands are early warning, not the trust boundary.

Cursor

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

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

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