| name | preflight-check |
| description | This skill should be used when the user asks to "pre-flight check", "validate before commit", "validate before PR", "validate before deploy", "is this ready to ship", "check readiness", "run pre-flight", "validate project state", or wants context-aware validation across commit/PR/release/deploy boundaries. Orchestrates universal validators (lint, tests, types, version sync, stale refs, docs, hook conflicts) and supports generating new custom validators. |
Pre-flight Check
Universal pre-flight validation across commit, PR, release, and deploy boundaries. Orchestrates the validator suite that lives under .claude-plugin/skills/validation/ and dispatches the right check set for the current context.
When to Use
- User asks "is this ready to commit / PR / release / deploy?"
- User says "pre-flight", "validate", "check readiness", or runs
/craft:check
- Before staging a commit, opening a PR, or kicking off the release pipeline
- After a session of edits, to confirm nothing regressed
- When the user wants to scaffold a new custom validator (
gen-validator flow)
Scope Boundary (Read This First)
This skill is broader than its siblings — understand the seams:
| Skill | Concern | Does NOT cover |
|---|
| preflight-check (this) | Cross-cutting validators: lint, tests, types, version sync, stale refs, link integrity, hook conflicts, CLAUDE.md health, docs staleness, badge URLs, formula desc, skill standards (release-gated) | Detection logic, release orchestration, guard rule editing |
project-detector (skills/ci/) | Detect project type / build tool / test framework to recommend a CI template | Validation orchestration. It answers "what kind of project is this?" not "is it ready?" |
release (skills/release/) | The full release pipeline (version bump → PR → merge → GitHub release → Homebrew → verify). Calls this skill internally for its Step 2 pre-flight gate | Standalone commit/PR validation |
guard-audit (skills/guard-audit/) | Tune branch-guard.sh rules via .claude/branch-guard.json to reduce false positives | Running checks. It edits guard config, doesn't validate the project |
Rule of thumb: if the user wants to run validators, use this skill. If they want to change which rules block them, route to guard-audit. If they want a release, route to release (which calls back into this skill).
Backing Commands
/craft:check — primary entry point; mode-aware, context-aware orchestrator
The skill should prefer invoking the commands rather than re-implementing their logic. The commands handle dry-run, orchestration, and hot-reload validator discovery.
Context Flags (--for ...)
Pick the check set by what the user is preparing for. This is the primary axis of behavior:
--for | Run when user is about to... | Adds beyond default |
|---|
commit | Stage and commit on a feature branch | Fast lint on changed files, fail-fast tests, basic version-sync, no-secrets scan |
pr | Open a PR to dev/main | Full lint, full test suite, coverage ≥ 80%, internal links, merge-conflict detect, stale-ref scan, hook-conflict audit, CLAUDE.md health |
release | Cut a release (called by skills/release/) | Full audit: strict lint, all tests + coverage ≥ 90%, all links, full version audit (fatal on drift), security audit, badge URL both-branch check, formula desc count check |
deploy | Deploy docs site or downstream artifact | Same as release minus formula-desc; plus tag-exists check |
If no --for is specified, run the "general" check set (lint + tests + git status + docs if changed).
Mode-Aware Behavior
Modes are orthogonal to --for — they tune verbosity, fail-fast, and threshold strictness:
| Mode | Budget | Behavior |
|---|
default | < 30s | Fast path, fail-fast, summary output |
debug | < 120s | Verbose output, no fail-fast, surface all warnings |
thorough | < 180s | Full lint + types + security + docs sweep |
release | < 300s | Strictest thresholds (coverage ≥ 90%, version drift = fatal) |
Mode applies to the hot-reload validators too via $CRAFT_MODE — see the validator template generator output for the per-mode threshold table.
Recommended Flow
- Confirm intent. Ask which context (
commit/pr/release/deploy) if the user didn't say. Default to the most conservative reasonable guess based on the current branch (feature/* → commit or pr; dev → release).
- Dry-run first when stakes are high. For
--for release or --for deploy, suggest /craft:check --for release --dry-run to preview the validator plan and time estimate before executing.
- Run the appropriate command. Invoke
/craft:check --for <context> [mode]. Let the command's Step 0 plan + AskUserQuestion gate handle confirmation.
- On failure, route specifically. Don't just dump errors — point at the right follow-up:
- Lint failures → suggest
/craft:ci:fix or /craft:code:lint
- Version drift → suggest
/craft:check --version release for the focused validator
- Stale refs from a rename → list the files that need updating
- CLAUDE.md staleness → suggest the docs/claude-md skill (sync)
- Hook-conflict false positives → route to
guard-audit skill
- On all-green, summarize and stop. Don't recommend "next steps" past the immediate gate the user asked about (per feature-branch-workflow rules: no PR-merge nudging).
Validator Generation (Separate Operation)
Generating a new custom validator is a distinct workflow from running checks. Trigger conditions:
- User says "create a validator", "add a custom validator", "generate a validator template"
- User wants to extend
/craft:check with project-specific validation logic
check:gen-validator was folded into this skill in the v4 consolidation (Phase 3.5,
2026-07-12) — no standalone command remains. Full scaffolding walkthrough (template
structure, interactive-mode prompts, mode-aware threshold examples, the community
validator marketplace convention): references/gen-validator.md.
In that flow:
- Generate the validator file directly under
.claude-plugin/skills/validation/<name>.md
with hot_reload: true (see references/gen-validator.md for the full template).
- After generation, suggest a smoke test:
CRAFT_MODE=default bash .claude-plugin/skills/validation/<name>.md then /craft:check to confirm auto-discovery.
Do not auto-generate a validator while the user is running checks — these are independent concerns. If both are in flight, finish the check pass first.
Context Header (--context)
The check command supports a --context flag that skips validation and emits only a one-screen session header (project, branch, worktree, base, guard status, phase, test count, docs status, insights). When the user asks "what's the state of this branch?" or "what session am I in?", prefer /craft:check --context over running validators. It's read-only and < 1s.
Output Conventions
The backing command uses box-drawing output (see commands/check.md). When this skill summarizes results in chat, mirror that structure compactly:
Project: <name> (<type>) Context: <for-value> Mode: <mode>
Lint: PASS / N issues
Tests: N/M passed
Version: in sync / DRIFT (file:line)
Docs: GREEN / YELLOW / RED
Status: READY / BLOCKED — <reason>
Next: <single actionable suggestion or none>
Keep summaries terse. The command's own output is the system of record.
Anti-Patterns
- Don't re-implement project detection here — defer to
project-detector via the command.
- Don't edit branch-guard rules — that's
guard-audit.
- Don't chain into the release pipeline — let the user invoke
release explicitly. This skill stops at "READY FOR RELEASE."
- Don't silently expand scope. If the user asked
--for commit, don't also run the release-tier validators just because "they're cheap." Mode budgets exist for a reason.
- Don't fix issues the validators report unless the user asks. Surface, then wait.
See Also
commands/check.md — full check command spec (validators, modes, dry-run output)references/gen-validator.md — validator scaffolding (folded from a command into this
skill in the v4 consolidation).claude-plugin/skills/validation/ — hot-reload validator directoryskills/release/SKILL.md — orchestrates this skill at Step 2 of releasesskills/ci/SKILL.md — project detection (used internally to pick check set)skills/guard-audit/SKILL.md — tune what blocks operations (not what validates them)
