docs: add Lefthook migration guide (#428)

Author: chenjiahan

.agents/skills/migrate-to-rstack-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: migrate-to-rstack-cli
-description: Use when migrating projects from standalone Rsbuild, Rslib, Rstest, Rslint, Rspress, Prettier, sort-package-json, lint-staged, husky, or simple-git-hooks tooling to the unified `rstack` package, `rs` commands, and `rstack.config.*`.
+description: Use when migrating projects from standalone Rsbuild, Rslib, Rstest, Rslint, Rspress, Prettier, sort-package-json, lint-staged, husky, lefthook, or simple-git-hooks tooling to the unified `rstack` package, `rs` commands, and `rstack.config.*`.
 ---
 
 # Migrate to Rstack CLI
@@ -18,7 +18,7 @@ Read every matching reference before editing. Load only the tools present in the
 - `prettier`, `package.json#prettier`, `.prettierrc*`, `prettier.config.*`, `.prettierignore`, `.editorconfig`, `sort-package-json`, Prettier plugins, or formatting scripts: [prettier.md](references/prettier.md)
 - `@rspress/core`, `rspress.config.*`, `rspress` commands, themes, or plugins: [rspress.md](references/rspress.md)
 - `lint-staged`, `nano-staged`, their configs: [lint-staged.md](references/lint-staged.md)
-- `husky`, `.husky/`, `package.json#husky`, `simple-git-hooks`, `.simple-git-hooks.*`, or Git hook installer scripts: [git-hooks.md](references/git-hooks.md)
+- `husky`, `.husky/`, `package.json#husky`, `lefthook`, `simple-git-hooks`, `.simple-git-hooks.*`, or Git hook installer scripts: [git-hooks.md](references/git-hooks.md)
 
 ## Workflow
 

.agents/skills/migrate-to-rstack-cli/references/git-hooks.md

@@ -1,6 +1,6 @@
 # Git Hook Migration
 
-Migrate [Husky](https://typicode.github.io/husky/) or [simple-git-hooks](https://github.com/toplenboren/simple-git-hooks#readme) to [`rs hooks`](https://rstack.rs/guide/cli/hooks). If a hook calls lint-staged or nano-staged, also read [lint-staged.md](lint-staged.md).
+Migrate [Husky](https://typicode.github.io/husky/), [Lefthook](https://lefthook.dev/), or [simple-git-hooks](https://github.com/toplenboren/simple-git-hooks#readme) to [`rs hooks`](https://rstack.rs/guide/cli/hooks). If a hook works with staged files, also read [lint-staged.md](lint-staged.md).
 
 ## Shared Steps
 
@@ -38,6 +38,14 @@ to:
 pnpm test
 ```
 
+## Lefthook
+
+1. Resolve the merged configuration, including main and local files, `LEFTHOOK_CONFIG`, `extends` or remote configs, lifecycle scripts, and direct `lefthook run` calls. Treat ignored local configs as user-owned.
+2. Create one Rstack file per Git hook. Rstack runs it with POSIX `sh -e` and forwards arguments and standard input. Replace templates such as `{1}` with `"$1"`; move custom Lefthook groups to project scripts.
+3. Move `pre-commit` tasks using `{staged_files}`, `stage_fixed`, `glob`, or `exclude` to `define.staged`, and run `rs staged` from `.rstack/hooks/pre-commit`; it passes matched files and stages successful fixes. Recreate the intended file set instead of copying globs: Lefthook's default `**` semantics differ from lint-staged. Preserve exclusions such as unsupported symlinks.
+4. For `{push_files}`, `{all_files}`, custom `{files}`, or orchestration such as `parallel` and `piped`, call a project helper from the hook. It should consume all `pre-push` ref updates, apply the original conditions, preserve concurrency or ordering, and aggregate failures. For a configuration like Rstest's, run the format/spell check always, skip type checking only for Markdown-only pushes, and run the dependency check only for pushed package manifests. Do not substitute a fixed `HEAD^` diff.
+5. Replace `lefthook install` with `rs hooks` and `LEFTHOOK=0` with `RSTACK_HOOKS=0`. After validation, remove Lefthook configs, dependencies, generated hooks, and its entries from pnpm build metadata such as `allowBuilds`, `onlyBuiltDependencies`, or `ignoredBuiltDependencies`. Preserve unrelated entries, and remove a setting only if it becomes empty. Remove local-config ignore rules only when no longer needed.
+
 ## simple-git-hooks
 
 1. Load the active configuration from `package.json#simple-git-hooks`, a `.simple-git-hooks.{js,cjs,mjs,json}` or `simple-git-hooks.{js,cjs,mjs,json}` file, or the custom path passed to its CLI. Use the configuration values instead of copying generated files from the Git hooks directory.