init-relizy

Init Relizy — Monorepo Release Configuration Implementation Skill

This skill is anexecution-orientedworkflow: from repository health check, strategy confirmation, file writing, compatibility branch selection, to dry-run verification and documentation sync, it covers the complete integration pipeline. It is not a consulting skill that "only gives suggestions."

Relationship with package-linter relationship

If you are also creating or normalizing subpackages, 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 the relizy release domain .

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

The compatibility layer (Windows GNU tool supplementation + independent baseline tag pre-check) 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 as the implementation approach.

• Authoritative documentation(behavior, parameters, root script examples): see packages/utils/src/node-esm/scripts/relizy-runner/index.mdin the repository; if an online direct link is needed, you may refer to:https://raw.githubusercontent.com/ruan-cat/monorepo/refs/heads/dev/packages/utils/src/node-esm/scripts/relizy-runner/index.md
• Invocation convention: you must use package.json 's bin(such as npx relizy-runner … / pnpm exec relizy-runner …），Prohibitedto use tsx @ruan-cat/utils/relizy-runner and other forms that bypass exports (see "Must use bin command invocation" in that document).

--yes and non-interactive releases (the skill must pass explicitly)

Background: relizy may pop up "continue?"-type interactions in release / bump and other flows; under no TTY or in CI it willwait on stdin indefinitely, manifesting as a hung process. The upstream option --yes means Skip confirmation prompt, and is unrelated to the version calculation algorithm.

Relationship with relizy-runner relationship: newer versions of @ruan-cat/utils will, on the release / bump subcommand,automatically append --yes(unless the runner-specific --no-yes is used to disable it). Even so,when executing this skill you must still explicitly write --yesin all content written to disk, including:

1. Root package.json all relizy-runner release、relizy-runner bumpin it (if configured) and changelog examples that need to run non-interactively;
2. Equivalent commands in README / internal documentation;
3. The examples in the "Verification command baseline" below in this file and in references/verification-matrix.md .

Reason: scripts and documentation are self-describing, consistent with CI copy-paste, compatible with older versions of @ruan-cat/utilsthat do not yet have built-in automatic injection, and cover paths such as changelog where the runner does not inject --yes by default.

Locally requiring step-by-step manual confirmation: use the runner's --no-yes(consumed by the runner, not forwarded to relizy), see packages/utils/.../relizy-runner/index.md。

When directly connecting to relizy(without a runner): for any example command involving release / bump , --yesmust likewise be included, unless the documentation is explicitly demonstrating interactive mode.

Three-layer directory

Level	Path	Purpose
Process and checklist	SKILL.md(this file)	Stage division, blocking conditions, index
Copyable snippets and tables	templates/	Reconnaissance output, confirmation checklist, configuration skeleton, README paragraph
Principles and decision basis	references/	Decision tree, pitfalls, verification matrix, anonymous prototype comparison (including expected decision check items)

When executing:First read the stages in this file → open templates as needed to fill in forms → consult references for conceptual questions。

Non-goals (must be observed)

• Do not execute by default npm publish, and do not enable provider release by default.
• Do not write this skill as a dedicated script for a specific private or fixed repository; a specific repository may only be studied as an **anonymous "verified prototype"**, see references/validated-archetypes.md。
• When private the strategy is unconfirmed and the compatibility strategy is undecided , do not blindly rewrite the release script or claim "integration is complete".
• Do not skip @ruan-cat/utils of relizy-runnerby default on the grounds that "the baseline tag issue has been verified to be absent"; if you insist on not using this bin, there must be a clear manual verification record (see references/baseline-tags.md）。
• ProhibitedFor integrating relizy, in the target repositorycreatea local runner script; uniformly complete execution through @ruan-cat/utils dependencies and the relizy-runner command.
• Do not conflate selective with "independent version lines for each package".

Standard five-stage process

Task Progress:
- [ ] 阶段 1 — 侦察：收集工作区、锁文件、现有发版工具、tag、`private`、README/CHANGELOG 边界（用 templates/workspace-discovery.md）
- [ ] 阶段 2 — 第一次确认：仅对高风险项确认（versionMode、全量纳管、`private`、兼容策略、是否写 README）（用 templates/package-eligibility.md）
- [ ] 阶段 3 — 落盘：依赖（含 `@ruan-cat/utils` + `relizy`）、changelog.config.ts、relizy.config.ts（含 `release` 默认块）、根脚本指向 `relizy-runner` 且 **显式包含 `--yes`**（见上节）、可选 pnpm patch、必要时最小 tsconfig（用 templates/config-writer.md + references/config-templates.md）
- [ ] 阶段 4 — 验证：帮助、changelog dry-run、release dry-run（必要时 --no-publish 等），见 references/verification-matrix.md
- [ ] 阶段 5 — 收尾：修改清单、破坏性说明、残余风险、下一步（用 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 intends to use selective as the independent version solution (see references/version-mode-decision.md）。
• The packages intended to be included in relizy involve private: true changes, but no written/conversational confirmation has been obtained (see references/package-visibility.md）。
• Confirm not to use relizy-runner（@ruan-cat/utils), but manual baseline tag confirmation has not been completed and no supplementary tagging mechanism has been established (see references/baseline-tags.md）。
• On Windows, grep / head / sed -type failures have been observed, but no compatibility strategy has been chosen (see references/windows-compatibility.md）。

Core decisions (quick reference)

1. versionMode: "independent version line per package" → independent; "only bump changed packages and share one release semantics" ≠ independent version lines, see the decision table.
2. Compatibility strategy：Preferred @ruan-cat/utils provided by relizy-runner bin(simultaneously solves the Windows GNU tool issue and baseline tag pre-check); second choice pnpm patch(only solves the Windows tool issue, baseline tags must be handled separately); no additional layer is usable only when strict prerequisites are met (see references/windows-compatibility.md）。
3. Documentation boundaries：rootChangelog and README updates are two separate chains;formatCmd should not be so broad as to mistakenly modify the README, see references/readme-and-changelog-boundaries.md。

templates/ index

File	Purpose
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 writing skeleton (including @ruan-cat/utils / relizy-runner integration steps)
templates/runtime-compat.md	Compatibility strategy record (relizy-runner bin is the default recommendation)
templates/docs-sync.md	README release section template

references/ index

File	Content
references/overview.md	Skill knowledge map and recommended rollout order
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 closure
references/windows-compatibility.md	relizy-runner / patch / no layer
references/baseline-tags.md	Standalone 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	Comparison of three archetypes + expected decision checklist (no repository names)

Verification command baseline (run from root directory)

For specific flags and failure attribution, see references/verification-matrix.md。

When relizy-runner(recommended) is already integrated, prefer using bin to perform verification along the same path as the release:

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

When not using a runner and connecting directly to relizy(the "no extra layer" prerequisite in references/windows-compatibility.md must already be satisfied):

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

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, rather than a configuration failure.