---
title: "feat: Migrate repo releases to manual release-please with centralized changelog"
description: "Replace the current single-line `semantic-release` flow and maintainer-local `release-docs` workflow with a repo-owned release system built around `release-please`, a single accumulating release PR, explicit component version ownership, release automation-owned metadata/count updates, and a centralized root `CHANGELOG.md`. The new model keeps release timing manual by making merge of the generated "
type: skill
canonical_url: https://claudary.paisolsolutions.com/skills/2026-03-17-001-feat-release-automation-migration-beta-plan
source: "Claudary"
difficulty: intermediate
author: "Claude Code Knowledge Pack"
date: 2026-07-10T10:59:00.361Z
license: CC-BY-4.0
attribution: "feat: Migrate repo releases to manual release-please with centralized changelog — Claudary (https://claudary.paisolsolutions.com/skills/2026-03-17-001-feat-release-automation-migration-beta-plan)"
---

# feat: Migrate repo releases to manual release-please with centralized changelog
Replace the current single-line `semantic-release` flow and maintainer-local `release-docs` workflow with a repo-owned release system built around `release-please`, a single accumulating release PR, explicit component version ownership, release automation-owned metadata/count updates, and a centralized root `CHANGELOG.md`. The new model keeps release timing manual by making merge of the generated 

## Overview

---
title: "feat: Migrate repo releases to manual release-please with centralized changelog"
type: feat
status: active
date: 2026-03-17
origin: docs/brainstorms/2026-03-17-release-automation-requirements.md
---

# feat: Migrate repo releases to manual release-please with centralized changelog

## Overview

Replace the current single-line `semantic-release` flow and maintainer-local `release-docs` workflow with a repo-owned release system built around `release-please`, a single accumulating release PR, explicit component version ownership, release automation-owned metadata/count updates, and a centralized root `CHANGELOG.md`. The new model keeps release timing manual by making merge of the generated release PR the release action while allowing dry-run previews and automatic release PR maintenance as new merges land on `main`.

## Problem Frame

The current repo mixes one automated root CLI release line with manual plugin release conventions and stale docs/tooling. `publish.yml` publishes on every push to `main`, `.releaserc.json` only understands the root package, `release-docs` still encodes outdated repo structure, and plugin-level version/changelog ownership is inconsistent. The result is drift across root changelog history, plugin manifests, computed counts, and contributor guidance. The origin requirements define a different target: manual release timing, one release PR for the whole repo, independent component versions, no bumps for untouched plugins, centralized changelog ownership, and CI-owned release authority. (see origin: docs/brainstorms/2026-03-17-release-automation-requirements.md)

## Requirements Trace

- R1. Manual release; no publish on every merge to `main`
- R2. Batched releasable changes may accumulate on `main`
- R3. One release PR for the whole repo that auto-accumulates releasable merges
- R4. Independent version bumps for `cli`, `compound-engineering`, `coding-tutor`, and `marketplace`
- R5. Untouched components do not bump
- R6. Root `CHANGELOG.md` remains canonical
- R7. Root changelog uses top-level component-version entries
- R8. Existing changelog history is preserved
- R9. `plugins/compound-engineering/CHANGELOG.md` is no longer canonical
- R10. Retire `release-docs` as release authority
- R11. Replace `release-docs` with narrow scripts
- R12. Release automation owns versions, counts, and release metadata
- R13. Support dry run with no side effects
- R14. Dry run summarizes proposed component bumps, changelog entries, and blockers
- R15. Marketplace version bumps only for marketplace-level changes
- R16. Plugin version changes do not imply marketplace version bumps
- R17. Plugin-only content changes do not force CLI version bumps
- R18. Preserve compatibility with current install behavior where the npm CLI fetches plugin content from GitHub at runtime
- R19. Release flow is triggerable through CI by maintainers or AI agents
- R20. The model must scale to additional plugins
- R21. Conventional release intent signals remain required, but component scopes in titles remain optional
- R22. Component ownership is inferred primarily from changed files, not title scopes alone
- R23. The repo enforces parseable conventional PR or merge titles without requiring component scope on every change
- R24. Manual CI release supports explicit bump overrides for exceptional cases without fake commits
- R25. Bump overrides are per-component rather than repo-wide only
- R26. Dry run shows inferred bump and applied override clearly

## Scope Boundaries

- No change to how Claude Code consumes marketplace/plugin version fields
- No end-user auto-update discovery flow for non-Claude harnesses in v1
- No per-plugin canonical changelog model
- No fully automatic timed release cadence in v1

## Context & Research

### Relevant Code and Patterns

- `.github/workflows/publish.yml` currently runs `npx semantic-release` on every push to `main`; this is the behavior being retired.
- `.releaserc.json` is the current single-line release configuration and only writes `CHANGELOG.md` and `package.json`.
- `package.json` already exposes repo-maintenance scripts and is the natural place to add release preview/validation script entrypoints.
- `src/commands/install.ts` resolves named plugin installs by cloning the GitHub repo and reading `plugins/<name>` at runtime; this means plugin content releases can remain independent from npm CLI releases when CLI code is unchanged.
- `.claude-plugin/marketplace.json`, `plugins/compound-engineering/.claude-plugin/plugin.json`, and `plugins/coding-tutor/.claude-plugin/plugin.json` are the current version-bearing metadata surfaces that need explicit ownership.
- `.claude/commands/release-docs.md` is stale and mixes docs generation, metadata synchronization, validation, and release guidance; it should be replaced rather than modernized in place.
- Existing planning docs in `docs/plans/` use one file per plan, frontmatter with `origin`, and dependency-ordered implementation units with explicit file paths; this plan follows that pattern.

### Institutional Learnings

- `docs/solutions/plugin-versioning-requirements.md` already encodes an important constraint: version bumps and changelog entries should be release-owned, not added in routine feature PRs. The migration should preserve that principle while moving the authority into CI.

### External References

- `release-please` release PR model supports maintaining a standing release PR that updates as more work lands on the default branch.
- `release-please` manifest mode supports multi-component repos and per-component extra file updates, which is a strong fit for plugin manifests and marketplace metadata.
- GitHub Actions `workflow_dispatch` provides a stable manual trigger surface for dry-run preview workflows.

## Key Technical Decisions

- **Use `release-please` for version planning and release PR lifecycle**: The repo needs one accumulating release PR with multiple independently versioned components; that is closer to `release-please`'s native model than to `semantic-release`.
- **Keep one centralized root changelog**: The root `CHANGELOG.md` remains the canonical changelog. Release automation must render component-labeled entries into that one file rather than splitting canonical history across plugin-local changelog files.
- **Use top-level component-version entries in the root changelog**: Each released component version gets its own top-level entry in `CHANGELOG.md`, including the component name, version, and release date in the heading. This keeps one centralized file while preserving readable independent version history.
- **Treat component versioning and changelog rendering as related but separate concerns**: `release-please` can own component version bumps and release PR state, but root changelog formatting may require repo-specific rendering logic to preserve a single readable canonical file.
- **Use explicit release scripts for repo-specific logic**: Count computation, metadata sync, dry-run summaries, and root changelog shaping should live in versioned scripts rather than hidden maintainer-local command prompts.
- **Preserve current plugin delivery assumptions**: Plugin content updates do not force CLI version bumps unless the converter/installer behavior in `src/` changes.
- **Marketplace is catalog-scoped**: Marketplace version bumps depend on marketplace file changes such as plugin additions/removals or marketplace metadata edits, not routine plugin release version updates.
- **Use conventional type as release intent, not mandatory component scope**: `feat`, `fix`, and explicit breaking-change markers remain important release signals, but component scope in PR or merge titles is optional and should not be required for common compound-engineering work.
- **File ownership is authoritative for component selection**: Optional title scope can help notes and validation, but changed-file ownership rules should decide which components bump.
- **Support manual bump overrides as an explicit escape hatch**: Inferred bumping remains the default, but the CI-driven release flow should allow per-component `patch` / `minor` / `major` overrides for exceptional cases without requiring synthetic commits on `main`.
- **Deprecate, do not rely on, legacy changelog/docs surfaces**: `plugins/compound-engineering/CHANGELOG.md` and `release-docs` should stop being live authorities; they should be removed, frozen, or reduced to pointer guidance only after the new flow is in place.

## Root Changelog Format

The root `CHANGELOG.md` should remain the only canonical changelog and should use component-version entries rather than repo-wide release-event entries.

### Format Rules

- Each released component gets its own top-level entry.
- Entry headings include the component name, version, and release date.
- Entries are ordered newest-first in the single root file.
- When multiple components release from the same merged release PR, they appear as adjacent entries with the same date.
- Each entry contains only changes relevant to that component.
- The file keeps a short header note explaining that it is the canonical changelog for the repo and that versions are component-scoped.
- Historical root changelog entries remain in place; the migration adds a note and changes formatting only for new entries after cutover.

### Recommended Heading Shape

```md
## compound-engineering v2.43.0 - 2026-04-10

### Features
- ...

### Fixes
- ...
```

Additional examples:

```md
## coding-tutor v1.2.2 - 2026-04-18

### Fixes
- ...

## marketplace v1.3.0 - 2026-04-18

### Changed
- Added `new-plugin` to the marketplace catalog.

## cli v2.43.1 - 2026-04-21

### Fixes
- Correct OpenClaw install path handling.
```

### Migration Rules

- Preserve all existing root changelog history as published.
- Add a short migration note near the top stating that, starting with the cutover release, entries are recorded per component version in the root file.
- Do not attempt to rewrite or normalize all older entries into the new structure.
- `plugins/compound-engineering/CHANGELOG.md` should no longer receive new canonical entries after cutover.

## Component Release Rules

The release system should use explicit file-to-component ownership rules so unchanged components do not bump accidentally.

### Component Definitions

- **`cli`**: The npm-distributed `@every-env/compound-plugin` package and its release-owned root metadata.
- **`compound-engineering`**: The plugin rooted at `plugins/compound-engineering/`.
- **`coding-tutor`**: The plugin rooted at `plugins/coding-tutor/`.
- **`marketplace`**: Marketplace-level metadata rooted at `.claude-plugin/` and any future repo-owned marketplace-only surfaces.

### File-to-Component Mapping

#### `cli`

Changes that should trigger a `cli` release:

- `src/**`
- `package.json`
- `bun.lock`
- CLI-only tests or fixtures that validate root CLI behavior:
  - `tests/cli.test.ts`
  - other top-level tests whose subject is the CLI itself
- Release-owned root files only when they reflect a CLI release rather than another component:
  - root `CHANGELOG.md` entry generation for the `cli` component

Changes that should **not** trigger `cli` by themselves:

- Plugin content changes under `plugins/**`
- Marketplace metadata changes under `.claude-plugin/**`
- Docs or brainstorm/plan documents unless the repo explicitly decides docs-only changes are releasable for the CLI

#### `compound-engineering`

Changes that should trigger a `compound-engineering` release:

- `plugins/compound-engineering/**`
- Tests or fixtures whose primary purpose is validating compound-engineering content or conversion results derived from that plugin
- Release-owned metadata updates for the compound-engineering plugin:
  - `plugins/compound-engineering/.claude-plugin/plugin.json`
- Root `CHANGELOG.md` entry generation for the `compound-engineering` component

Changes that should **not** trigger `compound-engineering` by themselves:

- `plugins/coding-tutor/**`
- Root CLI implementation changes in `src/**`
- Marketplace-only metadata changes

#### `coding-tutor`

Changes that should trigger a `coding-tutor` release:

- `plugins/coding-tutor/**`
- Tests or fixtures whose primary purpose is validating coding-tutor content or conversion results derived from that plugin
- Release-owned metadata updates for the coding-tutor plugin:
  - `plugins/coding-tutor/.claude-plugin/plugin.json`
- Root `CHANGELOG.md` entry generation for the `coding-tutor` component

Changes that should **not** trigger `coding-tutor` by themselves:

- `plugins/compound-engineering/**`
- Root CLI implementation changes in `src/**`
- Marketplace-only metadata changes

#### `marketplace`

Changes that should trigger a `marketplace` release:

- `.claude-plugin/marketplace.json`
- Future marketplace-only docs or config files if the repo later introduces them
- Adding a new plugin directory under `plugins/` when that addition is accompanied by marketplace catalog changes
- Removing a plugin from the marketplace catalog
- Marketplace metadata changes such as owner info, catalog description, or catalog-level structure changes

Changes that should **not** trigger `marketplace` by themselves:

- Routine version bumps to existing plugin manifests
- Plugin-only content changes under `plugins/compound-engineering/**` or `plugins/coding-tutor/**`
- Root CLI implementation changes in `src/**`

### Multi-Component Rules

- A single merged PR may trigger multiple components when it changes files owned by each of those components.
- A plugin content change plus a CLI behavior change should release both the plugin and `cli`.
- Adding a new plugin should release at least the new plugin and `marketplace`; it should release `cli` only if the CLI behavior, plugin discovery logic, or install UX also changed.
- Root `CHANGELOG.md` should not itself be used as the primary signal for component detection; it is a release output, not an input.
- Release-owned metadata writes generated by the release flow should not recursively cause unrelated component bumps on subsequent runs.

### Release Intent Rules

- The repo should continue to require conventional release intent markers such as `feat:`, `fix:`, and explicit breaking change notation.
- Component scopes such as `feat(coding-tutor): ...` are optional and should remain optional.
- When a scope is present, it should be treated as advisory metadata that can improve release note grouping or mismatch detection.
- When no scope is present, release automation should still work correctly by using changed-file ownership to determine affected components.
- Docs-only, planning-only, or maintenance-only titles such as `docs:` or `chore:` should remain parseable even when they do not imply a releasable component bump.

### Manual Override Rules

- Automatic bump inference remains the default for all components.
- The manual CI workflow should support override values of at least `patch`, `minor`, a

---

Source: [Claudary](https://claudary.paisolsolutions.com/skills/2026-03-17-001-feat-release-automation-migration-beta-plan) · https://claudary.paisolsolutions.com