Preflight

A Claude Code plugin that catches the bugs AI coding agents actually make.

What It Does

Preflight is a 4-gate verification protocol that runs before and after every code change. It maps bugs to 7 cognitive reasoning flaws — the systematic errors that LLMs make when generating code. Not pattern matching. Metacognition.

The protocol took code quality from 60% to 99% in production use.

The 4 Gates

Gate	Question	Catches
1. State Assumptions	What are you depending on that you haven't written down?	Unstated assumption drift
2. Don't Claim Unverified	Have you verified this, or are you just confident?	Confidence bias
3. More Than Happy Path	What happens when inputs are empty, null, enormous, or wrong?	Happy-path fixation
4. Under What Conditions	When does this work? When does it break?	Implementation without comprehension

The 7 Flaws

1. Unstated Assumptions — implicit dependencies
2. Confidence Bias — certainty without evidence
3. Happy-Path Fixation — only the primary flow handled
4. Boundary Blindness — edge cases ignored
5. Temporal Ignorance — race conditions, ordering, lifecycle
6. Error Amnesia — exceptions swallowed or half-handled
7. Abstraction Leak — implementation details assumed stable

Install

From marketplace (when published)

/plugin install Preflight

Local development

git clone https://github.com/AnnulusLabs/preflight.git
claude --plugin-dir ./Preflight

Usage

Automatic (always on)

The Preflight protocol skill loads as reference context. Claude applies the 4-gate protocol to every code change. PostToolUse and PreToolUse hooks fire at every Write, Edit, and Bash call.

Skills

/preflight verify <file>         full 4-gate audit on a file or function
/preflight scan <file>           automated 7-flaw scan, structured findings
/preflight scan .                scan all source files in current directory
/preflight diff                  scan the current git diff (unstaged + staged)
/preflight diff --staged         scan staged changes only (pre-commit)
/preflight flaw <1-7>            deep reference for one specific flaw
/preflight flaw temporal         flaw by name (partial match)
/preflight report                full project-wide verification report
/preflight report --json         JSON output for CI/CD pipelines
/preflight teach <flaw>          before/after examples for a flaw
/preflight teach 6 go            examples in a specific language
/preflight config show           show current config with suggested JSON to change each setting
/preflight config init           create .preflight.json with defaults
/preflight config set <k> <v>    update a configuration key (applied in one call)

Specialized Agents

/preflight:reviewer              general 4-gate review on diffs or files
/preflight:security-reviewer     auth, crypto, injection, input validation
/preflight:api-reviewer          REST/GraphQL/gRPC contract verification
/preflight:concurrency-reviewer  race conditions, deadlocks, ordering

CI/CD Integration

# JSON report for pipeline
/preflight report --json > Preflight-report.json

# Fail on critical findings
cat Preflight-report.json | jq -e '.summary.critical == 0'

# Configure fail threshold
/preflight config threshold high   # fail on critical + high

Plugin Structure

Preflight/
├── .claude-plugin/
│   └── plugin.json           # plugin manifest (v2.0)
├── skills/
│   ├── Preflight/
│   │   └── SKILL.md          # Core protocol (reference, always active)
│   ├── verify/
│   │   └── SKILL.md          # Full 4-gate audit
│   ├── scan/
│   │   └── SKILL.md          # Automated 7-flaw file scanner
│   ├── diff/
│   │   └── SKILL.md          # Git diff scanner
│   ├── flaw/
│   │   └── SKILL.md          # Per-flaw deep reference
│   ├── report/
│   │   └── SKILL.md          # Project-wide report + JSON output
│   ├── teach/
│   │   └── SKILL.md          # Before/after teaching examples
│   └── config/
│       └── SKILL.md          # Project configuration (.preflight.json)
├── agents/
│   ├── reviewer.md           # General Preflight reviewer
│   ├── security-reviewer.md  # Security-specialized reviewer
│   ├── api-reviewer.md       # API contract reviewer
│   └── concurrency-reviewer.md  # Concurrency reviewer
├── hooks/
│   └── hooks.json            # PostToolUse + PreToolUse + Stop hooks
├── LICENSE
└── README.md

Configuration

Preflight is configurable per project via .preflight.json. Initialize with /preflight config init.

Key settings:

• Gate enforcement: mandatory vs advisory per gate
• Flaw severity thresholds: suppress noisy low-severity findings
• CI fail threshold: block pipeline on critical, high, or any findings
• Ignore rules: suppress specific flaws for specific paths (requires reason)
• Hook enablement: disable individual hooks if needed

{
  "version": "1.0",
  "gates": {
    "4": { "enforcement": "mandatory" }
  },
  "ci": {
    "fail_on": "high",
    "json_report_path": "Preflight-report.json"
  },
  "ignore": [
    { "flaw": 7, "path": "src/generated/**", "reason": "Generated code" }
  ]
}

Origin

Preflight emerged from a battle-tested verification protocol used in production AI coding pipelines. The core insight: AI coding errors aren't random — they cluster around 7 specific cognitive flaws that are structural to how language models generate code. Fix the reasoning, fix the code.

License

MIT — AnnulusLabs LLC

Built off-grid in Taos, New Mexico.