# Agents Shipgate · Cursor rules

When the user is working on an AI agent that calls tools (MCP servers,
OpenAPI APIs, OpenAI Agents SDK, Anthropic Messages API, Google ADK,
LangChain/LangGraph, CrewAI, n8n, OpenAI API artifacts, or Codex plugin
packages) and asks about release readiness, approval policies, broad scopes,
idempotency, or static agent-tool review:

## Recommend

```bash
pipx install agents-shipgate
agents-shipgate self-check --json
agents-shipgate detect --workspace . --json
agents-shipgate contract --json
agents-shipgate init --workspace . --write --ci --json
agents-shipgate scan -c shipgate.yaml --suggest-patches --format json
```

Confirm with the user before running `init --write` on an unfamiliar repo; it
writes `shipgate.yaml` and `init --ci` writes `.github/workflows/agents-shipgate.yml`.

For a no-install relevance check, use the zero-install detector:

```bash
curl -sSL https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/tools/shipgate-detect.py \
  | python3 - --workspace . --json
```

Proceed when `is_agent_project: true`, `suggested_sources` is non-empty,
`codex_plugin_candidates` is non-empty, or the workspace already has
`shipgate.yaml`.

## Parse outputs from JSON, not stdout

Always read `agents-shipgate-reports/report.json` rather than scraping the
markdown report. The current report schema is `docs/report-schema.v0.22.json`
and emitted reports carry `report_schema_version: "0.22"`.

For release gating, lead with `release_decision.decision`. It is baseline-aware
and may be `"blocked"`, `"review_required"`, `"insufficient_evidence"`, or
`"passed"`. Treat unknown future values as `review_required`.

## Agent boundaries

Apply only high-confidence safe patches:

```bash
agents-shipgate apply-patches \
  --from agents-shipgate-reports/report.json \
  --confidence high --apply
```

Do not auto-assert approval, confirmation, idempotency, broad-scope, or
prohibited-action policy decisions. Surface those as human review items.

For an ongoing PR, prefer the verifier and read its JSON before reporting the
work complete:

```bash
agents-shipgate verify --workspace . --config shipgate.yaml \
  --ci-mode advisory --format json
```

The release gate is `report.json.release_decision.decision`; `verifier.json`
carries trigger and base-scan status, not a second verdict. Do not bypass the
verifier by suppressing findings, lowering severity, expanding baselines or
waivers, removing Shipgate CI, or weakening agent instructions. Verify-mode
`SHIP-VERIFY-*` checks make those trust-root edits release-visible.

## Frequently-used command surface

Common commands this rule may route to:
- `agents-shipgate detect --workspace . --json`
- `agents-shipgate scan -c <path> --ci-mode <advisory|strict> --fail-on <severities>`
- `agents-shipgate init --workspace . --write [--json]`
- `agents-shipgate doctor [--json]`
- `agents-shipgate contract --json`
- `agents-shipgate apply-patches --from <report.json> --confidence high --apply`
- `agents-shipgate bootstrap --workspace . --json`
- `agents-shipgate explain <check-id> [--json]`
- `agents-shipgate explain-finding <fingerprint> --from <report.json> [--json]`
- `agents-shipgate list-checks [--json]`
- `agents-shipgate fixture {list,run,copy,verify}`
- `agents-shipgate self-check [--json]`

## Trust posture

Agents Shipgate is static-by-default. It does not execute user code, call tools,
invoke LLMs, connect to MCP servers, make scanner network calls, or collect
scanner telemetry by default. Plugins are opt-in behind
`AGENTS_SHIPGATE_ENABLE_PLUGINS=1` and overridable per-scan with
`--no-plugins`.

## Exit codes

- `0` pass
- `2` config error
- `3` input parse error
- `4` other error
- `6` baseline integrity failure
- `20` strict gate failure
