init-release-base-relizy-and-bumpp

Init Release Base — Relizy + Bumpp Monorepo release configuration implementation skill

This skill is anexecution-typeworkflow: set up the combined release solution of relizy (sub-packages) + bumpp (root package) for a pnpm monorepo in one go, covering the complete integration chain from repository health check, configuration persistence, dependency alignment, and failure pre-check, to dry-run verification and documentation sync.

Design philosophy

1. Local control of tag generation: developers run pnpm release locally to complete all version management with a single command
2. Cloud handles GitHub Release: after GitHub Actions detects a tag push, it automatically extracts content from CHANGELOG.md to create a Release
3. Single push: all tags in the serial main chain (sub-packages + root package) are pushed in one git push --follow-tags push
4. The root package has two valid entry points: the serial main chain uses release:root + --no-push; standalone root package releases use release:bumpp + --push
5. Two tools collaborate: relizy handles sub-packages (independent mode), bumpp handles the root package, each fulfilling its own role

Relationship with package-linter relationship

If you are also creating or normalizing sub-packages at the same time, please first or in parallel refer to the package-linter skill in the repository to ensure package.json / tsup / tsconfig is consistent with the monorepo conventions; this skill focuses on the configuration and decisions of therelease domain.

Runner: you must use @ruan-cat/utils of relizy-runner(creating your own scripts is prohibited)

The compatibility layer (Windows GNU tool completion + automatic preparation of independent baseline tags) is implemented by the @ruan-cat/utils package and invoked via relizy-runner bin .Must notcreate scripts/relizy-runner.ts or any local runner copy in the target repository.

• Authoritative documentation: the relizy-runner documentation in the relizy-runner --help and @ruan-cat/utils packages installed in the target repository shall prevail.
• Invocation convention: you must use package.json of bin(such as npx relizy-runner … / pnpm exec relizy-runner …），Prohibitedto use tsx @ruan-cat/utils/relizy-runner and other forms that bypass exports.
• baseline behavior：release / bump When an independent baseline tag is missing, annotated bootstrap tags will be created according to the current package.json version. With --no-push , only local tags are kept, and subsequent git push --follow-tags will carry them; without --no-push , atomic push is used to push this round of tags.
• Write-prohibited behavior：--dry-run or --no-commit No tags will be created under this; when the baseline is missing, only manual fallback commands are printed and it stops.

--yes and non-interactive releases

relizy may pop up interactions in processes such as release / bump ; it will hang without a TTY or in CI.In the serial main chain, release:sub and release:root must explicitly write --yes, including package.json scripts, README, and verification commands. The standalone entry point release:bumpp retains bumpp's interactive version selection by default and pushes the root tag immediately via --push ; if the target repository really needs fully non-interactive behavior, then explicitly append --yes。

Release process architecture

pnpm release
    │
    ├── 1. pnpm run release:sub（relizy）
    │   ├── 必要时创建本地 annotated baseline tags（--no-push 下不推送）
    │   ├── 分析各子包 commits → bump → CHANGELOG → commit → tag
    │   └── 不 push（--no-push）
    │
    ├── 2. pnpm run release:root（bumpp）
    │   ├── bump 根包 patch → changelogen → commit → tag
    │   └── 不 push（--no-push）
    │
    └── 3. pnpm run git:push
        └── git push --follow-tags（一次性推送）

For detailed architecture description, see references/release-workflow-architecture.md。

Used when releasing the root package separately:

pnpm run release:bumpp
    ├── bumpp 交互式选择根包版本
    ├── 生成根包 commit + tag
    └── 立即 push（--push）

Configuration files written to disk in one go

File	Purpose	Template
bump.config.ts	Root package release (bumpp)	templates/bump.config.ts
changelog.config.ts	Shared changelog configuration	templates/changelog.config.ts
changelogithub.config.ts	changelogithub integration	templates/changelogithub.config.ts
relizy.config.ts	Subpackage release (relizy)	templates/relizy.config.ts
.github/workflows/release.yaml	GitHub Release automation	templates/release.yaml

Dependency list

During integration, the following devDependencies must be installed (versions are subject to the latest in the registry):

pnpm add -D bumpp changelogen changelogithub relizy @ruan-cat/commitlint-config @ruan-cat/utils @types/node pnpm-workspace-yaml

Root package scripts template

See templates/package-scripts.mdfor details. Key commands:

{
	"release": "pnpm run release:sub && pnpm run release:root && pnpm run git:push",
	"release:sub": "relizy-runner release --no-publish --no-provider-release --no-push --yes",
	"release:root": "bumpp --no-push --yes --release patch",
	"release:bumpp": "bumpp --push",
	"changelog:root": "changelogen --output CHANGELOG.md",
	"git:push": "git push --follow-tags"
}

Three-layer directory

Layer	Path	Purpose
Process and checklist	SKILL.md(this file)	Phase division, blocking conditions, index
Copyable snippets and templates	templates/	Configuration file templates, reconnaissance output, confirmation checklist, scripts templates
Principles and decision basis	references/	Decision tree, pitfalls, verification matrix, failure pre-check, architecture description

Non-goals (must be observed)

• Do not execute npm publishby default, and do not enable provider release by default.
• Do not write this skill as a dedicated script for a specific private or fixed repository.
• When the private strategy is unconfirmed and the compatibility strategy is undecided , do not blindly write to disk.
• Prohibitedto create a local runner script in the target repository.
• Do not confuse selective with "independent version lines for each package".

Standard six-phase process

Task Progress:
- [ ] 阶段 1 — 侦察：收集工作区、锁文件、现有发版工具、tag、private、README/CHANGELOG 边界（用 templates/workspace-discovery.md）
- [ ] 阶段 2 — 确认：仅对高风险项确认（versionMode、全量纳管、private、兼容策略）（用 templates/package-eligibility.md）
- [ ] 阶段 3 — 故障预检：检查是否存在 commit-and-tag-version、conventional-changelog-cli 等遗留根包发版工具（见 references/dependency-conflict-precheck.md）
- [ ] 阶段 4 — 落盘：依赖安装、5 个配置文件写入、根 scripts 配置、必要时最小 tsconfig（用 templates/config-writer.md + 各 templates/*.ts）
- [ ] 阶段 5 — 验证：help、changelog dry-run、release dry-run（见 references/verification-matrix.md）
- [ ] 阶段 6 — 收尾：修改清单、破坏性说明、残余风险、下一步（用 templates/docs-sync.md）

Explicit blocking conditions (must not be skipped)

When any of the following holds,stop automatic writing to disk, and instead only output the plan and user confirmation:

• The user requests "independent versions for each subpackage", yet selective is planned to be used as the independent versioning solution.
• The packages planned to be included in relizy involve private: true changes, but confirmation has not been obtained.
• It is confirmed that relizy-runnerwill not be used, but manual baseline tag confirmation has not been completed.
• On Windows, grep / head / sed type failures have been observed, but no compatibility strategy has been chosen.
• A legacy root package release tool is detected(such as commit-and-tag-version、conventional-changelog-cli、standard-version、release-it), but it has not yet been confirmed whether to delete or isolate it (see references/dependency-conflict-precheck.md）。

Core decisions (quick reference)

1. versionMode: "independent version line for each package" → independent; "only bump changed packages and share one release semantics" ≠ independent version lines.
2. Compatibility strategy：Preferred relizy-runner(Windows GNU tools + automatic baseline tag preparation).
3. Documentation boundary：rootChangelog and README updates are two separate chains;formatCmd should not be broad enough to mistakenly modify the README.
4. Root package release: handled independently by bumpp,bump.config.ts does not hard-code push; the serial entry point release:root uses --no-push, the standalone entry point release:bumpp uses --push, and through the execute function calls changelogen --output CHANGELOG.md -r <newVersion>。
5. GitHub Release: used by CI with gh release create extracted from CHANGELOG.md, without relying on changelogithub / relizy provider-release.

templates/ index

File	Purpose
templates/bump.config.ts	bumpp root package release configuration template
templates/changelog.config.ts	Shared changelog configuration template
templates/changelogithub.config.ts	changelogithub configuration template
templates/relizy.config.ts	relizy subpackage release configuration template
templates/release.yaml	GitHub Actions Release workflow template
templates/package-scripts.md	Complete root package scripts template and description
templates/workspace-discovery.md	Structured output of reconnaissance results
templates/package-eligibility.md	Managed scope and private confirmation
templates/config-writer.md	Configuration and script persistence skeleton
templates/runtime-compat.md	Compatibility strategy record
templates/docs-sync.md	README release section template

references/ index

File	Content
references/overview.md	Skill knowledge map and recommended implementation order
references/release-workflow-architecture.md	Detailed explanation of the relizy + bumpp combined release architecture
references/dependency-conflict-precheck.md	Legacy root package release tool pre-check
references/discovery-checklist.md	Reconnaissance signal checklist
references/version-mode-decision.md	independent / selective / unified version line
references/config-templates.md	Configuration slots and file roles
references/type-compatibility.md	types and changelogen consolidation
references/windows-compatibility.md	relizy-runner / patch / no layer
references/baseline-tags.md	Independent mode and package tags
references/package-visibility.md	private and scan scope
references/readme-and-changelog-boundaries.md	Root CHANGELOG and README
references/verification-matrix.md	Verification command matrix
references/rollback-and-risks.md	Rollback and stop-loss
references/validated-archetypes.md	Prototype comparison and expected decision checklist

Verification command baseline (run in root directory)

See references/verification-matrix.md。

relizy subpackage verification (using relizy-runner)：

pnpm exec relizy-runner --help
pnpm exec relizy-runner changelog --dry-run --yes
pnpm exec relizy-runner release --dry-run --no-publish --no-provider-release --no-push --no-commit --no-clean --yes

bumpp root package verification：

pnpm exec bumpp --help
pnpm exec bumpp --dry-run --release patch
pnpm exec changelogen --output CHANGELOG.md -r 0.0.1
git ls-remote --tags origin "v0.0.1"

Expected root package changelog to generate version heading ## v0.0.1, not range heading ## v0.0.0...main。

If a root package tag already exists locally, but GitHub Actions' release.yaml was not triggered, first check whether the remote tag exists, rather than immediately suspecting the workflow's CHANGELOG extraction logic.

If release:dry or the dry-run in the verification matrix indicates missing independent baseline tags, this is the expected write-protection: dry-run will not create tags. On first integration, use a real release:sub --no-push to automatically create local annotated baseline tags, or manually create them as prompted and then re-run dry-run.

If the output is "no packages to bump" and there are no configuration/cross-platform errors, it should be interpreted asverification passed but there are currently no changes to release。