docs: add release checklist to .cursorrules, CONTRIBUTING.md, CLAUDE.md, and ROADMAP.md

Ensures every version bump has a consistent process: implementation, version sync across 8 files, docs/GH Pages updates, test re-run, tag, release, and repo description update.

Made-with: Cursor

Author: TMHSDigital

.cursorrules

@@ -18,6 +18,30 @@
 - Use `execDocker()` from `utils/docker-api.ts` for all Docker CLI calls.
 - Always check for Docker availability before executing commands.
 
+## Release checklist
+Before finalizing any version bump, complete every item in order:
+1. Implement all MCP tools, skills, and rules listed for the milestone in ROADMAP.md.
+2. Add input validation tests for every new MCP tool in `input-validation.test.ts`.
+3. Build the MCP server (`npm run build`) and confirm zero compiler errors.
+4. Run all tests: `cd mcp-server && npm test` (Vitest) and `pytest tests/ -v --tb=short` (structure).
+5. Bump version in ALL of these files (must be consistent):
+   - `.cursor-plugin/plugin.json` (version + description tool count)
+   - `mcp-server/package.json` (version + description)
+   - `mcp-server/src/index.ts` (McpServer version string)
+   - `README.md` (version badge, tool count in tagline, tools table)
+   - `CLAUDE.md` (version, tool count, tool table, CLI quick reference)
+   - `ROADMAP.md` (mark new version as current, previous as Released, update Completed list)
+6. Add a new section to `CHANGELOG.md` with all Added/Changed/Fixed items.
+7. Update `docs/index.html` (GitHub Pages site):
+   - Meta description and og:description tool counts
+   - Hero version pill
+   - Stats counter data-target for MCP Tools
+   - Tools table (add new tool rows)
+   - Roadmap timeline (mark current, add/shift planned items)
+8. Re-run all tests after doc changes (some tests validate docs consistency).
+9. Commit, push, tag (`vX.Y.Z`), and `gh release create` with release notes.
+10. Update repo description: `gh repo edit --description "..."` with new tool count.
+
 ## Docker conventions
 - Default to Alpine or slim base images when suggesting Dockerfiles.
 - Always suggest multi-stage builds for production images.

CLAUDE.md

@@ -132,6 +132,25 @@ pip install -r requirements-test.txt
 pytest tests/ -v --tb=short
 ```
 
+## Release Checklist
+
+When bumping a version, update ALL of these (they must stay in sync):
+
+| File | What to update |
+|------|---------------|
+| `.cursor-plugin/plugin.json` | `version`, tool count in `description` |
+| `mcp-server/package.json` | `version`, `description` |
+| `mcp-server/src/index.ts` | `version` in `McpServer` constructor |
+| `README.md` | Version badge, tagline tool count, tools table |
+| `CLAUDE.md` | Version, tool count, tool tables, CLI quick reference |
+| `CHANGELOG.md` | New version section with Added/Changed/Fixed |
+| `ROADMAP.md` | Mark new version `(current)`, previous `Released`, update Completed |
+| `docs/index.html` | Meta tags, hero pill, stats counter, tools table, roadmap timeline |
+
+After all updates: re-run tests (some validate doc consistency), commit, tag, push, create GitHub release, update repo description.
+
+Full checklist with copy-paste commands: [CONTRIBUTING.md - Release Checklist](CONTRIBUTING.md#release-checklist)
+
 ## Key Conventions
 
 - **No em dashes.** Use regular dashes (-) or rewrite the sentence.

CONTRIBUTING.md

@@ -229,6 +229,50 @@ export function register(server: McpServer): void {
 3. Fill out the PR template completely
 4. One approval required for merge
 
+## Release Checklist
+
+When cutting a new version, complete every step in order before merging to `main`:
+
+### 1. Implementation
+
+- [ ] All MCP tools, skills, and rules listed for the milestone in `ROADMAP.md` are implemented
+- [ ] Input validation tests added for every new MCP tool (`input-validation.test.ts`)
+- [ ] MCP server builds cleanly (`cd mcp-server && npm run build`)
+- [ ] All Vitest tests pass (`cd mcp-server && npm test`)
+- [ ] All pytest structure tests pass (`pytest tests/ -v --tb=short`)
+
+### 2. Version bump (must be consistent across all files)
+
+- [ ] `.cursor-plugin/plugin.json` - `version` field and tool count in `description`
+- [ ] `mcp-server/package.json` - `version` field and `description`
+- [ ] `mcp-server/src/index.ts` - `version` in `McpServer` constructor
+- [ ] `README.md` - version badge, tool count in tagline, tools table rows
+- [ ] `CLAUDE.md` - version, tool count, tool tables, CLI quick reference table
+- [ ] `ROADMAP.md` - mark new version `(current)`, previous version `Released`, update Completed list
+
+### 3. Documentation
+
+- [ ] `CHANGELOG.md` - new version section with all Added/Changed/Fixed items and comparison link
+- [ ] `docs/index.html` (GitHub Pages):
+  - Meta description and `og:description` tool counts
+  - Hero version pill
+  - Stats counter `data-target` for MCP Tools
+  - Tools table (add rows for new tools)
+  - Roadmap timeline (shift current marker, update planned items)
+
+### 4. Final validation
+
+- [ ] Re-run all tests after doc changes (some tests check docs consistency)
+- [ ] Verify `docs/index.html` renders correctly in a browser
+
+### 5. Ship
+
+- [ ] Commit and push to `main`
+- [ ] Create annotated tag: `git tag vX.Y.Z`
+- [ ] Push tag: `git push origin vX.Y.Z`
+- [ ] Create GitHub release: `gh release create vX.Y.Z --title "vX.Y.Z - Theme" --notes "..."`
+- [ ] Update repo description: `gh repo edit --description "...new tool count..."`
+
 ## Style Guidelines
 
 - **No em dashes.** Use regular dashes (-) or rewrite the sentence.

ROADMAP.md

@@ -230,6 +230,19 @@ All destructive MCP tools (`rm`, `rmi`, `prune`, `kill`, `down`) will:
 
 ---
 
+## Release Process
+
+Every release follows the checklist in [CONTRIBUTING.md](CONTRIBUTING.md#release-checklist). The short version:
+
+1. Implement all tools/skills/rules for the milestone
+2. Add tests, build, verify all tests pass
+3. Bump version consistently across `plugin.json`, `package.json`, `index.ts`, `README.md`, `CLAUDE.md`, and this file
+4. Update `CHANGELOG.md` and `docs/index.html` (GitHub Pages)
+5. Re-run tests (some validate doc consistency)
+6. Commit, tag, push, create GitHub release, update repo description
+
+---
+
 ## Contributing
 
 Have an idea for a new skill, rule, or MCP tool? Check the [Contributing Guide](CONTRIBUTING.md) and open an issue or pull request.