# How Plugin Versioning Requirements Are Enforced in the Compound Engineering Plugin

> Learn how Compound Engineering Plugin enforces versioning requirements with a manual checklist and code review. Update plugin json changelog and readme for merges.

- Repository: [Every/compound-engineering-plugin](https://github.com/everyinc/compound-engineering-plugin)
- Tags: internals
- Published: 2026-02-16

---

**Plugin versioning requirements are enforced through a mandatory manual checklist and code review process that requires updating [`.claude-plugin/plugin.json`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/.claude-plugin/plugin.json), [`CHANGELOG.md`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/CHANGELOG.md), and [`README.md`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/README.md) before any change is merged.**

The EveryInc/compound-engineering-plugin repository implements strict plugin versioning requirements through a documented workflow defined in the solution document **"Plugin Versioning and Documentation Requirements"** rather than automated CI gates. This process ensures that every modification is tracked via semantic versioning, documented in a changelog, and reflected in component inventory tables.

## The Three Files That Control Plugin Versioning Requirements

### [`.claude-plugin/plugin.json`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/.claude-plugin/plugin.json) — The Version Manifest

The [`.claude-plugin/plugin.json`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/.claude-plugin/plugin.json) file stores the canonical `version` field that the CLI uses for downstream generation targeting OpenCode, Codex, and Gemini. According to the solution document, every change must bump this value following **Semantic Versioning (semver)** rules—MAJOR for breaking changes, MINOR for new features, and PATCH for bug fixes.

```json
{
  "name": "compound-engineering",
  "version": "1.3.0",
  "description": "Tools that make each unit of engineering work easier."
}

```

### [`CHANGELOG.md`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/CHANGELOG.md) — The Change History

The [`CHANGELOG.md`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/CHANGELOG.md) file maintains a human-readable log of what changed for each version. The plugin versioning requirements mandate using the **Keep a Changelog** format, with new entries added under `## [Unreleased]` or a new version section. Entries must be categorized under `### Added`, `### Changed`, `### Deprecated`, `### Removed`, `### Fixed`, or `### Security`.

```markdown

## [1.3.0] - 2026-02-15

### Added

- New agent **Style Reviewer** for enforcing code style guidelines.
- New command **/workflows:plan** improvements.

### Fixed

- Minor typo in README component count.

```

### [`README.md`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/README.md) — The Component Inventory

The [`README.md`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/README.md) contains tables listing the plugin's agents, commands, and skills, along with component counts displayed at the top of the file. The plugin versioning requirements require that these tables and counts be verified and updated whenever components are added, removed, or renamed. This prevents documentation drift between the manifest and the implementation.

```markdown
| Component | Count |
|-----------|-------|
| Agents    | 12    |
| Commands  | 7     |
| Skills    | 15    |

```

## How the Versioning Workflow Enforces Compliance

The enforcement mechanism is defined in [`docs/solutions/plugin-versioning-requirements.md`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/docs/solutions/plugin-versioning-requirements.md) and operates through a four-step manual process backed by code review discipline.

### Step 1: Bump the Semantic Version

Contributors must increment the `version` field in [`.claude-plugin/plugin.json`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/.claude-plugin/plugin.json) according to semver rules. This version is consumed by the CLI for downstream generation, making accuracy critical for OpenCode, Codex, and Gemini integrations.

### Step 2: Document Changes in [`CHANGELOG.md`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/CHANGELOG.md)

Every pull request must add a changelog entry describing added, changed, deprecated, removed, fixed, or security-related items. The entry follows the Keep a Changelog format and is placed under the unreleased section or a new version header.

### Step 3: Synchronize [`README.md`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/README.md) Component Counts

When agents, commands, or skills are modified, contributors must reconcile the component counts in [`README.md`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/README.md) with the actual file system and update the relevant tables. This ensures the documentation reflects the current codebase state.

### Step 4: Complete the Mandatory Checklist

Before committing, contributors must tick off a markdown checklist that includes all three items above. The checklist lives in the solution document and is verified during code review:

```markdown
- [ ] Version bumped in `.claude-plugin/plugin.json`
- [ ] CHANGELOG.md updated with changes
- [ ] README.md component counts verified
- [ ] README.md tables updated (if adding/removing/renaming)
- [ ] plugin.json description updated (if component counts changed)

```

## Processual Enforcement Through Code Review

Unlike repositories that rely on automated CI gates to block unversioned changes, the compound-engineering-plugin enforces plugin versioning requirements through **processual discipline** and **manual verification**.

During code review, reviewers inspect the solution document checklist to ensure all three files have been updated. The CLI's reliance on the `version` field in [`plugin.json`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/plugin.json) for downstream generation creates a natural incentive to keep the version current—stale versions cause mismatched output for OpenCode, Codex, and Gemini integrations, which reviewers catch during testing.

This approach prioritizes documentation accuracy and semantic meaning over rigid automation, ensuring that every version number corresponds to a documented, reviewed set of changes.

## Summary

- **Plugin versioning requirements** in the EveryInc/compound-engineering-plugin repository are enforced through a documented workflow defined in [`docs/solutions/plugin-versioning-requirements.md`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/docs/solutions/plugin-versioning-requirements.md).
- Three files must be updated for every change: [`.claude-plugin/plugin.json`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/.claude-plugin/plugin.json) (semver version), [`CHANGELOG.md`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/CHANGELOG.md) (change history), and [`README.md`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/README.md) (component inventory).
- A mandatory markdown checklist ensures contributors verify version bumps, changelog entries, and documentation synchronization before committing.
- Enforcement relies on **processual discipline** and code review rather than automated CI gates, with the CLI's downstream generation dependencies acting as a natural validation mechanism.

## Frequently Asked Questions

### What happens if I forget to bump the version in [`plugin.json`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/plugin.json)?

If you forget to increment the `version` field in [`.claude-plugin/plugin.json`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/.claude-plugin/plugin.json), the CLI will generate downstream artifacts for OpenCode, Codex, and Gemini with a stale version number. Reviewers typically catch this during code review when they verify the solution document checklist, and mismatched output during testing serves as a natural signal to correct the omission.

### Does the repository use CI/CD automation to block unversioned changes?

No, the repository does not implement automated CI gates that abort builds if the version is not bumped. Instead, plugin versioning requirements are enforced through **processual enforcement**—a mandatory checklist in [`docs/solutions/plugin-versioning-requirements.md`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/docs/solutions/plugin-versioning-requirements.md) that reviewers verify during code review. This manual verification ensures documentation accuracy without rigid automation.

### What format should [`CHANGELOG.md`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/CHANGELOG.md) entries follow?

Entries must follow the **Keep a Changelog** format, using categories like `### Added`, `### Changed`, `### Deprecated`, `### Removed`, `### Fixed`, and `### Security`. New entries are placed under `## [Unreleased]` or under a new version header (e.g., `## [1.3.0] - 2026-02-15`). This format is mandated by the plugin versioning requirements checklist.

### How do component counts in [`README.md`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/README.md) affect plugin functionality?

While the component counts in [`README.md`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/README.md) do not directly alter runtime behavior, they serve as the **canonical documentation** for the plugin's agents, commands, and skills. The CLI and downstream generators for OpenCode, Codex, and Gemini rely on accurate documentation to correctly interpret the plugin's capabilities. Stale counts create confusion during integration and violate the plugin versioning requirements that mandate documentation synchronization.