preflight - SKILL.md Agent Skill

name: preflight description: > Pre-PR validation — working tree status, format, lint, TypeScript check, and protected file check. Workspace-aware: detects which of backend/, frontend/, services/apps/, services/libs/ were changed and runs only the relevant scripts. Use before submitting any PR, to check if code is ready, or to validate a branch before review. allowed-tools: Bash, Read, Glob, Grep, AskUserQuestion

Pre-Submission Preflight Check

Run each check in order. Report results clearly and help fix any issues found.

Check 0: Working Tree Status

git status
git diff --stat origin/main...HEAD
git log --format="%h %s%n%b" origin/main...HEAD

Evaluate:

Uncommitted changes? — Ask the contributor: commit now or stash?
No commits ahead of main? — The branch has nothing to validate. Ask if they're on the right branch.
Commit messages missing JIRA key? — Flag commits that don't include a CM-XXX reference.
Commits missing --signoff? — Flag any commits without Signed-off-by: lines.

Resolve any issues before proceeding.

Check 1: Detect Changed Workspaces

git diff --name-only origin/main...HEAD

Group changed files into workspaces:

Workspace	Path prefix	Lint	Format check	Type check	Test
Backend	`backend/`	`cd backend && pnpm lint`	`cd backend && pnpm format-check`	`cd backend && pnpm tsc-check`	`cd backend && pnpm test` (needs Docker)
Frontend	`frontend/`	`cd frontend && npm run lint`	—	—	—
Each service	`services/apps/<name>/`	`cd services/apps/<name> && pnpm lint`	`cd services/apps/<name> && pnpm format-check`	`cd services/apps/<name> && pnpm tsc-check`	`cd services/apps/<name> && pnpm test` if vitest present
Each lib	`services/libs/<name>/`	`cd services/libs/<name> && pnpm lint`	`cd services/libs/<name> && pnpm format-check`	`cd services/libs/<name> && pnpm tsc-check`	`cd services/libs/<name> && pnpm test` if vitest present

Run checks only for the workspaces that have changed files.

Check 2: Lint

For each changed workspace, run its lint command. Fix any errors before proceeding. Common issues:

Unused imports or variables
Missing type annotations
Rule violations

Check 3: Format Check

For each changed workspace that has a format-check script (backend, services), run it.

If there are format violations:

# Fix them
pnpm format
# Then stage the fixes
git add -p

Frontend does not have a format-check script — skip for frontend/.

Check 4: TypeScript Check

For each changed workspace that has tsc-check (backend, services), run it. Fix all type errors before proceeding.

Frontend does not have a tsc-check script — skip for frontend/.

Check 5: Protected Files Check

git diff --name-only origin/main...HEAD

Flag any changes to these protected files — they should NOT be modified without code owner approval:

services/libs/data-access-layer/** — shared DAL, high blast radius
services/libs/common/** — shared utilities, affects all services
backend/src/database/migrations/** — append-only Flyway migrations
scripts/cli, scripts/scaffold.yaml, scripts/scaffold.insights.yaml
.husky/*, commitlint.config.js
.github/workflows/**, .github/actions/**
tsconfig*.json, .eslintrc*, .prettierrc*
pnpm-lock.yaml, package.json, */package.json
CLAUDE.md, .claude/settings.json

If protected files appear in the diff, warn the contributor and ask them to revert or get code owner approval.

Check 6: Commit Verification

git log --format="%h %s%n%b" origin/main...HEAD

All changes committed? — If not, remind them to commit.
Commit messages follow conventions? — type: description (CM-XXX) format per commit-workflow.md.
--signoff on all commits? — Every commit must have Signed-off-by:.
JIRA key referenced? — PR title must contain a JIRA key (validated by CI at .github/workflows/pr-title-jira-key-lint.yml).

Check 7: Change Summary

git diff --stat origin/main...HEAD

List:

New files created — with their purpose
Modified files — with what changed
API changes — any new or modified routes in backend/src/api/
Migration changes — any new Flyway migrations

Results Report

Present a clear report:

PREFLIGHT RESULTS
─────────────────────────────────────────────────
✓ Working tree        — Clean, N commits ahead of main
✓ Lint                — backend: OK | frontend: OK | services/...: OK
✓ Format check        — backend: OK
✓ TypeScript          — backend: OK
✓ Protected files     — None modified
✓ Commits             — Conventions followed, signed off, CM-XXX present
─────────────────────────────────────────────────
READY FOR PR

Or if there are issues:

PREFLIGHT RESULTS
─────────────────────────────────────────────────
✓ Working tree        — Clean, N commits ahead of main
✗ Lint                — backend: 3 errors (see above)
✓ Format check        — backend: OK
✗ TypeScript          — backend: 1 error (see above)
✓ Protected files     — None modified
✗ Commits             — Missing Signed-off-by on 2 commits (run /dco)
─────────────────────────────────────────────────
ISSUES FOUND — Fix before submitting

If All Checks Pass

Suggest creating the PR:

"All preflight checks passed! Ready to create a PR. Would you like me to create it with gh pr create?"