docs: improve Rstack CLI migration skill (#287)

Author: chenjiahan

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

@@ -24,15 +24,15 @@ Read every matching reference before editing. Load only the tools present in the
 
 1. Inspect manifests, workspace catalogs, lock files, scripts, standalone configs, ignore files, Git hooks, TypeScript `types`, and source imports.
 2. Read the matching references and inventory behavior that must survive: config functions, CLI arguments, plugins, presets, adapters, custom config paths, and chained commands.
-3. Check the latest `rstack` version and inspect its Node.js engine and underlying tool versions. Resolve plugin and adapter peer ranges first; upgrade incompatible extensions or stop when no compatible version exists. Add `rstack` using the repository's existing package manager and version convention, usually as a development dependency.
+3. Check the latest `rstack` release, Node.js engine, underlying tool versions, and relevant peer ranges. Upgrade incompatible plugins or adapters; stop if no compatible version exists. Ensure development and CI use supported Node.js versions, but do not narrow a published package's runtime `engines` solely to satisfy Rstack. Add `rstack` as a development dependency with the existing package manager.
 4. If a matching reference uses a `define.*` registration, create `rstack.config.ts` and move the standalone configuration into it.
 5. Rewrite commands and imports as directed by the references.
-6. Search again for old direct imports, binaries, config paths, manifest entries, and type references. Remove only entries with no remaining direct or runtime use and no unresolved peer compatibility requirement.
+6. Search again for old imports, binaries, config paths, manifest entries, package-manager metadata, and type references. Remove an item only after ruling out direct or runtime use and unresolved peer constraints.
 7. Delete a standalone config only after its behavior is represented in `rstack.config.*`.
 8. Refresh the lockfile with the repository's package manager. Confirm the expected tool version changes and resolve peer dependency warnings.
-9. Run the repository's existing migrated scripts and required checks. Compare generated artifacts or runtime behavior where relevant.
+9. Run migrated scripts and required repository checks. Compare generated artifacts or runtime behavior where relevant. After any follow-up changes, rerun the relevant checks against the final code.
 
-The underlying Rsbuild, Rslib, Rstest, Rslint, and Prettier packages remain transitive dependencies of `rstack`. Do not require their names to disappear from the lockfile; require obsolete direct manifest entries and imports to disappear.
+Rsbuild, Rslib, Rstest, Rslint, and Prettier remain transitive `rstack` dependencies. Remove obsolete direct dependencies and imports from the migrated scope; do not expect their names to disappear from the lockfile.
 
 ## Configuration Rules
 

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

@@ -10,6 +10,8 @@ Migrate [Husky](https://typicode.github.io/husky/) or [simple-git-hooks](https:/
 4. Ensure the `prepare` script in the root `package.json` runs `rs setup`, adding it if necessary. Remove the old installer invocation from any lifecycle script while preserving other commands. Use `--hooks-dir` consistently when choosing a custom directory.
 5. Run the updated lifecycle script, exercise the migrated hooks, and remove the old dependency and configuration only after behavior matches.
 
+`rs setup` creates `.rstack/hooks/_/.gitignore`. Do not list `.rstack/hooks/_` in the root `.gitignore`.
+
 ## Husky
 
 1. Locate the source hooks:
@@ -42,7 +44,7 @@ pnpm test
 3. Replace the simple-git-hooks lifecycle command with `rs setup`, preserving other chained commands.
 4. Replace `SKIP_INSTALL_SIMPLE_GIT_HOOKS=1` and `SKIP_SIMPLE_GIT_HOOKS=1` usage with `RSTACK_HOOKS=0`. Move required commands from the file referenced by `SIMPLE_GIT_HOOKS_RC` to the Rstack user initialization file, with user permission.
 5. Do not run the simple-git-hooks uninstall script after `rs setup`; it follows the current `core.hooksPath` and can delete Rstack's generated hook shims.
-6. After validation, remove the simple-git-hooks dependency, configuration, and installer command. Remove old generated hook files only after confirming their ownership and exact paths.
+6. After validation, remove the simple-git-hooks dependency, config, installer, and stale package-manager metadata such as pnpm `allowBuilds`. Remove old generated hook files only after confirming their ownership and paths.
 
 For example, migrate:
 

.agents/skills/migrate-to-rstack-cli/references/lint-staged.md

@@ -10,17 +10,18 @@ If staged tasks invoke Prettier, also read [prettier.md](prettier.md).
 
 1. Replace staged-file script invocations with `rs staged`.
 2. Move the staged-file config into `define.staged` in `rstack.config.*`.
-3. Remove the old manifest key or config file.
-4. Remove the direct staged-file dependency only when no script, config, or programmatic API still uses it.
+3. Preserve previous behavior. Separate code tasks that lint and format from format-only tasks.
+4. Remove the old manifest key or config file.
+5. Remove the direct staged-file dependency only when no script, config, or programmatic API still uses it.
 
 ## Config Pattern
 
 ```ts
 import { define } from 'rstack';
 
 define.staged({
-  '*.{ts,tsx,js,jsx}': ['rs lint --fix', 'rs fmt'],
-  '*.{json,md}': 'rs fmt',
+  '*.{js,jsx,ts,tsx,mjs,cjs}': ['rs lint', 'rs fmt'],
+  '*.{json,jsonc,md,mdx,css,html,yml,yaml}': 'rs fmt',
 });
 ```
 

.agents/skills/migrate-to-rstack-cli/references/prettier.md

@@ -17,6 +17,8 @@ Read this reference when the project uses the `prettier` CLI or API, `package.js
 
 `rs fmt` ignores `package-lock.json` and `pnpm-lock.yaml` by default. Drop redundant ignore entries during migration, but keep intentional negations.
 
+Rstack creates `.rstack/cache/.gitignore` by default. Do not list `.rstack/cache` in the root `.gitignore`; add explicit rules only for custom cache paths.
+
 `rs fmt` does not read Prettier configuration files, `.prettierignore`, or `.editorconfig`.
 
 Keep `.editorconfig` when editors or other tools use it. Keep Prettier when application code uses APIs such as `prettier.format()`; `rs fmt` is not a drop-in replacement for the programmatic API.

.agents/skills/migrate-to-rstack-cli/references/rslint.md

@@ -36,4 +36,4 @@ If a script also runs Prettier, migrate its formatting command as described in [
 
 ## Validate
 
-Run the non-writing lint script.
+Run lint without writes. If Rstack upgrades Rslint, preserve the pre-migration lint baseline: disable newly enabled rules instead of changing source code, unless code changes are requested.