feat(rstack-repo-maintain): add rstack repo maintain skill

AGENTS.md

@@ -11,6 +11,7 @@ A collection of Agent Skills for the Rspack ecosystem (Rspack, Rsbuild, Rslib, R
 ```
 agent-skills/
 ├── skills/              # Skills directory, contains all Skills
+├── dev-skills/          # Developer-facing Skills for Rstack repository maintenance
 ├── packages/            # Source code projects for complex scripts
 ├── scripts/             # Project-level configurations and tools
 │   └── config/          # Common configurations (rslib, tsconfig, etc.)
@@ -25,6 +26,8 @@ agent-skills/
 
 - **skills/**: Contains all Skills, each Skill is an independent folder
   - Each Skill includes `SKILL.md` (required), `scripts/` (optional), `references/` (optional), `assets/` (optional)
+- **dev-skills/**: Contains Skills used for Rstack repository maintenance
+  - These Skills are primarily for repository developers and maintainers, not end users
 - **packages/**: Contains source code for complex scripts that need compilation
   - Corresponds to Skills with the same name in the skills directory
   - Compiled by Rslib and output to the corresponding `skills/{skill-name}/scripts/` directory

dev-skills/rstack-repo-maintain/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: rstack-repo-maintain
+description: 'Audit and modernize RstackJS/Rspack ecosystem repositories to the current shared infrastructure baseline: Rslib ESM or dual builds, Rslint recommended rules, Rstest test tooling, Node 20+ support where appropriate, TypeScript 6 and tsgo where compatible, concise README/AGENTS docs, release workflow cleanup, unused dependency removal, and infra PR commit conventions. Use when updating rstackjs repositories, copying infra patterns from maintained exemplars, or reviewing package/tooling consistency.'
+metadata:
+  internal: true
+---
+
+# Rstack Repo Maintain
+
+## Overview
+
+Modernize RstackJS repositories without blindly copying config. Use current repository state and recently maintained exemplar repos to make small, verifiable infrastructure upgrades.
+
+## Baseline Evidence
+
+Read `references/repo-baselines.md` when choosing a template repo, explaining where the baseline came from, or deciding whether a migration should be pure ESM, dual package, Node 20+, TypeScript 6, Rslint, Rstest, or tsgo.
+
+Default starting points:
+
+- Primary small-package baseline: `rstackjs/rslog`.
+- Pure ESM and Node 20 plugin package baseline: `rstackjs/rsbuild-plugin-publint`.
+- Concise AGENTS.md and tsgo/publint reference: `rstackjs/rslog`.
+- Additional package validation reference: `rstackjs/rsbuild-plugin-arethetypeswrong`.
+- Additional Rslib `dts.tsgo` implementation reference: `rstackjs/rsbuild-plugin-virtual-module`.
+
+Always re-check the target repo and exemplar repo before editing. The reference file is a dated snapshot, not a permanent source of truth.
+
+## Workflow
+
+1. **Inventory the target repo**
+   - Read `package.json`, lockfile, `rslib.config.*`, `rslint.config.*`, `rstest.config.*`, `vitest.config.*`, `jest.config.*`, `playwright.config.*`, `tsconfig*.json`, `.github/workflows/*`, `README.md`, `AGENTS.md`, release config, and source entry points.
+   - Identify package kind: library, Rsbuild/Rspack plugin, CLI, app template, test fixture, or docs package.
+   - List current build, lint, typecheck, test, release, and package manager commands before changing them.
+
+2. **Choose the migration target**
+   - Prefer pure ESM for modern libraries and plugins when consumers can support it.
+   - Use dual package output only as a deliberate transition when existing CommonJS consumers or public exports require it.
+   - Treat runtime support, package exports, CLI bins, side effects, and documented deep imports as compatibility constraints.
+
+3. **Update the infrastructure in small layers**
+   - **Rslib**: use `rslib` for builds, keep config minimal, set appropriate `lib.syntax`, emit declarations, and align `package.json#exports` with real output. Add `rsbuild-plugin-publint` when the package should validate publish metadata during build.
+   - **Rslint**: use `@rslint/core`; use `ts.configs.recommended` for TypeScript packages. Add `js.configs.recommended` only when JavaScript source or config files are intentionally linted.
+   - **Prettier**: if the repo already carries Prettier or should check formatting, wire it into lint scripts with the repo's established style (`prettier --check .` / `prettier --write .` or `-c` / `-w`) and keep generated artifacts ignored by `.prettierignore`.
+   - **Test tooling**: prefer Rstest for JavaScript/TypeScript unit tests in Rstack repositories. When a repo still uses Vitest or Jest, use the `migrate-to-rstest` skill, map scripts and configs to `@rstest/core`, keep Playwright or other browser E2E tooling separate, and remove legacy runner deps/configs only after the migrated scope is green.
+   - **Node/CI**: verify the effective Node support policy from code, dependencies, CI, and release workflows. Do not blindly add a Node 20 matrix or an extra CI build step when the maintained baseline intentionally keeps CI latest-only for speed or already builds in release.
+   - **GitHub Actions**: keep `.github/workflows/*` aligned with the chosen baseline repo. Pin third-party actions to commit hashes, not floating tags, and update action pins by copying or refreshing the baseline pattern instead of inventing new pins.
+   - **TypeScript**: upgrade to TypeScript 6, remove stale/deprecated compiler options, prefer `target: "ES2023"` for Node 20+ packages, and keep module resolution consistent with runtime output.
+   - **tsgo**: enable Rslib declaration `dts: { tsgo: true }` only after checking compatibility with declaration bundling, package shape, and installed `@typescript/native-preview`. Pin native-preview to an exact version and validate emitted declarations plus package contents.
+   - **Docs**: keep `README.md` focused on purpose, install, usage, options, supported runtimes, release/license links. Add a concise `AGENTS.md` in the rsbuild-style shape: Stack, Commands, Project structure, and Code style.
+   - **Dependency cleanup**: run a repo-appropriate unused dependency check such as Knip when feasible, then remove only dependencies proven unused or misplaced. Do not add Knip as a dependency unless the repo starts using it in scripts; treat `pnpm stage` and tsgo tool dependencies as known false positives when applicable.
+
+4. **Preserve behavior while modernizing**
+   - Do not touch business logic unless the infra change requires it.
+   - Keep compatibility breaks explicit in commit/PR notes: ESM-only output, removed exports, changed CLI behavior, or dependency placement changes.
+   - If a repo needs multiple risky changes, split them into reviewable PR-sized batches.
+
+5. **Prepare the infra PR**
+   - Create the infrastructure update branch from the latest `origin/main` unless the user asks for a different base.
+   - Use a specific PR title starting with `chore(infra):`, for example `chore(infra): enable tsgo and package validation` or `chore(infra): align build and lint tooling`.
+   - Keep each tool update or tool configuration as its own commit unit. Use commit titles such as `chore(deps): update rslint to 0.6.1`, `chore(infra/tsgo): enable tsgo declaration build`, or `chore(infra/ci): pin workflow actions`.
+   - Do not mix unrelated tool changes, generated lockfile updates, and source fixes in a single commit unless the tool update requires them to stay atomic.
+
+6. **Validate before cleanup**
+   - Run install with the repo package manager.
+   - Run lint, typecheck if present, build, and tests.
+   - Run `npm pack --dry-run` or the repo's publish dry-run path for packages.
+   - Smoke test import/CLI paths that changed.
+   - Remove obsolete configs and dependencies only after the new path is green.
+
+## Output
+
+When reporting back, include:
+
+- Target baseline and why it was chosen.
+- Files changed, grouped by build/lint/TypeScript/CI/docs/dependencies.
+- Breaking changes or compatibility risks.
+- Commands run and their result.
+- Any deliberate deviations from the Rstack baseline.

dev-skills/rstack-repo-maintain/references/repo-baselines.md

@@ -0,0 +1,159 @@
+# Rstack Repository Baselines
+
+Snapshot date: 2026-06-24.
+Primary `rslog` baseline last verified from `origin/main` on 2026-06-24 at commit `25dc20d3402efc3c3104f776a97a81cf9829be67`.
+
+This reference is based on public GitHub PR and repository inspection under `rstackjs/*`. Re-check current main branches before applying these patterns. Secondary reference sections remain at the 2026-06-24 snapshot unless explicitly noted.
+
+## Primary Baseline: rstackjs/rslog
+
+Use `rslog` as the primary maintained baseline when modernizing a small Rstack package.
+
+Why it is the best first template:
+
+- It has the strongest maintenance signal among inspected candidates.
+- It shows the full migration history from Rslib to pure ESM, Node 20+, Rslint, TypeScript 6, and CI cleanup.
+- Its current package shape is simple enough to copy: `type: "module"`, explicit `exports["."].types` and default ESM entry, `files: ["dist"]`, `build: "rslib"`, `lint: "rslint && prettier --check ."`, `lint:write`, `test: "rstest"`, and `packageManager: "pnpm@11.6.0"`.
+- Current `rslib.config.ts` uses `syntax: "es2023"`, `dts: { tsgo: true }`, and `pluginPublint()`.
+- Current `rslint.config.ts` ignores generated `dist` output and keeps `ts.configs.recommended` with no rule overrides because the package is TypeScript-only.
+- Current `rstest.config.ts` enables `globals: true`.
+- Current `tsconfig.json` uses `rootDir: "./src"`, `outDir: "./dist"`, `target: "ES2023"`, `module: "nodenext"`, `moduleResolution: "nodenext"`, and `types: ["node", "@rstest/core/globals"]`.
+- Current dependency pins include `@rslib/core@^0.22.1`, `@rslint/core@^0.6.1`, `@rstest/core@^0.10.4`, `typescript@^6.0.3`, `rsbuild-plugin-publint@^1.0.0`, and exact `@typescript/native-preview@7.0.0-dev.20260615.1`.
+- Current `AGENTS.md` follows the concise rsbuild-style structure: Stack, Commands, Project structure, and Code style.
+- Current `.prettierignore` is intentionally minimal: `dist` and `pnpm-lock.yaml`.
+- CI intentionally keeps an Ubuntu-only Node `24.16.0` test workflow that runs lint and tests, with no separate build step in test CI.
+- Release CI builds before `pnpm stage publish --no-git-checks`, uses OIDC, and keeps `contents: read` plus `id-token: write`.
+- Current workflows pin `actions/checkout`, `actions/setup-node`, and `pnpm/action-setup` to commit hashes with version comments, set `package-manager-cache: false` in setup-node, and let `pnpm/action-setup` handle installation with `run_install: true`.
+
+Useful PRs:
+
+- [#23 chore(build): switch to Rslib](https://github.com/rstackjs/rslog/pull/23)
+- [#33 chore: migrate to Rstest](https://github.com/rstackjs/rslog/pull/33)
+- [#43 chore: remove unused @microsoft/api-extractor dependency](https://github.com/rstackjs/rslog/pull/43)
+- [#59 feat!: transform to pure ESM package and requires Node 20+](https://github.com/rstackjs/rslog/pull/59)
+- [#74 chore: add Rslint as linter](https://github.com/rstackjs/rslog/pull/74)
+- [#76 chore: update TypeScript to v6 and adjust tsconfig settings](https://github.com/rstackjs/rslog/pull/76)
+- [#77 chore: update tsconfig](https://github.com/rstackjs/rslog/pull/77)
+- [#89 chore: optimize CI pnpm setup](https://github.com/rstackjs/rslog/pull/89)
+- [#91 chore: upgrade rslint to 0.6.1](https://github.com/rstackjs/rslog/pull/91)
+- [#93 chore(infra): enable tsgo, publint, and prettier checks](https://github.com/rstackjs/rslog/pull/93)
+
+Review-tested decisions from #93:
+
+- Keep `AGENTS.md` short and close to `rsbuild/AGENTS.md`; avoid a long maintenance manual.
+- Do not mention formatter tools the target repo does not use; use "existing format conventions" or the repo's actual formatter.
+- Keep `js.configs.recommended` out of TypeScript-only packages.
+- `@typescript/native-preview` is a deliberate tsgo toolchain dependency; pin it exactly and validate the generated declarations.
+- `pnpm stage publish` is a pnpm 11 builtin, not a missing dependency.
+- Prefer the current `pnpm/action-setup` + `run_install: true` workflow shape for small pnpm packages; avoid reintroducing ad hoc corepack/install steps unless the target repo needs them.
+- In test CI, run lint and tests, but do not add a build job just to follow a generic checklist when release CI already performs the package build.
+- Knip can be used locally for dependency review, but should not be added as a devDependency unless scripted.
+
+## Secondary Baseline: rstackjs/rsbuild-plugin-publint
+
+Use `rsbuild-plugin-publint` when a plugin package needs a compact pure ESM + Node 20 example.
+
+Current traits:
+
+- `type: "module"`.
+- `exports["."].types` plus ESM default entry.
+- `@rslib/core`, `@rslint/core`, TypeScript 6, and Rstest.
+- `rslib.config.ts` uses `syntax: "es2023"` and `dts: true`.
+
+Useful PRs:
+
+- [#32 chore: upgrade TypeScript to 6.0.2](https://github.com/rstackjs/rsbuild-plugin-publint/pull/32)
+- [#40 chore: migrate linting to Rslint and Prettier](https://github.com/rstackjs/rsbuild-plugin-publint/pull/40)
+- [#49 feat: pure ESM package](https://github.com/rstackjs/rsbuild-plugin-publint/pull/49)
+- [#50 feat!: replace picocolors with styleText and requires Node 20](https://github.com/rstackjs/rsbuild-plugin-publint/pull/50)
+- [#54 chore: optimize CI pnpm setup](https://github.com/rstackjs/rsbuild-plugin-publint/pull/54)
+- [#56 chore: upgrade rslint to 0.6.1](https://github.com/rstackjs/rsbuild-plugin-publint/pull/56)
+
+Known gaps:
+
+- No `AGENTS.md` in current main at snapshot time.
+- No Rslib `dts.tsgo` in current main at snapshot time.
+
+## Package Validation Reference: rstackjs/rsbuild-plugin-arethetypeswrong
+
+Use `rsbuild-plugin-arethetypeswrong` as an additional package validation and staged publishing reference. Use `rslog`, not this repo, as the current AGENTS.md shape.
+
+Current traits:
+
+- `type: "module"`.
+- Rslib build, Rslint, TypeScript 6, and Rstest.
+- `rslint.config.ts` enables both `js.configs.recommended` and `ts.configs.recommended`.
+- Has `AGENTS.md` and README.
+- Rslib config includes `rsbuild-plugin-publint` and bundled declarations.
+
+Useful PRs:
+
+- [#49 chore: switch to npm staged publishing](https://github.com/rstackjs/rsbuild-plugin-arethetypeswrong/pull/49)
+- [#51 chore: build before stage publish](https://github.com/rstackjs/rsbuild-plugin-arethetypeswrong/pull/51)
+- [#55 chore: optimize CI pnpm setup](https://github.com/rstackjs/rsbuild-plugin-arethetypeswrong/pull/55)
+- [#58 chore: upgrade rslint to 0.6.1](https://github.com/rstackjs/rsbuild-plugin-arethetypeswrong/pull/58)
+
+Known gaps:
+
+- Rslib output syntax is `es2022`, not `es2023`, at snapshot time.
+- No Rslib `dts.tsgo` in current main at snapshot time.
+
+## High-Activity Reference: rstackjs/prebundle
+
+Use `prebundle` as a high-activity reference when maintaining a CLI/build-tool style package with generated artifacts.
+
+Current traits:
+
+- High maintenance activity at snapshot time.
+- Rslib build, Rslint, TypeScript 6, Rstest, README, and `AGENTS.md`.
+- `rslint.config.ts` enables both `js.configs.recommended` and `ts.configs.recommended`.
+
+Useful PRs:
+
+- [#10 refactor: use Rslib to bundle](https://github.com/rstackjs/prebundle/pull/10)
+- [#37 chore: enable npm trusted publishing](https://github.com/rstackjs/prebundle/pull/37)
+- [#62 chore: upgrade TypeScript to ^6.0.2](https://github.com/rstackjs/prebundle/pull/62)
+- [#72 chore: add Rslint linting](https://github.com/rstackjs/prebundle/pull/72)
+- [#81 chore: optimize CI pnpm setup](https://github.com/rstackjs/prebundle/pull/81)
+- [#83 chore: upgrade rslint to 0.6.1](https://github.com/rstackjs/prebundle/pull/83)
+
+Known gaps:
+
+- Rslib syntax is `es2021`, so do not copy it for Node 20+/ES2023 packages without checking why.
+
+## tsgo Reference: rstackjs/rsbuild-plugin-virtual-module
+
+Use `rsbuild-plugin-virtual-module` only as a concrete Rslib `tsgo` configuration reference.
+
+Current traits:
+
+- `rslib.config.ts` uses `dts: { tsgo: true }`.
+- `@typescript/native-preview` is installed.
+- Dual package output is still present.
+
+Relevant PR:
+
+- [#28 chore: update infrastructure for tsgo](https://github.com/rstackjs/rsbuild-plugin-virtual-module/pull/28)
+
+Important caveat:
+
+- Treat this repo as implementation evidence for Rslib tsgo, not as the primary small-package baseline.
+
+## Search Notes
+
+Searches used:
+
+- `type:pr org:rstackjs rslib`
+- `type:pr org:rstackjs rslint`
+- `type:pr org:rstackjs "typescript 6"`
+- `type:pr org:rstackjs "Node 20"`
+- `type:pr org:rstackjs AGENTS`
+- `type:pr org:rstackjs README`
+- `type:pr org:rstackjs "optimize CI"`
+- `type:pr org:rstackjs knip`
+
+Findings:
+
+- No repo-owned scripted Knip baseline was found in the sampled search results.
+- `rslog` now provides the reviewed tsgo + publint baseline for small packages; `rsbuild-plugin-virtual-module` remains useful only as an additional implementation reference.
+- Some heavily maintained packages intentionally remain dual package or use lower output syntax; copy only after checking consumer compatibility.