The Legible Repo: Product Quality for Humans and AI Agents
Linters check your code. Test suites check your source tree. Nothing checks whether your project is legible — whether a stranger arriving cold, human or AI agent, can get from “found the repo” to “it worked on my machine” in ten minutes.
This series covers the quality layer your CI can’t see: one silent failure per episode, the incident that proves it, and one runnable command that catches it. The tooling behind the series is Invigil (Apache-2.0), a CI gate that grades repos on the promises strangers rely on — and grades itself on every pull request.
It runs in three parts. Part I — The Doctrine is for maintainers: the legibility failures your CI never catches. Part II — Build On It is for collaborators: extend the gate, understand the fix engine, and ship your first contribution. Part III — Adopt At Scale is for enterprises: supply-chain evidence, org-wide rollout, and audit-ready compliance.
New episodes publish weekly, Thursday mornings IST.
Episodes
| EP | Part | Episode | Status |
|---|---|---|---|
| EP01 | I · Doctrine | Product Quality vs Code Quality: Why Your Green CI Still Loses Users | Published |
| EP02 | I · Doctrine | How to Test Your Published PyPI Package — Before a Stranger Does | Coming up |
| EP03 | I · Doctrine | llms.txt and AGENTS.md: Is Your Repo Legible to AI Agents? | Coming up |
| EP04 | I · Doctrine | Actionable Error Messages: Correlation IDs and the Users You Never Hear From | Coming up |
| EP05 | I · Doctrine | 5 Repo Quality Gaps Every Maintainer Misses | Coming up |
| EP06 | II · Build On It | Write Your Own Quality Check: Invigil’s Plugin Architecture in One File | Coming up |
| EP07 | II · Build On It | How the Fix Engine Works: Safe Mutators and Single-Pass Rules | Coming up |
| EP08 | II · Build On It | Fix-by-PR Without the Noise: Mechanical Fixes on a Stable Branch | Coming up |
| EP09 | II · Build On It | Your First Merged PR to Invigil: From good-first-issue to Release Credit | Coming up |
| EP10 | III · Adopt At Scale | Supply-Chain Evidence as a Merge Gate: Scorecard, Signed Releases, SBOM | Coming up |
| EP11 | III · Adopt At Scale | Rolling Invigil Across an Org: Profiles and Progressive Enforcement | Coming up |
| EP12 | III · Adopt At Scale | Declaring Your Dependencies: A Supply-Chain Governance Gate | Coming up |
| EP13 | III · Adopt At Scale | Audit-Ready by Default: Mapping Invigil to SOC 2, SSDF, CISSP | Coming up |
Try the gate now
pip install invigil
invigil score .
Every failing check prints the exact fix. Start in report-only mode; enforce when the grade stabilizes.
Collaborate
Invigil is built in the open and looking for contributors — good-first-issues with acceptance criteria and a local verify command are waiting at github.com/invigil/invigil. First-time contributors get fast reviews and release-notes credit. If a check you need doesn’t exist, open a Discussion — that conversation is usually the best first issue.
Get each episode in your inbox when it publishes → subscribe