gentleeduck/duck-ui / .claude/skills/setup-pre-commit
setup-pre-commit
VerifiedThe commit and push gates in this repo - what husky runs at each hook, why test:coverage and not test, why a push can leave files unstaged, and how to add or change a gate without letting the hook and CI drift apart. Use when a hook fails, when asked to add a check at commit or push time, or when tempted to reach for --no-verify.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.2 KB |
| agents/openai.yaml | config | 99 B |
SKILL.md
View on GitHub---
name: setup-pre-commit
description: The commit and push gates in this repo - what husky runs at each hook, why test:coverage and not test, why a push can leave files unstaged, and how to add or change a gate without letting the hook and CI drift apart. Use when a hook fails, when asked to add a check at commit or push time, or when tempted to reach for --no-verify.
---
# The gates
Husky is already wired here. `prepare` is `husky`, so `bun install` installs the hooks, and
three exist.
| Hook | Runs | Blocks |
|---|---|---|
| `commit-msg` | `commitlint --edit` | a message that is not a conventional commit, or carries a non-ASCII codepoint |
| `pre-commit` | `lint`, then `format` | a commit, on the first failure |
| `pre-push` | `lint`, `format`, `fix`, `check`, `check-types`, `test:coverage`, `build` | a push, on the first failure (`set -e` is explicit in the file) |
Every one of those is a root `package.json` script. Read them there rather than trusting this
table: the scripts are the source of truth and this is a summary of them.
## What the design is protecting
- **`biome` is the only linter and formatter.** There is no prettier, no eslint, no
lint-staged, and nothing stages a subset of files. `lint` is `biome lint .`, `format` is
`biome format --write .`, `fix` is `biome check --write .`, `check` is `biome check .`.
Adding prettier would give the repo two formatters that disagree.
- **`format` and `fix` write.** A formatting slip is corrected in place during the push rather
than refused by `check` two lines later. The corrected file is left **unstaged**, so
`git status` after a push that took a while is worth reading.
- **`test:coverage`, not `test`.** A threshold is only read when coverage is collected.
Thresholds live in each package's own `vitest.config.ts`, set at what that package measures
rather than at an aspiration. They are a ratchet: raise one as coverage rises, and read a
drop as the thing to fix rather than the number to lower. A package with no tests has no
threshold, because a gate over nothing measures nothing.
- **Neither infrastructure tier is in a hook.** `test:e2e` wants Docker, a seeded database and
a build, and every integration file truncates one shared Postgres, so two runs at once fail
each other. Both run at `--concurrency=1`, from CI or from `bun run verify`.
- **One definition, so the hook and CI cannot drift.** `ci` is
`check && check-types && test:coverage && build`. `verify` is `ci` plus the two
infrastructure tiers. The hook runs the same scripts CI does.
## When a gate fails
Read what failed and fix it. The gates have caught real defects, and two failure shapes look
like a broken tree when nothing is wrong:
- **Parallel `check-types --force` runs** read a mid-write `dist` and emit a TS2307 storm.
One run at a time.
- **Two integration or e2e runs at once** truncate each other's database. That is the
`--concurrency=1` above, and a second run started by hand defeats it.
An unused import or an argument count that no longer matches is the honest signal that a
refactor is half-finished, not hook noise.
`--no-verify` is for the case where the gate itself is broken, not the code. It needs the
user's explicit say-so in that same message, and whatever it skipped still has to run before
the branch is anyone else's problem.
## Changing a gate
Put the step in the root `ci` or `verify` script first, then reference that script from the
hook. A step written straight into `.husky/pre-push` runs on push and never in CI, which is
the drift the two scripts exist to prevent.
`.husky/pre-push` keeps `set -e` and its current order: the cheap checks come before the
expensive ones, so a formatting mistake fails in seconds rather than after a build.
## Commit messages
`commit-msg` runs commitlint, which enforces:
- **Conventional commits**, `type(scope): subject`.
- **Plain ASCII only**, subject and body. The `ascii-only` rule rejects an em dash, a curly
quote, an arrow or an ellipsis character, and names the codepoint it found.
- Explain **why**, not what. The diff shows what.
A `Co-Authored-By` trailer is never added. Start a body paragraph with a word rather than a
`word:` token, or commitlint reads the paragraph as a footer and warns.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |