Enable Quality Gate

This skill helps you set up mise and hk quality gates in a repository. It leverages hk init --interactive --mise to detect project type, generate configuration, and optionally migrate existing hooks.

When to use this skill

• Onboarding a new repository to Bitso's quality gate infrastructure

• Setting up mise and hk in an existing repository

• Migrating from Husky, pre-commit, or lefthook to hk

• Configuring project-specific linters and formatters

Skill Contents

Sections

• When to use this skill

• Prerequisites

• Quick Start

• Instructions

• Project-Specific Configuration

• Hook Migration

• Bitso Environment Configuration

• Validation

• Troubleshooting

• Skill Self-Improvement

• Related Skills

Available Resources

📚 references/ - Detailed documentation

• java

• migration patterns

• nodejs

Prerequisites

Before enabling quality gates, ensure:

• mise is installed and activated in your shell

• hk is installed (via mise or package manager)

• pkl CLI is available (for hk configuration)

• Repository is cloned locally

Installation by Platform

macOS (Homebrew recommended due to AirLock):

brew install mise hk eval "$(mise activate zsh)" mise use pkl

Linux (distro package managers):

Debian/Ubuntu

curl https://mise.run | sh eval "$(mise activate bash)"

Fedora/RHEL

dnf copr enable jdxcode/mise dnf install mise

Arch

sudo pacman -S mise

Then install hk via mise (recommended)

mise use hk pkl

Alternative installation (any platform):

Install hk via cargo

cargo install hk

Install hk via aqua

aqua g -i jdx/hk

Verify Prerequisites

mise --version # Should be 2026.2.2+ hk --version # Should be 1.34.0+ pkl --version # Required for hk.pkl

Quick Start

For most repositories:

1. Install tools if needed (see Prerequisites for platform-specific options)

macOS: brew install mise hk

Linux: curl https://mise.run | sh && mise use hk pkl

2. Initialize with interactive mode

hk init --interactive --mise

3. Install hooks

hk install

4. Verify

hk check

Instructions

Step 1: Detect Project Type

Run hk init in interactive mode to detect your project:

hk init --interactive --mise

This command:

• Scans the repository for project indicators (package.json, build.gradle, go.mod, etc.)

• Presents a list of 90+ available linters relevant to your project

• Lets you select which linters to enable

• Generates hk.pkl configuration

• Generates mise.toml with hk integration (if --mise flag used)

Step 2: Review Generated Configuration

After running hk init , review the generated files:

hk.pkl - Git hook configuration:

amends "package://github.com/jdx/hk/releases/download/v1.36.0/hk@1.36.0#/Config.pkl" import "package://github.com/jdx/hk/releases/download/v1.36.0/hk@1.36.0#/Builtins.pkl"

hooks { ["pre-commit"] { fix = true stash = "git" steps { // Selected linters will appear here } } }

mise.toml - Development environment:

[tools] hk = "latest"

[tasks] pre-commit = "hk run pre-commit"

Step 3: Add Bitso-Specific Configuration

Enhance the generated configuration with Bitso standards:

Add to mise.toml:

[env]

Enable hk integration

HK_MISE = "1"

Hook mode (skip, info, warn, full)

BITSO_MISE_MODE = "full"

Logging

HK_LOG = "warn" HK_LOG_FILE = ".hk-logs/hk.log"

Add security checks to hk.pkl:

hooks { ["pre-commit"] { steps { // Security checks (always include) ["no-commit-to-branch"] = Builtins.no_commit_to_branch ["detect-private-key"] = Builtins.detect_private_key ["check-merge-conflict"] = Builtins.check_merge_conflict

  // Hygiene checks
  ["trailing-whitespace"] = Builtins.trailing_whitespace
  ["newlines"] = Builtins.newlines

  // Your project-specific linters
  // ...
}

} }

Step 4: Install Hooks

Install hk hooks

hk install

Or with mise integration

hk install --mise

Step 5: Configure Git Hooks Path

Note: hk by default uses .git/hooks , but Bitso Java repositories use .git-hooks for compatibility with existing infrastructure. Choose based on your repository's conventions:

Option A: Bitso standard (for Java repos and repos with existing .git-hooks)

git config core.hooksPath .git-hooks hk install # Will use .git-hooks

Option B: hk default (for new repos or repos without existing hook infrastructure)

hk install # Uses .git/hooks by default

Verify the hooks path

git config --get core.hooksPath

If your repository already has hooks in .git-hooks/ , use that path. Otherwise, you can use hk's default of .git/hooks .

Step 6: Add to .gitignore

Add hk logs to .gitignore

echo ".hk-logs/" >> .gitignore

Step 7: Commit Configuration

git add hk.pkl mise.toml .gitignore git commit -m "chore: enable mise and hk quality gates"

Project-Specific Configuration

Java/Gradle Projects

Java projects require custom steps for Gradle-based tooling:

amends "package://github.com/jdx/hk/releases/download/v1.36.0/hk@1.36.0#/Config.pkl" import "package://github.com/jdx/hk/releases/download/v1.36.0/hk@1.36.0#/Builtins.pkl"

local javaLinters = new Mapping<String, Step> { ["spotless-check"] { glob = List("/*.java", "/.kt") check = "./gradlew spotlessCheck --quiet" fix = "./gradlew spotlessApply --quiet" } ["gradle-check"] { glob = List("**/.java", "**/*.kt") check = "./gradlew check --quiet" } }

hooks { ["pre-commit"] { stash = "git" steps { // Security ["no-commit-to-branch"] = Builtins.no_commit_to_branch ["detect-private-key"] = Builtins.detect_private_key

  // Java linters
  ...javaLinters
}

} ["pre-push"] { steps { ["gradle-build"] { check = "./gradlew build --quiet" } } } }

See references/java/setup.md for complete Java configuration.

Node.js/TypeScript Projects

amends "package://github.com/jdx/hk/releases/download/v1.36.0/hk@1.36.0#/Config.pkl" import "package://github.com/jdx/hk/releases/download/v1.36.0/hk@1.36.0#/Builtins.pkl"

hooks { ["pre-commit"] { fix = true stash = "git" steps { // Security ["no-commit-to-branch"] = Builtins.no_commit_to_branch ["detect-private-key"] = Builtins.detect_private_key

  // Node.js linters
  ["eslint"] = Builtins.eslint
  ["prettier"] = Builtins.prettier
  ["tsc"] = Builtins.tsc
}

} ["pre-push"] { steps { ["test"] { check = "npm test" } } } }

See references/nodejs/setup.md for complete Node.js configuration.

Python Projects

hooks { ["pre-commit"] { fix = true stash = "git" steps { ["ruff"] = Builtins.ruff ["ruff-format"] = Builtins.ruff_format ["mypy"] = Builtins.mypy } } }

Go Projects

hooks { ["pre-commit"] { fix = true stash = "git" steps { ["golangci-lint"] = Builtins.golangci_lint ["go-fmt"] = Builtins.go_fmt ["go-vet"] = Builtins.go_vet } } }

Hook Migration

From Husky

Backup existing hooks:

cp -r .husky .husky.backup

Run hk init:

hk init --interactive --mise

Migrate lint-staged configuration:

If using lint-staged, add it as a step:

["lint-staged"] { check = "npx lint-staged" }

Remove Husky:

Remove from package.json

npm pkg delete scripts.prepare

Remove Husky directory

rm -rf .husky

From pre-commit (Python)

Map hooks to hk builtins:

pre-commit hook hk builtin

trailing-whitespace

Builtins.trailing_whitespace

end-of-file-fixer

Builtins.newlines

check-yaml

Builtins.yamllint

black

Builtins.black

flake8

Builtins.flake8

isort

Builtins.isort

Remove pre-commit:

pre-commit uninstall rm .pre-commit-config.yaml

From lefthook

Translate lefthook.yml to hk.pkl:

lefthook commands map directly to hk steps. File patterns are similar.

Remove lefthook:

lefthook uninstall rm lefthook.yml

See references/migration-patterns.md for detailed migration patterns.

Bitso Environment Configuration

Hook Mode System

Configure hook behavior via environment variables:

Variable Scope Default

BITSO_MISE_MODE

Global full

BITSO_MISE_GIT_HOOKS

All git hooks (from global)

BITSO_MISE_GIT_HOOKS_COMMIT

pre-commit (from git hooks)

BITSO_MISE_GIT_HOOKS_PUSH

pre-push (from git hooks)

Local Developer Override

Create mise.local.toml (git-ignored) for local preferences:

[env]

Don't fail commits locally, but enforce on push

BITSO_MISE_GIT_HOOKS_COMMIT = "warn" BITSO_MISE_GIT_HOOKS_PUSH = "full"

CI Configuration

In CI, hooks should be skipped (CI runs validations directly):

env: CI: true BITSO_MISE_GIT_HOOKS: skip

Validation

Verify Installation

Check tools

mise --version # Should be 2026.2.2+ hk --version # Should be 1.34.0+

Validate configuration

hk validate

Run checks

hk check

Test pre-commit

hk run pre-commit

Checklist

• hk.pkl exists and is valid

• mise.toml exists (if using mise integration)

• hk validate passes

• hk run pre-commit executes successfully

• git commit triggers hooks

• Configuration files are committed

• .hk-logs/ is in .gitignore

Troubleshooting

hk not found

Ensure Homebrew version is used

echo "alias hk='$(brew --prefix)/bin/hk'" >> ~/.zshrc source ~/.zshrc

pkl package download fails

Download with CA certificate for Cloudflare WARP

pkl download-package --ca-certificates=$HOME/cloudflare_ca_certificate.pem
package://github.com/jdx/hk/releases/download/v1.36.0/hk@1.36.0

Hooks not running

Reinstall hooks

hk install

Check git config

git config --get core.hooksPath # Should be .git-hooks (Bitso Java) or empty (hk default .git/hooks)

Manual test

hk run pre-commit

Gradle timeout

For slow Gradle builds, increase timeout or move to pre-push:

["gradle-check"] { check = "./gradlew check --quiet" profile = "slow" // Only runs with HK_PROFILE=slow }

Skill Self-Improvement

This skill should evolve based on learnings from actual migrations. After executing a migration:

Document Learnings

If you encounter issues or discover better patterns during a migration:

• Note the learning - What worked, what didn't, what was missing from this skill

• Identify the improvement - Which section needs updating (Prerequisites, Instructions, Troubleshooting, etc.)

• Propose a PR - Create a PR to update this skill in ai-code-instructions

Creating Improvement PRs

1. Clone ai-code-instructions (if not already)

cd ~/bitsoex git clone https://github.com/bitsoex/ai-code-instructions.git

2. Create a branch for the improvement

cd ai-code-instructions git checkout main && git pull git checkout -b docs/improve-enable-quality-gate-skill

3. Edit the skill

- global/skills/enable-quality-gate/SKILL.md

- global/skills/enable-quality-gate/references/*.md

4. Commit with context about the learning

git add global/skills/enable-quality-gate/ git commit -m "docs(enable-quality-gate): add learning from [repo] migration

• [What was learned]
• [What was added/changed]

Context: Discovered during migration of [repo-name]"

5. Create PR

git push -u origin HEAD gh pr create --draft --title "docs(enable-quality-gate): [improvement title]"
--body "## Learning from migration

Repository: `bitsoex/[repo-name]` Issue encountered: [description] Solution added: [what this PR adds]

Changes

• [list of changes to the skill]"

Types of Improvements

Category Example

New pattern Migration from a new hook system not documented

Troubleshooting Error message not covered in troubleshooting section

Configuration Project type needs special handling

Prerequisite Additional tool or setup step required

Clarification Instructions were ambiguous or incomplete

Feedback Loop

The goal is continuous improvement:

Migration attempt → Learn → Update skill → Next migration benefits

When proposing improvements, include:

• The specific repository where the issue was encountered

• The exact error or confusion point

• The solution that worked

• Suggested documentation update

Related Skills

Skill Purpose

mise mise configuration details

hk hk configuration details

git-hooks General hook patterns

quality-checks Runtime quality orchestration