pre-flight-check 1.4.0

Fail-fast quality gate for AI coding agents: Typecheck → Lint → Test → Security Audit. Stops the agent declaring 'done' on broken code.

✈️ pre-flight-check

Stop your AI coding agent from declaring "done" on broken code.

A universal quality gate that runs Typecheck → Lint → Test → Security Audit before any task is marked complete. Auto-detects Node.js, Python, Go, and Rust. Works with 10 AI coding tools.

Website  ·  Install  ·  How it works  ·  Supported AI tools  ·  Full guide

🌐 The landing-page source now lives in site/ and auto-deploys to GitHub Pages.

---

        ┌───────────┐   ┌──────┐   ┌──────┐   ┌────────────────┐
   →    │ TYPECHECK │ → │ LINT │ → │ TEST │ → │ SECURITY AUDIT │ → ✅ cleared for takeoff
        └───────────┘   └──────┘   └──────┘   └────────────────┘
              ↓ first failure halts the pipeline → ❌ exit 1

🛑 The problem

Your AI agent writes a function, watches it not throw at runtime, and reports "done" — while tsc would have caught a type error in 50ms, eslint would have flagged dead code, and pytest would have failed three tests.

pre-flight-check closes that loop. One command, four gates, structured failure output the agent has to act on. No more "I've successfully implemented the feature!" while the build is on fire.

📦 Install

Pick the install path that matches your platform.

🍎 macOS · 🐧 Linux (Homebrew)

brew tap mirekondro/pre-flight-check
brew install pre-flight-check

🪟 Windows (Scoop)

scoop bucket add pre-flight-check https://github.com/mirekondro/The-Pre-Flight-Check
scoop install pre-flight-check

🐍 Any platform (pipx)

pipx install pre-flight-check

⚡ One-line install (no package manager)

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/mirekondro/The-Pre-Flight-Check/main/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/mirekondro/The-Pre-Flight-Check/main/install.ps1 | iex

🤖 Claude Code plugin marketplace

claude plugin marketplace add mirekondro/The-Pre-Flight-Check
claude plugin install pre-flight-check

Then in any project:

pre-flight-check init --tool claude          # or cursor, codex, gemini, copilot, …
pre-flight-check init --tool all --project   # install for every supported AI tool at once

Run it, or preview what it would run:

pre-flight-check run                     # run every resolved gate (the default)
pre-flight-check run --only typecheck    # run a single gate (also: lint, test, audit)
pre-flight-check run --skip audit        # run everything except one
pre-flight-check doctor                  # show the runtime + stages + detected tools, run nothing

See INSTALL.md for the full per-tool matrix and troubleshooting.

⚙️ What it does

When your AI agent says "I'm done," it doesn't always mean the code works. pre-flight-check interposes a strict, fail-fast pipeline:

Typecheck → Lint → Test → Security Audit

The first stage that fails halts the pipeline, prints a structured Markdown block, and exits 1. The agent reads that block and must fix the exact error before continuing.

Here's what the agent actually sees on a failure:

### ❌ PRE-FLIGHT FAILURE: TYPECHECK
**Command Executed:** `npx --no-install tsc --noEmit`
**Context for AI Fix:**

src/auth/session.ts(42,18): error TS2345: Argument of type 'string | undefined'
is not assignable to parameter of type 'string'.

It knows: which file (session.ts), which line (42:18), which rule (TS2345), and what's wrong. No more "I think the auth flow is implemented."

On success:

### ✅ PRE-FLIGHT PASSED
All quality gates verified successfully.

🤖 Supported AI tools

Tool	Native delivery path	One-liner
Claude Code	.claude/skills/pre-flight-check/	pre-flight-check init --tool claude
OpenAI Codex / AGENTS.md	AGENTS.md at repo root	pre-flight-check init --tool codex --project
Gemini CLI	GEMINI.md + gemini-extension.json	pre-flight-check init --tool gemini --project
Cursor	.cursor/rules/pre-flight-check.mdc	pre-flight-check init --tool cursor --project
GitHub Copilot	.github/copilot-instructions.md	pre-flight-check init --tool copilot --project
Windsurf	.windsurf/rules/pre-flight-check.md	pre-flight-check init --tool windsurf --project
Cline	.clinerules/pre-flight-check.md	pre-flight-check init --tool cline --project
Kiro	.kiro/steering/pre-flight-check.md	pre-flight-check init --tool kiro --project
Roo Code	.roo/rules/pre-flight-check.md	pre-flight-check init --tool roo --project
Agent Skills standard	.agents/skills/pre-flight-check/	pre-flight-check init --tool agents-skills --project

Several tools (Codex, Copilot Coding Agent, Windsurf, Kiro) read AGENTS.md at the repo root as a fallback. Installing --tool codex alone gives broad ecosystem coverage.

✅ What it checks

Stage	Node.js	Python	Go	Rust
1. Typecheck	tsc --noEmit	mypy .	go build ./...	cargo check
2. Lint	eslint .	ruff → flake8	golangci-lint → go vet	cargo clippy
3. Test	jest / vitest	pytest -q	go test ./...	cargo test
4. Security Audit	npm audit	pip-audit → bandit	govulncheck	cargo audit

Node and Python prefer your existing package.json / Poetry scripts. Stages whose tools aren't installed are skipped silently — no false positives from missing optional gear.

🔍 How it works

• 🔎 Auto-detects the runtime from manifest files (package.json, pyproject.toml, requirements.txt, go.mod, Cargo.toml, …).
• 📦 Picks the right package manager from the lockfile: pnpm-lock.yaml → pnpm, yarn.lock → yarn, package-lock.json → npm.
• 🛠️ Prefers your existing scripts — if package.json defines lint, the pipeline calls npm run lint instead of invoking eslint directly.
• 🛑 Halts on first failure — no point linting code that doesn't typecheck.
• 🚫 Forbids escape hatches. The instruction file the AI agent reads (SKILL.md, AGENTS.md, .cursorrules/*.mdc, etc.) explicitly bans // @ts-ignore, # type: ignore, deleting failing tests, adding to ignore lists, and other ways to mark the gate green without fixing the bug.

The whole engine is one Python file with zero runtime dependencies. Audit it in five minutes.

⚙️ Configuration (optional)

Zero config by default. To override a command, disable a gate, or add one, drop a [tool.pre-flight-check] table in pyproject.toml or a .pre-flight-check.toml:

# .pre-flight-check.toml
disable = ["audit"]            # skip a gate entirely

[commands]                     # override or add a gate's command
lint = "biome check ."
test = "vitest run --coverage"

Preview the resolved plan any time with pre-flight-check doctor. (Config parsing uses tomllib, so it needs the engine running on Python 3.11+; older engines simply ignore it.)

📋 Requirements

• Python 3.8+ on PATH (the engine — no other Python dependencies)
• Your project's existing dev tooling — tsc, eslint, pytest, etc. We orchestrate, we don't replace.

That's it.

🚦 Project status

Stable. Used in production on the maintainer's own projects. The failure-block Markdown format is part of the public contract — any change to its shape is a major version bump.

Contributions welcome — see CONTRIBUTING.md. The bar for new features is high; the bar for new runtime adapters (Go, Rust, Ruby, …) and additional AI-tool adapters is low.

📄 License

MIT

---

_{If pre-flight-check catches a bug for you that would have shipped — ⭐ star the repo so the next developer finds it too.}