Skip to content
Back to search

invigil

Linters check your code. Invigil checks whether your repo is legible — to newcomers and to AI agents.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/invigil--invigil/badge.svg)](/listings/invigil--invigil)

HTML

<a href="/listings/invigil--invigil"><img src="/api/listings/invigil--invigil/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Published channels — pick the one that matches where you run it:

| Channel | Where it fits | One-liner | |---|---|---| | **PyPI** | local runs, Python-friendly CI | `pip install invigil` | | **GitHub Action** | GitHub PRs | `uses: invigil/invigil@v1` | | **Docker (ghcr)** | GitLab, Jenkins, any non-Python CI | `docker run --rm -v "$PWD:/repo" ghcr.io/invigil/invigil score /repo` | | **pre-commit** | offline checks on every commit | hooks `invigil-layout`, `invigil-secrets` (below) | | **MCP server** | agents (Claude Code, any MCP client) | `pip install "invigil[mcp]"` → `invigil mcp` |

Every release ships all of it signed: cosign-signed wheel, sdist, and container image, plus an SPDX SBOM — verifiable with `cosign verify` against the GitHub OIDC identity.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 296 lines
  1. # Invigil
  2. **Verify the path from installation to first successful use—for people and agents.**
  3. [![CI](https://github.com/invigil/invigil/actions/workflows/ci.yml/badge.svg)](https://github.com/invigil/invigil/actions/workflows/ci.yml)
  4. [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
  5. [![PyPI](https://img.shields.io/pypi/v/invigil)](https://pypi.org/project/invigil/)
  6. [![GitHub Marketplace](https://img.shields.io/badge/Marketplace-Invigil-2088FF?logo=githubactions&logoColor=white)](https://github.com/marketplace/actions/invigil-product-quality-gate)
  7. [![Docker](https://img.shields.io/badge/ghcr-invigil%2Finvigil-2496ed?logo=docker&logoColor=white)](https://github.com/invigil/invigil/pkgs/container/invigil)
  8. [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/invigil/invigil/badge)](https://scorecard.dev/viewer/?uri=github.com/invigil/invigil)
  9. [![Invigil grade](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/invigil/invigil/main/badges/invigil.json)](https://github.com/invigil/invigil)
  10. [![AI-ready](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/invigil/invigil/main/badges/invigil-ai.json)](https://github.com/invigil/invigil#when-your-user-is-an-agent)
  11. A package can install successfully and still fail its first useful command. Invigil
  12. combines repository-quality checks with a Cold-Start Gate that exercises declared
  13. operations and reports the evidence needed to diagnose failures.
  14. **New in 1.8.0** — install a candidate Python wheel outside its source checkout,
  15. run its first useful command, and save the result with the wheel’s SHA-256.
  16. ## Try the first-use demo
  17. On Linux with Python 3.11+ and venv support, run the two wheel fixtures:
  18. ```bash
  19. git clone --branch v1.8.0 https://github.com/invigil/invigil.git
  20. cd invigil
  21. python3 -m venv .venv
  22. .venv/bin/python -m pip install invigil==1.8.0
  23. .venv/bin/python examples/first-use-demo/run.py
  24. ```
  25. The demo runs offline and checks real wheels. Both install; one omits a required data file and fails its first-use command. Adding that file makes the same
  26. check pass. It prints the failure and saves JSON reports in a temporary directory.
  27. This is a synthetic example, not a claim about an upstream project's current release.
  28. [Demo details](examples/first-use-demo/README.md) ·
  29. [Verify your own wheel](docs/cli-reference.md#invigil-stranger-path) ·
  30. [CI workflow template](examples/wheel-first-use.yml)
  31. Wheel verification requires an explicit command and optional expected output. A successful
  32. run proves that operation worked in the recorded environment; it is not a general
  33. release-safety guarantee. Run unfamiliar artifacts in disposable workers without
  34. credentials—a Python venv is not a security sandbox.
  35. > *invigilate* — to watch over an exam and enforce its rules.
  36. ---
  37. ## How Invigil fits in your stack
  38. Invigil does not replace your existing tools; it covers the product-quality gaps they leave behind.
  39. | Capability | Role |
  40. |---|---|
  41. | Repository scorecard | Checks documentation, configuration and quality conventions; suggests fixes |
  42. | Published-artifact Cold-Start Gate | Exercises configured package/container operations and HTTP probes |
  43. | Local-wheel first use | Verifies the candidate artifact; records its hash, phases and dependencies |
  44. | Existing linters, scanners and tests | Continue checking code correctness and security alongside Invigil |
  45. A clean-install smoke script can detect the same packaging defects. Invigil aims
  46. to make that workflow easier to configure and its reports consistent across projects.
  47. ---
  48. ## Why
  49. The scorecard checks whether the project is legible to newcomers and agents.
  50. Every failing static check includes a suggested command or edit. Execution reports
  51. retain the failed step and output; they cannot infer every application's root cause.
  52. The [seven Gates](docs/doctrine.md) cover onboarding, errors, artifact verification,
  53. supply-chain evidence, audience documentation, contribution and adoption. A grade
  54. summarizes implemented repository checks; it does not establish that an artifact
  55. was executed successfully. Use the Cold-Start Gate for execution evidence.
  56. ## Install
  57. Published channels — pick the one that matches where you run it:
  58. | Channel | Where it fits | One-liner |
  59. |---|---|---|
  60. | **PyPI** | local runs, Python-friendly CI | `pip install invigil` |
  61. | **GitHub Action** | GitHub PRs | `uses: invigil/invigil@v1` |
  62. | **Docker (ghcr)** | GitLab, Jenkins, any non-Python CI | `docker run --rm -v "$PWD:/repo" ghcr.io/invigil/invigil score /repo` |
  63. | **pre-commit** | offline checks on every commit | hooks `invigil-layout`, `invigil-secrets` (below) |
  64. | **MCP server** | agents (Claude Code, any MCP client) | `pip install "invigil[mcp]"` → `invigil mcp` |
  65. Every release ships all of it signed: cosign-signed wheel, sdist, and container image, plus an
  66. SPDX SBOM — verifiable with `cosign verify` against the GitHub OIDC identity.
  67. ## Quick Start
  68. The commands below run the repository scorecard. The demo above exercises a built wheel.
  69. Run it locally on any repo:
  70. ```bash
  71. pip install invigil
  72. invigil score . # human-readable scorecard + the exact fix for every failure
  73. invigil score . --format markdown # a PR-comment-ready table
  74. invigil score . --format json # machine-readable
  75. ```
  76. Add it to CI as a report-only gate (posts a scorecard comment + badge, never blocks a PR):
  77. ```yaml
  78. # .github/workflows/quality-gate.yml
  79. name: Quality gate
  80. on: [pull_request]
  81. permissions: { contents: read, pull-requests: write }
  82. jobs:
  83. invigil:
  84. runs-on: ubuntu-latest
  85. steps:
  86. - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
  87. - uses: invigil/invigil@933dc13cedceac9f75c2ccf9b66aa1f6851fa727 # v1.8.0
  88. with:
  89. enforce: "false" # flip to true once the grade is stable
  90. ```
  91. Flip `enforce: "true"` (or set `project.enforce: true` in `.invigil.yml`) when you're ready for
  92. it to block merges below the target gate.
  93. > **Why the SHAs?** `invigil/invigil@v1` works and tracks the latest v1.x.y, but Invigil's own
  94. > `actions-sha-pinned` check (G3) fails floating tags — including its own. Pin, and let
  95. > Dependabot bump the pins; the trailing comment is what it reads.
  96. The action exposes the report and both badges as step outputs — pipe the scorecard into the job
  97. summary, publish the badge JSON wherever shields.io can reach it:
  98. ```yaml
  99. - uses: invigil/invigil@933dc13cedceac9f75c2ccf9b66aa1f6851fa727 # v1.8.0
  100. id: invigil
  101. with: { comment: "false" }
  102. - run: cat "${{ steps.invigil.outputs.report }}" >> "$GITHUB_STEP_SUMMARY"
  103. # outputs.badge → grade badge JSON · outputs.ai-badge → ai-ready badge JSON
  104. ```
  105. ## How it works
  106. Two layers, matching the doctrine:
  107. - **Static Doctrine Scorecard** (every PR, seconds) — inspects the repo filesystem and GitHub
  108. metadata: LICENSE, README length, `.env.example`, a deep-health endpoint, a global error-id
  109. handler, SHA-pinned actions, an enforced lockfile, a coverage gate, a daily published-artifact
  110. smoke test, ≥5 good-first-issues, docs index, `llms.txt`/`AGENTS.md`, and more. Emits text /
  111. JSON / Markdown / a shields.io badge.
  112. - **Cold-Start Gate** (nightly, reusable — `invigil stranger`) — on a clean runner, installs
  113. and boots configured published artifacts and probes their declared surfaces.
  114. The new local-wheel path additionally bounds setup/install/first use with one
  115. per-wheel budget and records phase results; legacy paths retain their behavior. Web services get HTTP probes; a CLI image (an artifact with a `command:`)
  116. is run to completion and must exit 0. One reusable workflow replaces the 60-line
  117. `smoke-published.yml` every repo copy-pastes:
  118. ```yaml
  119. # .github/workflows/stranger-gate.yml
  120. name: Cold-start gate
  121. on:
  122. schedule: [{ cron: "0 3 * * *" }]
  123. workflow_dispatch:
  124. jobs:
  125. stranger:
  126. uses: invigil/invigil/.github/workflows/stranger-gate.yml@933dc13cedceac9f75c2ccf9b66aa1f6851fa727 # v1.8.0
  127. ```
  128. ### Fix by PR
  129. The optional [fix workflow](.github/workflows/fix-pr.yml) applies mechanical fixes
  130. on a work branch and opens one batched PR. It uses `invigil score --fix --pr-mode`;
  131. protected-branch safeguards remain in place. Closing its PR without merging is
  132. respected until the work branch is deleted. See the
  133. [CLI reference](docs/cli-reference.md) for configuration and limits.
  134. ## Configuration
  135. Drop a `.invigil.yml` at the repo root. It's optional for the static scorecard (sensible
  136. defaults apply) and required for the Cold-Start Gate (it declares what to boot and probe). Full
  137. schema in [`schema/invigil.schema.json`](schema/invigil.schema.json); examples in
  138. [`examples/`](examples/).
  139. ```yaml
  140. version: 1
  141. project:
  142. name: my-app
  143. language: python
  144. min_gate: G4
  145. enforce: false
  146. artifacts:
  147. - type: pypi
  148. name: "my-app[all]"
  149. - type: ghcr
  150. image: ghcr.io/me/my-app:latest
  151. port: 8000
  152. probes:
  153. - { url: "/", expect_status: 200 }
  154. - { url: "/api/things", expect_json_count: { min: 5 } }
  155. boot_budget_minutes: 10
  156. ```
  157. ## Lightweight & modular
  158. A gate developers bypass is dead weight, so Invigil is built for zero friction:
  159. - **Fast offline groups for pre-commit** — each check is tagged `local`/`network`/`heavy`.
  160. `invigil check layout` runs the filesystem checks with no network in ~120ms:
  161. ```yaml
  162. # .pre-commit-config.yaml
  163. - repo: https://github.com/invigil/invigil
  164. rev: v1 # tracks the latest v1.x.y
  165. hooks: [{ id: invigil-layout }, { id: invigil-secrets }]
  166. ```
  167. Heavier, network-bound checks (`scorecard`, the Cold-Start Gate) stay in CI.
  168. `invigil score --offline` / `--layer local` / `--group supply-chain` slice it any way.
  169. - **It bends instead of forking.** `profile: strict | progressive | light`, per-check
  170. `weights`, `optional` (ding without gating), `thresholds.fail_on` — make it *your* doctrine.
  171. - **Resilient by design.** A scorecard.dev timeout is a SKIP excluded from the grade — never a
  172. false A-to-C downgrade, never a crashed build.
  173. → [The doctrine and the Gates](docs/doctrine.md) covers both in full.
  174. ## When your user is an agent
  175. Legibility now has two audiences. The reader arriving cold at your repo is, more often than
  176. not, an AI agent: it has a context window instead of patience, exit codes instead of
  177. intuition, and it acts only on what the repo states machine-readably. The `ai` check group
  178. grades that surface — not just *presence* of `llms.txt`/`AGENTS.md`, but whether an agent can
  179. actually act on them:
  180. | Check | The promise to the agent |
  181. |---|---|
  182. | `agents-md-actionable` | Your `AGENTS.md`/`CLAUDE.md` contains runnable fenced commands, not prose |
  183. | `llms-txt-shape` | `llms.txt` is spec-shaped and fits a 10 KB context budget |
  184. | `agent-context-fresh` | Agent instructions aren't 90+ days staler than the source they describe |
  185. | `readme-heading-hierarchy` | The README chunks cleanly (one H1, real H2 sections) |
  186. | `exit-codes-documented` | A CLI's exit codes are enumerated — agents branch on codes, not prose |
  187. | `llms-no-secrets` | The machine-readable surface leaks no credentials |
  188. | `agent-scope-visibility` | Agent code declares its tool inventory (blast-radius precondition) |
  189. Two artifacts fall out of it. **`invigil score --format llm`** — a deterministic report under
  190. ~1 KB, built to be read *by* an agent: a healthy repo costs it two lines of context. And an
  191. **`ai-ready` badge**, a shields.io endpoint you can put in your own README:
  192. ```bash
  193. invigil score . --format ai-badge --output badges/ai-ready.json # commit this
  194. ```
  195. ```markdown
  196. ![AI-ready](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/OWNER/REPO/main/badges/ai-ready.json)
  197. ```
  198. In CI the Action emits it for you — `steps.<id>.outputs.ai-badge` is the path to the same JSON.
  199. ### MCP server
  200. An editor agent can check a trusted checkout before a pull request. Start with
  201. `evaluate_repo`, preview proposed edits with `preview_fixes`, then call
  202. `check_group` after an edit to see the updated findings.
  203. Install with `pip install "invigil[mcp]==1.8.0"` and launch `invigil mcp` over stdio.
  204. Clients using `mcpServers` can launch the same version with `uvx`:
  205. ```json
  206. { "mcpServers": { "invigil": { "command": "uvx", "args": ["--from", "invigil[mcp]==1.8.0", "invigil", "mcp"] } } }
  207. ```
  208. The registry identifier is `mcp-name: io.github.invigil/invigil`.
  209. See the [MCP tool reference](docs/cli-reference.md#invigil-mcp) for arguments,
  210. defaults, results, and an example call.
  211. ## The doctrine
  212. *Absence of complaints is not absence of problems — silence is the loudest negative signal a
  213. project gets.* That's the Silent User Doctrine, and Invigil is its enforcement:
  214. [what the Gates mean and how to tune them](docs/doctrine.md).
  215. ## Stability
  216. Invigil is **Alpha**, and [`docs/stability.md`](docs/stability.md) says exactly what that
  217. buys you: the CLI, exit codes, JSON shape, badge JSON and MCP tools are stable enough to
  218. automate against; individual check verdicts are not, and every report carries a
  219. `doctrine_version` so you can tell *your repo regressed* from *the ruler moved*.
  220. ## Contributing
  221. Issues and PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) and
  222. [good first issues](https://github.com/invigil/invigil/labels/good%20first%20issue). Invigil
  223. grades itself in CI; self-score is currently report-only. See the scoped
  224. [beginner tasks](https://github.com/invigil/invigil/issues?q=is%3Aopen+label%3A%22good+first+issue%22)
  225. and [benchmark tasks](https://github.com/invigil/invigil/issues?q=is%3Aopen+label%3A%22help+wanted%22).
  226. ## License
  227. Apache-2.0 — see [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.