[codex] Externalize adoption kit rendering

CHANGELOG.md

@@ -12,6 +12,14 @@
   signal. Per-file coverage is not enforced; the aggregate floor only
   rises in step with what's already proven on `main`.
 
+- **Adoption kit rendering externalized.** Codex and Claude Code
+  `--agent-instructions` skill bundles now render from packaged
+  `adoption-kits/` files instead of Python string constants. Downstream repos
+  can provide `.agents-shipgate/adoption-kit.yaml` or
+  `--agent-instructions-kit <path>` for local overrides, and generated skill
+  directories now carry `.agents-shipgate-kit.json` sidecars for managed
+  migrations.
+
 - **v0.20 — third-party adapter entry-point discovery (E4 from round-3 review).**
   Opens the same extension surface for adapters (input loaders) that M5
   already opened for check plugins. Discovery is gated by the existing

README.md

@@ -134,6 +134,16 @@ The skill lives at `.agents/skills/agents-shipgate/`, can be invoked with
 `$agents-shipgate`, and teaches Codex the bootstrap, scan, report-reading,
 advisory CI, and finding-triage workflows.
 
+To customize generated skill content in a downstream repo without rebuilding
+`agents-shipgate`, add `.agents-shipgate/adoption-kit.yaml` with repo-local
+overrides, or pass it explicitly:
+
+```bash
+agents-shipgate init --workspace . --write \
+  --agent-instructions=codex-skill \
+  --agent-instructions-kit .agents-shipgate/adoption-kit.yaml
+```
+
 ## Who this is for
 
 - **Agent builders** — review MCP, OpenAPI, and SDK tool definitions before merging changes that expand the tool surface.

STABILITY.md

@@ -329,6 +329,11 @@ tests on every CI run, not by convention:
     call to resolve the bundled trigger catalog.
   - **`fixtures.py`** — one `importlib.resources.files('agents_shipgate')`
     call to resolve the bundled fixture directory.
+  - **`cli/discovery/agent_instructions/adoption_kit.py`** — one
+    `importlib.resources.files('agents_shipgate')` call to resolve bundled
+    first-party adoption-kit files from the installed wheel. Downstream
+    customization is explicit repo-local file reading through
+    `--agent-instructions-kit`, never dynamic imports or network fetches.
   - **`cli/self_check.py`** — one `__import__(module_name)` call
     validates that supplied modules import cleanly. Runs only under
     `agents-shipgate self-check`, never during scan.

adoption-kits/claude-code-skill/.agents-shipgate-kit-metadata.json

@@ -0,0 +1,37 @@
+{
+  "schema_version": 1,
+  "target": "claude-code-skill",
+  "prior_render_sha256": {},
+  "bootstrap_legacy_sha256": {
+    "SKILL.md": [
+      "b17c53d9905f46b196be38e98cf71e53da6779e3a4f426ecff14f2b0f238aba9"
+    ],
+    "prompts/add-shipgate-to-repo.md": [
+      "1ea69b1d3d418080c76540fff3b20044f70ed6787418eb5e4d3d39e036b34014"
+    ],
+    "prompts/decide-shipgate-relevance.md": [
+      "8fab0595326b127fb1678828fd9b15c63cbe98f0229aad5bb87d47030e4b9ca6"
+    ],
+    "prompts/explain-finding-to-user.md": [
+      "18031ed870b3c937a2996173820639ef441afe0a45e8171f16468826cd389829"
+    ],
+    "prompts/fix-top-finding.md": [
+      "90d36fbe91668fdc64e5e73727ec8285ee62c584d695b866261ef569fea07074"
+    ],
+    "prompts/recommend-fixes.md": [
+      "162aa2fb96066535425d9cf86a247a6782b8ec7cc661a18b42dbedf394779475"
+    ],
+    "prompts/stabilize-strict-mode.md": [
+      "bb97c3fbd3b52d5755f6960878f350d484837849c3e536d99aab3fab3e353405"
+    ],
+    "prompts/triage-false-positive.md": [
+      "8cfbb0d4b6e2c36569d24260384d3a54165f966276112f4b143b4ac234b51ada"
+    ],
+    "prompts/upgrade-shipgate-version.md": [
+      "992122338eba26ae5d8056b9658117d718a6b477b9928c2a438dd449b5effb68"
+    ],
+    "ci-recipes/advisory-pr-comment.yml": [
+      "c3756c86f52cf00a594b3fe38179b66e0f07dc8c52b98b9e76f4a15939901c77"
+    ]
+  }
+}

adoption-kits/claude-code-skill/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: agents-shipgate
+description: Use when the user wants to add a local-first, static Tool-Use Readiness release gate for an AI agent's tool surface, run agents-shipgate scans, fix or triage Shipgate findings, add Shipgate to CI, or interpret a shipgate report. Triggers on phrases like "add shipgate", "release readiness for my agent", "tool-use readiness", "scan my agent", "shipgate scan", "shipgate.yaml", "agents-shipgate-reports/report.json", "fix shipgate finding".
+---
+
+# agents-shipgate skill
+
+`agents-shipgate` is a local-first, static Tool-Use Readiness release gate for AI agent tool surfaces. It analyzes `shipgate.yaml` plus tool sources (MCP exports, OpenAPI specs, OpenAI Agents SDK Python files, Anthropic Messages API artifacts, Google ADK files, LangChain/LangGraph files, CrewAI files, OpenAI API artifacts, Codex plugin packages and marketplaces, n8n workflow JSON) and emits deterministic findings as Markdown, JSON, and SARIF.
+
+It does **not** run agents, call tools, invoke LLMs, connect to MCP servers, or send telemetry by default. Static analysis only; audited exceptions are pinned in `tests/test_adapter_static_only.py::ALLOWED_EXCEPTIONS`.
+
+> The skill name is intentionally `agents-shipgate` (not `shipgate`) so it does not collide with the `/shipgate` slash command shipped at `.claude/commands/shipgate.md` — Claude Code lets a skill with the same name preempt a command, which would bypass the bootstrap flow the slash command is meant to deliver.
+
+## When to use this skill
+
+- The user asks to add Tool-Use Readiness or pre-merge checks to an agent project.
+- The repo already has `shipgate.yaml` or `agents-shipgate-reports/report.json`.
+- The user asks to fix, triage, suppress, or explain a Shipgate finding.
+- The user wants to add Shipgate to CI (GitHub Actions, GitLab CI, CircleCI).
+
+## When NOT to use this skill
+
+- Generic linting / type checking — use the project's existing tooling.
+- Runtime monitoring, evals, or behavioral testing — Shipgate is static-only.
+- LLM output quality assessment — out of scope.
+- Editing `agents-shipgate`'s own check implementations — that's upstream-repo work, not user-repo work.
+
+## How to act
+
+Pick the matching task and follow the linked recipe verbatim. Recipes are bundled inside this skill so behavior is pinned to the installed version and works offline. Each prompt is self-contained: install commands, exit codes, and `AGENTS_SHIPGATE_AGENT_MODE=1` error handling are in the prompt itself.
+
+| Task | Recipe |
+|---|---|
+| Decide whether Shipgate should run at all (apply `docs/triggers.json` against the PR) | [`prompts/decide-shipgate-relevance.md`](prompts/decide-shipgate-relevance.md) |
+| Bootstrap a repo (install, init, scan, report) | [`prompts/add-shipgate-to-repo.md`](prompts/add-shipgate-to-repo.md) |
+| Add Shipgate to CI for the first time (advisory, PR comment) | See "First-time CI setup" below; copy [`ci-recipes/advisory-pr-comment.yml`](ci-recipes/advisory-pr-comment.yml) |
+| Fix the highest-severity finding | [`prompts/fix-top-finding.md`](prompts/fix-top-finding.md) |
+| Recommend fixes across all active findings | [`prompts/recommend-fixes.md`](prompts/recommend-fixes.md) |
+| Explain a single finding in user-facing prose (3–5 sentences for a PR comment / chat reply) | [`prompts/explain-finding-to-user.md`](prompts/explain-finding-to-user.md); pair with `agents-shipgate explain-finding <fingerprint> --from agents-shipgate-reports/report.json --json` |
+| Triage a suspected false positive | [`prompts/triage-false-positive.md`](prompts/triage-false-positive.md) |
+| Promote advisory CI to strict CI (assumes advisory is already running) | [`prompts/stabilize-strict-mode.md`](prompts/stabilize-strict-mode.md) |
+| Upgrade agents-shipgate version | [`prompts/upgrade-shipgate-version.md`](prompts/upgrade-shipgate-version.md) |
+
+Always:
+
+1. Set `AGENTS_SHIPGATE_AGENT_MODE=1` so errors emit a `next_action` JSON line on stderr.
+2. Parse `agents-shipgate-reports/report.json` (stable contract), not the markdown.
+3. Confirm with the user before any command that writes files (`init --write`, `baseline save`).
+
+## First-time CI setup (advisory)
+
+If the user has no Shipgate CI yet, default to **advisory** mode — never strict, never with a baseline. The promotion path comes later, only after findings have been reviewed.
+
+1. Confirm the repo has `shipgate.yaml` and a clean local scan (`agents-shipgate scan -c shipgate.yaml --ci-mode advisory` exits `0`). If not, run the bootstrap recipe first.
+2. Create `.github/workflows/agents-shipgate.yml` from [`ci-recipes/advisory-pr-comment.yml`](ci-recipes/advisory-pr-comment.yml). It runs on every pull request, posts a summary comment, uploads the report as an artifact, and never fails the job.
+3. Confirm `permissions: pull-requests: write` is acceptable to the user before committing — required for the PR comment.
+4. Push and open a test PR. Verify the agents-shipgate comment appears.
+5. **Stop here.** Promotion to strict mode is a separate task — only run [`prompts/stabilize-strict-mode.md`](prompts/stabilize-strict-mode.md) after the user has reviewed the advisory output and decided which findings they accept.
+
+For non-GitHub CI (GitLab, CircleCI, Jenkins, Azure Pipelines, Buildkite, Bitbucket, pre-commit) refer to https://github.com/ThreeMoonsLab/agents-shipgate/tree/main/examples or `docs/integrations.md` in the upstream repo. Always start in advisory mode.
+
+## Stable contracts (rely on these)
+
+- **CLI surface** is frozen for `0.x` — see https://github.com/ThreeMoonsLab/agents-shipgate/blob/main/STABILITY.md.
+- **Installed CLI contract**: when available, run `agents-shipgate contract --json` to verify local schema versions, `release_decision.decision`, and manual-review signal fields. Older installs should use [`docs/agent-contract-current.md`](https://github.com/ThreeMoonsLab/agents-shipgate/blob/main/docs/agent-contract-current.md) or upgrade before automating against the local contract command.
+- **Report JSON**: `report_schema_version: "0.20"`. Read `release_decision.decision` first for release gating; use `agent_summary` / `findings[].agent_action` for agent routing and `reviewer_summary` for the human-review entry point. To filter findings by source reliability, use `agents-shipgate findings --from agents-shipgate-reports/report.json --provenance-kind keyword_heuristic,regex_heuristic --json`; it reads `findings[].provenance_kind` (v0.15+) as a reviewer triage signal only, independent of `confidence` and never as a gate input. Do not gate on `summary.status`; it is legacy and baseline-blind. The full field list lives in [`docs/agent-contract-current.md`](https://github.com/ThreeMoonsLab/agents-shipgate/blob/main/docs/agent-contract-current.md#read-these-first-for-release-gating), and reports validate against [`docs/report-schema.v0.20.json`](https://github.com/ThreeMoonsLab/agents-shipgate/blob/main/docs/report-schema.v0.20.json).
+- **Release Evidence Packet**: `agents-shipgate-reports/packet.{md,json,html}` (and `packet.pdf` with the `[pdf]` extras) is emitted alongside the report by default. The packet has fixed reviewer sections governed by [`docs/packet-schema.v0.6.json`](https://github.com/ThreeMoonsLab/agents-shipgate/blob/main/docs/packet-schema.v0.6.json) (latest; v0.6 adds the top-level `evidence_matrix` compact review section AND `ReleaseDecisionItem.{source, policy_evidence_source}` for reviewer-grade dual-source provenance over the v0.5 baseline). See [STABILITY.md §Release Evidence Packet](https://github.com/ThreeMoonsLab/agents-shipgate/blob/main/STABILITY.md#release-evidence-packet-v06). Use the packet for reviewer-shaped output; use the report for finding details.
+- **Single source of truth for the contract**: [`docs/agent-contract-current.md`](https://github.com/ThreeMoonsLab/agents-shipgate/blob/main/docs/agent-contract-current.md). When the schema bumps, that file updates first.
+- **Exit codes**: `0` pass, `2` config error, `3` parse error, `4` other error, `20` strict-mode gate failure.
+- **Check IDs** (e.g. `SHIP-POLICY-APPROVAL-MISSING`) are stable; new ones may be added but existing ones will not be renamed or repurposed.
+
+## Boundaries (do not violate)
+
+- Do not claim a finding is fixed without re-running `agents-shipgate scan` and showing the diff in counts.
+- Do not silently suppress findings — `checks.ignore` requires a `reason` and the manifest validator rejects empty reasons.
+- Do not commit `agents-shipgate-reports/` — it's regenerated each run; add it to `.gitignore`.
+- Do not run `agents-shipgate baseline save` until the user has reviewed the initial findings; baselining ratchets in noise.
+- Do not enable strict CI as the first CI step. Always start advisory.
+- Do not modify checks in `agents-shipgate`'s own source — that's upstream repo work.
+
+## If something errors out
+
+Set `AGENTS_SHIPGATE_AGENT_MODE=1` and re-run. The CLI appends a JSON line to stderr with `{error, message, next_action}`. Follow the `next_action`. The error kinds emitted by the current CLI:
+
+| Error kind | Fix |
+|---|---|
+| `config_error` | Manifest is missing, malformed, or fails validation. Common cause: no `shipgate.yaml` yet — run `agents-shipgate init --workspace . --write`. |
+| `config_already_exists` | `init --write` was run with an existing `shipgate.yaml`. Edit the file in place or remove it before re-running. |
+| `input_parse_error` | A file referenced from the manifest (`tool_sources[].path`, baseline, policy pack) is missing, malformed, or resolves outside the manifest directory. Correct the path. |
+| `unknown_check_id` | The check ID passed to `explain` does not exist. Run `agents-shipgate list-checks --json` to enumerate. |
+| `other_error` / `internal_error` | Unexpected failure. Re-run with `--verbose` and include the output if filing an issue. |
+
+For deeper troubleshooting see https://github.com/ThreeMoonsLab/agents-shipgate/blob/main/docs/troubleshooting.md.

adoption-kits/claude-code-skill/ci-recipes/advisory-pr-comment.yml

@@ -0,0 +1,26 @@
+# Advisory PR comment.
+# Recommended starting point — runs the scanner on every PR, posts a summary
+# comment, uploads the report as an artifact, and never fails the job.
+name: Agents Shipgate (advisory)
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  shipgate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: ThreeMoonsLab/agents-shipgate@v{{ shipgate_version }}
+        with:
+          ci_mode: advisory
+          diff_base: target
+          pr_comment: 'true'
+          shipgate_version: '{{ shipgate_version }}'