version-bump-cx

name	version-bump-cx
description	Bump version, auto-generate CHANGELOG from git commits, update all versioned files, and refresh root + docs/ documentation to reflect the current project state

Version Bump Workflow

Automatically bump the project version, generate CHANGELOG entries from git history since the last tag, update every file that references the version, and refresh project documentation to reflect the current state.

Codex Execution Notes

• Treat // turbo / // turbo-all as instructions to use multi_tool_use.parallel for independent reads, checks, and GitHub calls.
• Any user-approval phase is a hard stop: present the report/status in the final response and wait before committing, pushing, tagging, publishing, or deploying.

VERSION RULE: Always use PATCH bumps (3.x.y → 3.x.y+1) NEVER use npm version minor or npm version major. Always use: npm version patch --no-git-tag-version The threshold rule: when y reaches 10, bump to 3.(x+1).0 — e.g. 3.4.10 → 3.5.0.

---

Phase 1: Determine Version

1. Read current version and last tag

// turbo

cd /home/diegosouzapw/dev/proxys/OmniRoute
CURRENT_VERSION=$(node -p "require('./package.json').version")
LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
CURRENT_BRANCH=$(git branch --show-current)
echo "Current version: $CURRENT_VERSION"
echo "Last tag: $LAST_TAG"
echo "Current branch: $CURRENT_BRANCH"

2. Calculate new version

Apply the patch bump rule:

• If the current patch number is 9, the new version is 3.(minor+1).0
• Otherwise, increment patch: 3.x.y → 3.x.(y+1)

If the version was ALREADY bumped (e.g. you are on a release branch and package.json already has the new version), skip the npm version bump and use the existing version.

3. Bump package.json (if needed)

// turbo

# Only if version hasn't been bumped yet
npm version patch --no-git-tag-version

Or for threshold (y=10):

# Manual threshold bump
VERSION="3.X.0"  # compute manually
npm version "$VERSION" --no-git-tag-version

---

Phase 2: Generate CHANGELOG from Git History

4. Collect commits since last tag

// turbo

cd /home/diegosouzapw/dev/proxys/OmniRoute
LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null)
echo "=== Commits since $LAST_TAG ==="
git log "$LAST_TAG"..HEAD --pretty=format:"%h %s" --no-merges | head -100
echo ""
echo "=== Merge commits ==="
git log "$LAST_TAG"..HEAD --merges --pretty=format:"%h %s" | head -50

5. Classify commits and generate CHANGELOG section

Analyze each commit message and classify into categories based on the conventional-commit prefix and content:

Category	Patterns
✨ New Features	feat:, feat(*):
🐛 Bug Fixes	fix:, fix(*):
⚠️ Breaking Changes	BREAKING CHANGE, !: suffix
🛠️ Maintenance	chore:, refactor:, perf:, build:
🧪 Tests	test:, tests:
📝 Documentation	docs:
🔒 Security	security:, CVE references, vulnerability fixes
🌍 i18n	translation updates, locale changes

For each category with entries, create a markdown section with descriptive bullet points. Use the commit messages but rewrite them to be human-readable and descriptive (not raw commit messages).

If a commit references a PR number (e.g. #880, PR #885), include it in the description.

6. Update CHANGELOG.md

Replace the ## [Unreleased] section content with the generated entries, then add the new versioned section:

## [Unreleased]

---

## [NEW_VERSION] — YYYY-MM-DD

### ✨ New Features

- **Feature name:** Description (#PR)

### 🐛 Bug Fixes

- **Fix name:** Description (#PR)

### 🛠️ Maintenance

- **Item:** Description

---

## [PREVIOUS_VERSION] — YYYY-MM-DD

...

The date must be today's date in YYYY-MM-DD format.

---

Phase 3: Sync Version Across All Files

7. Update workspace package.json files and openapi.yaml

// turbo

cd /home/diegosouzapw/dev/proxys/OmniRoute
VERSION=$(node -p "require('./package.json').version")

# Update docs/reference/openapi.yaml version
sed -i "s/  version: .*/  version: $VERSION/" docs/reference/openapi.yaml
echo "✓ docs/reference/openapi.yaml → $VERSION"

# Update workspace packages (open-sse, electron)
for dir in electron open-sse; do
  if [ -d "$dir" ] && [ -f "$dir/package.json" ]; then
    (cd "$dir" && npm version "$VERSION" --no-git-tag-version --allow-same-version > /dev/null)
    echo "✓ $dir/package.json → $VERSION"
  fi
done

echo "✓ All workspace packages synced to $VERSION"

8. Update llm.txt version references

// turbo

cd /home/diegosouzapw/dev/proxys/OmniRoute
VERSION=$(node -p "require('./package.json').version")
OLD_VERSION_PATTERN='[0-9]\+\.[0-9]\+\.[0-9]\+'

# Update "Current version:" line
sed -i "s/\*\*Current version:\*\* $OLD_VERSION_PATTERN/**Current version:** $VERSION/" llm.txt

# Update "Key Features (vX.Y.Z)" header
sed -i "s/## Key Features (v$OLD_VERSION_PATTERN)/## Key Features (v$VERSION)/" llm.txt

echo "✓ llm.txt → $VERSION"

9. Regenerate lock file

// turbo

cd /home/diegosouzapw/dev/proxys/OmniRoute
npm install
echo "✓ Lock file regenerated"

---

Phase 4: Update Root Documentation

Based on the CHANGELOG entries generated in Phase 2, review and update these root-level files if relevant changes warrant updates:

10. Review and update root documentation files

For each file below, read the current content and determine if the CHANGELOG entries require any updates. Only modify files where substantive changes have occurred:

File	When to update
README.md	New providers, major features, stats changes (test count, provider count), badges, installation instructions, feature table
AGENTS.md	Architecture changes, new modules, new commands, new providers, new services/handlers/executors
CONTRIBUTING.md	Dev workflow changes, new tooling, test infrastructure changes
SECURITY.md	Security fixes, new auth mechanisms, vulnerability disclosures
llm.txt	Provider count changes, new features, architecture changes

Update rules:

• README.md: Update provider count, test count, feature highlights table, badges if any numbers changed. If a new provider was added, add it to the provider table. If a major feature was added, add it to the features section.
• AGENTS.md: If new architecture components (handlers, executors, services, DB modules) were added, update the Architecture section. If new commands were added, update the Build/Test table.
• SECURITY.md: Add new vulnerability fixes or security improvements to the relevant section.
• llm.txt: Update provider count, feature list, version references.

11. Review and update docs/ files (excluding i18n/)

For each file in docs/ (excluding docs/i18n/), review if CHANGELOG changes affect it:

File	When to update
docs/reference/API_REFERENCE.md	New API endpoints, changed request/response formats
docs/architecture/ARCHITECTURE.md	New modules, new services, changed data flow
docs/architecture/CODEBASE_DOCUMENTATION.md	New files, architectural changes, module reorganization
docs/architecture/REPOSITORY_MAP.md	New folders / files / one-line descriptions
docs/reference/CLI-TOOLS.md	New CLI tool integrations, config format changes
docs/guides/USER_GUIDE.md	UX changes, new dashboard pages, settings changes
docs/reference/PROVIDER_REFERENCE.md	New providers (regenerate via scripts/gen-provider-reference.ts)
docs/frameworks/MCP-SERVER.md	New MCP tools, changed tool signatures, scope changes
docs/frameworks/A2A-SERVER.md	New A2A skills, protocol changes
docs/frameworks/AGENT_PROTOCOLS_GUIDE.md	New external agent protocols supported
docs/frameworks/CLOUD_AGENT.md	Cloud agent additions (codex-cloud, devin, jules) or API changes
docs/architecture/AUTHZ_GUIDE.md	New route classifications, policy changes
docs/security/GUARDRAILS.md	New guardrails registered, priority/order changes
docs/security/COMPLIANCE.md	Audit log / retention / no-log policy changes
docs/frameworks/SKILLS.md	Skill framework / registry / built-in skill changes
docs/frameworks/MEMORY.md	Memory pipeline / extraction / injection / Qdrant changes
docs/frameworks/EVALS.md	Evaluation framework changes, new evaluators
docs/frameworks/WEBHOOKS.md	New webhook events, payload schema changes

Only update files where the CHANGELOG entries directly affect the documented content. Do NOT update files just to bump a version number — only when the documented behavior, features, or architecture has actually changed.

---

Phase 5: Verify

12. Run lint check

// turbo

cd /home/diegosouzapw/dev/proxys/OmniRoute
npm run lint

13. Run tests

// turbo

cd /home/diegosouzapw/dev/proxys/OmniRoute
npm test

14. Verify version sync across all files

// turbo

cd /home/diegosouzapw/dev/proxys/OmniRoute
VERSION=$(node -p "require('./package.json').version")
echo "Expected version: $VERSION"
echo ""

echo "--- package.json ---"
grep '"version"' package.json | head -1

echo "--- open-sse/package.json ---"
grep '"version"' open-sse/package.json | head -1

echo "--- electron/package.json ---"
[ -f electron/package.json ] && grep '"version"' electron/package.json | head -1

echo "--- docs/reference/openapi.yaml ---"
grep "  version:" docs/reference/openapi.yaml | head -1

echo "--- llm.txt ---"
grep "Current version:" llm.txt

echo "--- CHANGELOG.md (first versioned entry) ---"
grep "^## \[" CHANGELOG.md | head -2

15. 🛑 STOP — Present Summary to User

STOP and present a summary to the user including:

• Old version → New version
• CHANGELOG entries generated
• Files modified
• Test results
• Any documentation updates made

Wait for the user to confirm before committing.

---

Phase 6: Commit (only after user approval)

16. Stage and commit

// turbo-all

cd /home/diegosouzapw/dev/proxys/OmniRoute
git add -A
VERSION=$(node -p "require('./package.json').version")
git commit -m "chore(release): bump to v$VERSION — changelog, docs, version sync"

---

Notes

• This workflow does NOT create tags, releases, or deploy. Use /generate-release for the full release cycle after this.
• This workflow does NOT update docs/i18n/ translations. Translation updates are handled manually or via release tooling — there is no /update-i18n workflow shipped in this repo.
• The CHANGELOG generation is based on git commits since the last tag. If there are no new commits, the workflow should inform the user and stop.
• Always verify the generated CHANGELOG entries make sense — raw commit messages may need rewriting for clarity.
• If the version was already bumped (e.g. you're on a release/vX.Y.Z branch), skip the npm version step and use the existing version.

Version Touchpoints Checklist

File	Field/Pattern
package.json	"version": "X.Y.Z"
open-sse/package.json	"version": "X.Y.Z"
electron/package.json	"version": "X.Y.Z"
docs/reference/openapi.yaml	version: X.Y.Z
llm.txt	**Current version:** X.Y.Z and ## Key Features (vX.Y.Z)
CHANGELOG.md	## [X.Y.Z] — YYYY-MM-DD