unslop-preflight

Unslop Preflight

The ultimate preflight & autonomous repair guardrail for AI-built frontends.

Stop AI coding agents before they ship fragile, slop-ridden frontend layouts into production.

What is Unslop Preflight?

AI coding agents write frontend code 10x faster, but they also introduce fragile UI regressions 10x faster. When agents "vibe code" without strict guardrails, they often generate:

• Clickable <div> elements: Interactive components missing keyboard support and ARIA landmarks.
• Blind z-9999 patches: Stacking-context bugs masked by extreme z-indexes.
• Desktop-only modals: Overlays that lock scrolling or clip content on mobile devices.
• Performance killers: Broad transition: all declarations that degrade Interaction to Next Paint (INP).
• Prose slop: AI-sounding filler copy (e.g., "delve", "foster").

Unslop Preflight is an automated quality gate and source-level repair engine. It enforces accessibility, layout sanity, and copy standards before AI-generated code is ever merged.

Features: 7 Integrated Engines

Unslop Preflight unifies 7 open-source quality engines into one deterministic CLI:

1. no-ai-slop: Copy and prose refactoring.
2. loop-engineering: Continuous L1/L2 autonomous loops.
3. ui-review-loop: Visual browser UI testing and DOM timeline capture.
4. browser-use: Headless automation and viewport boundary testing.
5. make-interfaces-feel-better: 19 design engineering polish principles.
6. ui-skills: Baseline motion performance and interaction rules.
7. ux-ui-agent-skills: Design token governance and taste calibration.

Quick Start

[!NOTE] bun is highly recommended for executing Unslop Preflight within AI agent environments.

Run the instant preflight scan and auto-repair:

bunx unslop-preflight autopilot --safe-fix --verify

Installation

# Using Bun (Recommended)
bun add -d unslop-preflight

# Using npm
npm install --save-dev unslop-preflight

# Using pnpm
pnpm add -D unslop-preflight

CLI Commands

Use autopilot --plan-only for a zero-write preview. It prints the assessment and proposed repairs without modifying project files or creating .unslop reports, even when --report or a fix-mode flag is also present.

Example Gate Output

Blocked Scan (Errors & Layout Regressions Detected)

$ bunx unslop-preflight scan src

Unslop Output
Score: 0/100 | Checks: 64 | Errors: 3 | Warnings: 14 | Info: 0
Readiness: blocked
Decision: Do not hand this to an AI coding agent yet. Resolve errors and blocked source issues first.
Scan: 1 file | 17 findings | 0 scanner failures | 10ms
Top categories: source-modular (17)

Issues:
  ✕ [ERROR] fixed-width-mobile-risk: Fixed wide width without a max-width constraint or responsive breakpoint. Will cause horizontal scroll on mobile.
  ⚠ [WARNING] arbitrary-z-index-slop: Extreme arbitrary z-index detected (e.g. z-9999). Use structured layers (e.g., z-40, z-50) or stacking contexts.
  ⚠ [WARNING] height-100vh-mobile-risk: `h-screen` or `100vh` detected. On mobile Safari/Chrome, this ignores the browser address bar. Use `h-dvh` or `min-h-screen`.
  ⚠ [WARNING] oversized-typography-mobile-risk: Oversized text utility found without a responsive constraint. This will break mobile layouts.

Next steps:
  Run: bunx unslop-preflight autopilot --report

Passing / Agent-Ready Scan

$ bunx unslop-preflight scan src

Unslop Output
Score: 100/100 | Checks: 64 | Errors: 0 | Warnings: 0 | Info: 0
Readiness: agent-ready
Decision: Ready for AI-assisted implementation with standard verification.
Scan: 12 files | 0 findings | 0 scanner failures | 8ms

✓ No issues found! Your design spec is robust.

Next steps:
  Run: bunx unslop-preflight autopilot --report

CLI Flags & Common Recipes

CLI Flags

Common Recipes

• Quick Health & Spec Check:

  bunx unslop-preflight doctor
  

• CI Build & Quality Gate:

  bunx unslop-preflight scan src --ci
  

• Strict Pre-Merge Gate (Errors + Warnings):

  bunx unslop-preflight scan src --strict
  

• Zero-Write Dry-Run Plan:

  bunx unslop-preflight autopilot --plan-only
  

• Full Autonomous Repair & Verification Loop:

  bunx unslop-preflight autopilot --safe-fix --verify --report --strict
  

• Agent Handoff Instructions:

  bunx unslop-preflight audit --agent-prompt
  

Security & Supply Chain Defense

[!IMPORTANT] Unslop Preflight is built with a zero-trust, secure-by-default architecture to prevent supply chain attacks, strictly adhering to npm security best practices.

• Zero Postinstall Scripts: Executes cleanly with ignore-scripts=true.
• Lockfile Integrity: Strictly validates package lockfiles (package-lock.json, bun.lockb, pnpm-lock.yaml) during the repair lifecycle to prevent injection.
• OIDC Publishing: Releases are signed via GitHub Actions OIDC with provenance attestations (--provenance).
• Credential Scanning: Embedded detectors proactively block hardcoded API keys and JWTs in source code before they ship.

Agent Instructions

[!TIP] Paste this into Claude Code, Cursor, or Gemini CLI to delegate the cleanup loop.

You are my cleanup agent. Please run Unslop Preflight and fix the reported issues:

1. Detect the package manager (prefer Bun).
2. Run: `bunx unslop-preflight autopilot --safe-fix --verify --report --strict`
3. Read the reports in `.unslop/` (report.md, fix-list.md).
4. Address the findings:
   - Fix prose slop and AI-sounding copy.
   - Fix interface issues (transition: all, missing focus states).
   - Fix accessibility gaps (clickable divs, icon-only buttons).
   - Fix z-index and modal clipping bugs.
5. Re-run the autopilot command to verify the score delta.
6. Ensure all project checks (build, test, lint) pass cleanly.

Repository Structure

unslop-preflight/
├── .github/workflows/          # CI/CD & OIDC trusted npm publishing
├── bin/cli.js                  # CLI executable entry point
├── src/
│   ├── commands/               # CLI handlers (autopilot, scan, loop, review)
│   ├── core/                   # Engines (loopGate, reviewRecorder, safetyValidator)
│   ├── rules/                  # Gate rules (proseSlop, interfaceFeel, a11y)
│   └── scanners/               # Analyzers (browserAutomation, sourceSlop)
├── tests/                      # Unit & integration test runner suite
├── AGENTS.md                   # Agent guidance contract
├── SKILL.md                    # Universal skill manifest
└── package.json                # Project description & ESM manifest

Crafted with care to bring rigorous architectural discipline and gorgeous visual elegance to AI-driven frontend workflows.