From bd2a19dc95a0f76240dfa6af28059247d3167c94 Mon Sep 17 00:00:00 2001 From: Kieran Klaassen Date: Mon, 24 Nov 2025 12:00:10 -0800 Subject: [PATCH] docs: Add versioning requirements for plugin development MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add CLAUDE.md with versioning checklist and pre-commit requirements - Add docs/solutions/plugin-versioning-requirements.md with detailed workflow - Bump version to 2.0.1 - Update CHANGELOG with v2.0.1 entry 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../.claude-plugin/plugin.json | 2 +- plugins/compounding-engineering/CHANGELOG.md | 7 ++ plugins/compounding-engineering/CLAUDE.md | 47 +++++++++++ .../plugin-versioning-requirements.md | 77 +++++++++++++++++++ 4 files changed, 132 insertions(+), 1 deletion(-) create mode 100644 plugins/compounding-engineering/CLAUDE.md create mode 100644 plugins/compounding-engineering/docs/solutions/plugin-versioning-requirements.md diff --git a/plugins/compounding-engineering/.claude-plugin/plugin.json b/plugins/compounding-engineering/.claude-plugin/plugin.json index 9e8e492..b3776e8 100644 --- a/plugins/compounding-engineering/.claude-plugin/plugin.json +++ b/plugins/compounding-engineering/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "compounding-engineering", - "version": "2.0.0", + "version": "2.0.1", "description": "AI-powered development tools. 24 agents (organized by category: review, research, design, workflow, docs), 15 commands, 11 skills for code review, research, design, and workflow automation.", "author": { "name": "Kieran Klaassen", diff --git a/plugins/compounding-engineering/CHANGELOG.md b/plugins/compounding-engineering/CHANGELOG.md index e90ca87..2204b75 100644 --- a/plugins/compounding-engineering/CHANGELOG.md +++ b/plugins/compounding-engineering/CHANGELOG.md @@ -5,6 +5,13 @@ All notable changes to the compounding-engineering plugin will be documented in The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [2.0.1] - 2024-11-24 + +### Added + +- `CLAUDE.md` - Project instructions with versioning requirements and pre-commit checklist +- `docs/solutions/plugin-versioning-requirements.md` - Detailed workflow documentation for maintaining version, CHANGELOG, and README in sync + ## [2.0.0] - 2024-11-24 Major reorganization consolidating agents, commands, and skills from multiple sources into a single, well-organized plugin. diff --git a/plugins/compounding-engineering/CLAUDE.md b/plugins/compounding-engineering/CLAUDE.md new file mode 100644 index 0000000..f0a24c1 --- /dev/null +++ b/plugins/compounding-engineering/CLAUDE.md @@ -0,0 +1,47 @@ +# Compounding Engineering Plugin Development + +## Versioning Requirements + +**IMPORTANT**: Every change to this plugin MUST include updates to all three files: + +1. **`.claude-plugin/plugin.json`** - Bump version using semver +2. **`CHANGELOG.md`** - Document changes using Keep a Changelog format +3. **`README.md`** - Verify/update component counts and tables + +### Version Bumping Rules + +- **MAJOR** (1.0.0 → 2.0.0): Breaking changes, major reorganization +- **MINOR** (1.0.0 → 1.1.0): New agents, commands, or skills +- **PATCH** (1.0.0 → 1.0.1): Bug fixes, doc updates, minor improvements + +### Pre-Commit Checklist + +Before committing ANY changes: + +- [ ] Version bumped in `.claude-plugin/plugin.json` +- [ ] CHANGELOG.md updated with changes +- [ ] README.md component counts verified +- [ ] README.md tables accurate (agents, commands, skills) +- [ ] plugin.json description matches current counts + +### Directory Structure + +``` +agents/ +├── review/ # Code review agents +├── research/ # Research and analysis agents +├── design/ # Design and UI agents +├── workflow/ # Workflow automation agents +└── docs/ # Documentation agents + +commands/ +├── workflows/ # Core workflow commands (/workflows:*) +└── *.md # Utility commands + +skills/ +└── *.md # All skills at root level +``` + +## Documentation + +See `docs/solutions/plugin-versioning-requirements.md` for detailed versioning workflow. diff --git a/plugins/compounding-engineering/docs/solutions/plugin-versioning-requirements.md b/plugins/compounding-engineering/docs/solutions/plugin-versioning-requirements.md new file mode 100644 index 0000000..b1174b6 --- /dev/null +++ b/plugins/compounding-engineering/docs/solutions/plugin-versioning-requirements.md @@ -0,0 +1,77 @@ +--- +title: Plugin Versioning and Documentation Requirements +category: workflow +tags: [versioning, changelog, readme, plugin, documentation] +created: 2025-11-24 +severity: process +component: plugin-development +--- + +# Plugin Versioning and Documentation Requirements + +## Problem + +When making changes to the compounding-engineering plugin, documentation can get out of sync with the actual components (agents, commands, skills). This leads to confusion about what's included in each version and makes it difficult to track changes over time. + +## Solution + +**Every change to the plugin MUST include:** + +1. **Version bump in `plugin.json`** + - Follow semantic versioning (semver) + - MAJOR: Breaking changes or major reorganization + - MINOR: New agents, commands, or skills added + - PATCH: Bug fixes, documentation updates, minor improvements + +2. **CHANGELOG.md update** + - Add entry under `## [Unreleased]` or new version section + - Use Keep a Changelog format + - Categories: Added, Changed, Deprecated, Removed, Fixed, Security + +3. **README.md verification** + - Verify component counts match actual files + - Verify agent/command/skill tables are accurate + - Update descriptions if functionality changed + +## Checklist for Plugin Changes + +```markdown +Before committing changes to compounding-engineering plugin: + +- [ ] 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) +``` + +## File Locations + +- Version: `.claude-plugin/plugin.json` → `"version": "X.Y.Z"` +- Changelog: `CHANGELOG.md` +- Readme: `README.md` + +## Example Workflow + +When adding a new agent: + +1. Create the agent file in `agents/[category]/` +2. Bump version in `plugin.json` (minor version for new agent) +3. Add to CHANGELOG under `### Added` +4. Add row to README agent table +5. Update README component count +6. Update plugin.json description with new counts + +## Prevention + +This documentation serves as a reminder. When Claude Code works on this plugin, it should: + +1. Check this doc before committing changes +2. Follow the checklist above +3. Never commit partial updates (all three files must be updated together) + +## Related Files + +- `/Users/kieranklaassen/every-marketplace/plugins/compounding-engineering/.claude-plugin/plugin.json` +- `/Users/kieranklaassen/every-marketplace/plugins/compounding-engineering/CHANGELOG.md` +- `/Users/kieranklaassen/every-marketplace/plugins/compounding-engineering/README.md`