preflight

A Claude skill that enforces discovery-first discipline before any code change. Built for AI-assisted repos where wrong-file edits, API contract drift, and unverified UI changes are the main failure modes.

---

What it does

Before touching any code, preflight forces a structured discovery pass:

1. Maps the repo — finds real entry points, feature flags, API contracts, and legacy traps
2. Checks contracts — ensures API-owned values aren't hardcoded on the client
3. Implements minimally — edits only mapped files, keeps scope tight
4. Gates on build/test — with a concrete recovery path if things break
5. Verifies visually — mini-browser or Playwright, with auth-state coverage
6. Reviews logic top-to-bottom — catches redundant sections, wrong branding, missing states
7. Opens a clean PR — with evidence, context, and architecture impact noted

---

The problem it solves

Claude (and most AI coding agents) make the same class of mistakes repeatedly:

• Editing a legacy file instead of the active one
• Hardcoding values the API already returns
• Shipping UI changes that were never rendered
• PRs with no context for reviewers
• ARCHITECTURE.md drifting out of sync

preflight encodes the fix for all of these into a single reusable skill.

---

Definition of Done

A task isn't done until:

• Correct file(s) edited based on discovery map
• API contracts respected (no hardcoded server-owned values)
• Build and tests pass
• UI verification completed (screenshot or fallback evidence)
• Architecture/mode docs updated if impacted
• PR opened from feature branch

---

Installation

Copy SKILL.md into your Claude skills directory:

# Claude Code
cp SKILL.md ~/.claude/skills/preflight/SKILL.md

Or install as a .skill file if your setup supports it.

---

Usage

Once installed, Claude will use preflight automatically before code changes. You can also trigger it explicitly:

• "preflight the dashboard page before we change anything"
• "verify before pushing"
• "check the repo structure first"

---

Works with

• Any frontend/backend/fullstack repo
• Next.js, React, Node, Rails, Django — framework-agnostic
• mini-browser, Playwright, or Cypress for UI verification
• GitHub PRs

---

mini-browser (runablehq)

Preflight supports runablehq mini-browser for UI verification.

• GitHub: https://github.com/runablehq/mini-browser
• npm: https://www.npmjs.com/package/@runablehq/mini-browser

Install:

npm install -g @runablehq/mini-browser

---

Free to use

MIT licensed. No paid tier. 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.