{
"markdown": "\n\n
✈️ pre-flight-check
\n\n### Stop your AI coding agent from declaring **\"done\"** on broken code.\n\nA universal quality gate that runs **Typecheck → Lint → Test → Security Audit**\nbefore any task is marked complete.\nAuto-detects Node.js, Python, Go, and Rust. Works with [10 AI coding tools](#-supported-ai-tools).\n\n
\n\n[](https://github.com/mirekondro/The-Pre-Flight-Check/actions/workflows/ci.yml)\n[](https://github.com/mirekondro/The-Pre-Flight-Check/releases)\n[](LICENSE)\n[](https://www.python.org/downloads/)\n[](#-how-it-works)\n\n
\n\n**[Website](https://mirekondro.github.io/The-Pre-Flight-Check/)** · **[Install](#-install)** · **[How it works](#-how-it-works)** · **[Supported AI tools](#-supported-ai-tools)** · **[Full guide](INSTALL.md)**\n\n> 🌐 The landing-page source now lives in [`site/`](site/) and auto-deploys to GitHub Pages.\n\n\n\n---\n\n```text\n ┌───────────┐ ┌──────┐ ┌──────┐ ┌────────────────┐\n → │ TYPECHECK │ → │ LINT │ → │ TEST │ → │ SECURITY AUDIT │ → ✅ cleared for takeoff\n └───────────┘ └──────┘ └──────┘ └────────────────┘\n ↓ first failure halts the pipeline → ❌ exit 1\n```\n\n## 🛑 The problem\n\nYour AI agent writes a function, watches it not throw at runtime, and reports \"done\" — while `tsc`\nwould have caught a type error in 50ms, `eslint` would have flagged dead code, and `pytest` would\nhave failed three tests.\n\n`pre-flight-check` closes that loop. **One command, four gates, structured failure output the agent\nhas to act on.** No more \"I've successfully implemented the feature!\" while the build is on fire.\n\n## 📦 Install\n\nPick the install path that matches your platform.\n\n\n🍎 macOS · 🐧 Linux (Homebrew)
\n\n```bash\nbrew tap mirekondro/pre-flight-check\nbrew install pre-flight-check\n```\n\n \n\n\n🪟 Windows (Scoop)
\n\n```powershell\nscoop bucket add pre-flight-check https://github.com/mirekondro/The-Pre-Flight-Check\nscoop install pre-flight-check\n```\n\n \n\n\n🐍 Any platform (pipx)
\n\n```bash\npipx install pre-flight-check\n```\n\n \n\n\n⚡ One-line install (no package manager)
\n\n```bash\n# macOS / Linux\ncurl -fsSL https://raw.githubusercontent.com/mirekondro/The-Pre-Flight-Check/main/install.sh | bash\n\n# Windows (PowerShell)\nirm https://raw.githubusercontent.com/mirekondro/The-Pre-Flight-Check/main/install.ps1 | iex\n```\n\n \n\n\n🤖 Claude Code plugin marketplace
\n\n```bash\nclaude plugin marketplace add mirekondro/The-Pre-Flight-Check\nclaude plugin install pre-flight-check\n```\n\n \n\nThen in any project:\n\n```bash\npre-flight-check init --tool claude # or cursor, codex, gemini, copilot, …\npre-flight-check init --tool all --project # install for every supported AI tool at once\n```\n\nRun it, or preview what it would run:\n\n```bash\npre-flight-check run # run every resolved gate (the default)\npre-flight-check run --only typecheck # run a single gate (also: lint, test, audit)\npre-flight-check run --skip audit # run everything except one\npre-flight-check doctor # show the runtime + stages + detected tools, run nothing\n```\n\nSee **[INSTALL.md](INSTALL.md)** for the full per-tool matrix and troubleshooting.\n\n## ⚙️ What it does\n\nWhen your AI agent says \"I'm done,\" it doesn't always mean the code works. `pre-flight-check`\ninterposes a strict, fail-fast pipeline:\n\n```text\nTypecheck → Lint → Test → Security Audit\n```\n\nThe first stage that fails **halts the pipeline**, prints a structured Markdown block, and exits `1`.\nThe agent reads that block and **must fix the exact error** before continuing.\n\nHere's what the agent actually sees on a failure:\n\n```text\n### ❌ PRE-FLIGHT FAILURE: TYPECHECK\n**Command Executed:** `npx --no-install tsc --noEmit`\n**Context for AI Fix:**\n\nsrc/auth/session.ts(42,18): error TS2345: Argument of type 'string | undefined'\nis not assignable to parameter of type 'string'.\n```\n\nIt knows: which **file** (`session.ts`), which **line** (`42:18`), which **rule** (`TS2345`), and\nwhat's wrong. No more \"I think the auth flow is implemented.\"\n\nOn success:\n\n```text\n### ✅ PRE-FLIGHT PASSED\nAll quality gates verified successfully.\n```\n\n## 🤖 Supported AI tools\n\n| Tool | Native delivery path | One-liner |\n|---|---|---|\n| **Claude Code** | `.claude/skills/pre-flight-check/` | `pre-flight-check init --tool claude` |\n| **OpenAI Codex / AGENTS.md** | `AGENTS.md` at repo root | `pre-flight-check init --tool codex --project` |\n| **Gemini CLI** | `GEMINI.md` + `gemini-extension.json` | `pre-flight-check init --tool gemini --project` |\n| **Cursor** | `.cursor/rules/pre-flight-check.mdc` | `pre-flight-check init --tool cursor --project` |\n| **GitHub Copilot** | `.github/copilot-instructions.md` | `pre-flight-check init --tool copilot --project` |\n| **Windsurf** | `.windsurf/rules/pre-flight-check.md` | `pre-flight-check init --tool windsurf --project` |\n| **Cline** | `.clinerules/pre-flight-check.md` | `pre-flight-check init --tool cline --project` |\n| **Kiro** | `.kiro/steering/pre-flight-check.md` | `pre-flight-check init --tool kiro --project` |\n| **Roo Code** | `.roo/rules/pre-flight-check.md` | `pre-flight-check init --tool roo --project` |\n| **Agent Skills standard** | `.agents/skills/pre-flight-check/` | `pre-flight-check init --tool agents-skills --project` |\n\n> Several tools (Codex, Copilot Coding Agent, Windsurf, Kiro) read `AGENTS.md` at the repo root as a\n> fallback. Installing `--tool codex` alone gives broad ecosystem coverage.\n\n## ✅ What it checks\n\n| Stage | Node.js | Python | Go | Rust |\n|---|---|---|---|---|\n| **1. Typecheck** | `tsc --noEmit` | `mypy .` | `go build ./...` | `cargo check` |\n| **2. Lint** | `eslint .` | `ruff` → `flake8` | `golangci-lint` → `go vet` | `cargo clippy` |\n| **3. Test** | `jest` / `vitest` | `pytest -q` | `go test ./...` | `cargo test` |\n| **4. Security Audit** | `npm audit` | `pip-audit` → `bandit` | `govulncheck` | `cargo audit` |\n\n> Node and Python prefer your existing `package.json` / Poetry scripts. Stages whose tools aren't\n> installed are **skipped silently** — no false positives from missing optional gear.\n\n## 🔍 How it works\n\n- **🔎 Auto-detects** the runtime from manifest files (`package.json`, `pyproject.toml`, `requirements.txt`, `go.mod`, `Cargo.toml`, …).\n- **📦 Picks the right package manager** from the lockfile: `pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `package-lock.json` → npm.\n- **🛠️ Prefers your existing scripts** — if `package.json` defines `lint`, the pipeline calls `npm run lint` instead of invoking `eslint` directly.\n- **🛑 Halts on first failure** — no point linting code that doesn't typecheck.\n- **🚫 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.\n\n> The whole engine is **one Python file with zero runtime dependencies.** Audit it in five minutes.\n\n## ⚙️ Configuration (optional)\n\nZero config by default. To override a command, disable a gate, or add one, drop\na `[tool.pre-flight-check]` table in `pyproject.toml` or a `.pre-flight-check.toml`:\n\n```toml\n# .pre-flight-check.toml\ndisable = [\"audit\"] # skip a gate entirely\n\n[commands] # override or add a gate's command\nlint = \"biome check .\"\ntest = \"vitest run --coverage\"\n```\n\nPreview the resolved plan any time with `pre-flight-check doctor`. (Config\nparsing uses `tomllib`, so it needs the engine running on Python 3.11+; older\nengines simply ignore it.)\n\n## 📋 Requirements\n\n- **Python 3.8+** on `PATH` (the engine — no other Python dependencies)\n- Your project's existing dev tooling — `tsc`, `eslint`, `pytest`, etc. We orchestrate, we don't replace.\n\nThat's it.\n\n## 🚦 Project status\n\n**Stable.** Used in production on the maintainer's own projects. The failure-block Markdown format\nis part of the public contract — any change to its shape is a major version bump.\n\nContributions welcome — see **[CONTRIBUTING.md](CONTRIBUTING.md)**. The bar for new features is high;\nthe bar for new runtime adapters (Go, Rust, Ruby, …) and additional AI-tool adapters is low.\n\n## 📄 License\n\n[MIT](LICENSE)\n\n---\n\n\n
If pre-flight-check catches a bug for you that would have shipped —\n⭐ star the repo so the next developer finds it too.\n