Preflight ✈️

One skill that makes AI coding agents stop making dumb mistakes.

Preflight is a coding discipline skill for OpenClaw agents. It enforces discovery-first methodology, scope contracts, fail-fast verification, and proof-of-work before any coding task is marked done.

The Problem

AI coding agents make the same mistakes repeatedly:

#	Failure Mode	What Happens
1	Wrong file edited	Agent finds Header.tsx and Header.old.tsx, edits the dead one
2	Hardcoded API values	API returns brandName, agent writes <h1>Ampere</h1> directly
3	"Done" without verification	"Updated the component ✅" — never ran build
4	Fix one, break three	Fixes a button, breaks mobile layout
5	Context amnesia	Agent forgets what it discovered 500 tokens ago
6	Infinite fix loops	Error → fix → error → fix → 45 min later, codebase destroyed
7	Wrong framework patterns	Next.js App Router project, agent uses Pages Router code
8	Empty PRs	PR title: "Update files". Body: empty.
9	Reinventing existing code	Repo has useAuth() hook, agent builds auth from scratch
10	Scope explosion	"Add loading state" → agent rewrites entire data layer

Preflight prevents all of these.

The 5 Pillars

🗺️ KNOW    → Map the repo before editing anything
🎯 SCOPE   → Write what you'll change and why (before coding)
🔨 VERIFY  → Build/test after EVERY file edit (not at the end)
📸 PROVE   → Evidence before "done" (screenshots, curl, test output)
🆘 STOP    → 3 failed fix attempts = stop and escalate to human

The Flow

Step 0: Branch Safety — never work on main
Step 1: Discovery — detect stack, map repo, find patterns
Step 2: Scope Contract — what files, what changes, why
Step 3: Implement — edit only planned files, reuse existing patterns
Step 4: Verify Loop — build after each edit, 3-strike rule
Step 5: Proof of Work — screenshot / curl / test evidence
Step 6: Logic Review — top-to-bottom sanity pass
Step 7: PR + Evidence — auto-generated PR body with full context

Install

Copy the skill into your OpenClaw skills directory:

# Clone
git clone https://github.com/dix105/preflight.git

# Copy to your agent's skills
cp -r preflight/skills/preflight ~/.openclaw/workspace/skills/preflight

Or if you're using ClaHub:

openclaw skill install preflight

Once installed, OpenClaw agents automatically use preflight before coding tasks.

What's Included

skills/preflight/
├── SKILL.md                        # The brain — full 7-step discipline flow
├── scripts/
│   ├── detect-stack.sh             # Auto-detect language/framework/version
│   ├── discover.sh                 # Map repo structure, patterns, contracts
│   └── verify.sh                   # Build runner with 3-strike escalation
└── references/
    └── stack-conventions.md        # Framework-specific do's and don'ts

Stack Detection

Auto-detects and adapts to your project:

Language	Frameworks
TypeScript/JavaScript	Next.js (App Router + Pages Router), React, Vue, Svelte, Express, Fastify, Hono
Python	Django, FastAPI, Flask
Go	Standard library, common patterns
Rust	Cargo-based projects
Ruby	Rails
PHP	Laravel

Key Features

• Persistent artifacts — Discovery map, plan, and checkpoints survive context loss
• Stack-aware scanning — Different discovery commands for different frameworks
• 3-strike rule — Prevents infinite fix loops, forces escalation to human
• Import graph tracing — Finds dead files before you accidentally edit them
• Pattern reuse — Finds existing hooks/utils/helpers so agents don't reinvent them
• PR auto-generation — Creates PR body with what changed, why, and verification evidence

Composability

Preflight works alongside other OpenClaw skills:

• PR-review — Preflight creates the PR → PR-review runs parallel review agents
• SAMURAI — Queen assigns "use preflight" to worker agents for disciplined execution
• Any coding skill — Preflight is the discipline layer, other skills are the intelligence layer

Trigger Phrases

Preflight activates automatically on coding tasks. You can also trigger it explicitly:

• "preflight the repo before we change anything"
• "discover the codebase first"
• "verify before pushing"
• "map the project structure"

Mini-browser Support

Preflight supports mini-browser for UI verification:

npm install -g @runablehq/mini-browser

Falls back to Playwright, Cypress, or manual verification if mini-browser isn't available.

License

MIT — fork it, modify it, make it yours.

Contributing

PRs welcome. If you find a failure mode this skill doesn't catch, open an issue with a reproduction case.