release-coherence

name	release-coherence
description	Unified release coherence workflow for any component (CLI, GHA, or SDK). Use when bumping a version, preparing a release, or verifying that all documentation surfaces are updated after a version change. Orchestrates changelog, ROADMAP, website, and docs updates. Delegates to doc-maintenance, sdk-release-checklist, and doc-sync skills as needed.

Release Coherence

Ensures all documentation surfaces stay aligned when releasing a new version of any component: CLI, GitHub Action, or SDK (any runtime).

When to Use

• Bumping a version of CLI, GHA, or any SDK
• After merging a feature/fix that warrants a changelog entry
• Before tagging a release to verify nothing was missed
• When asked to "prepare the release" for a component

Components & Their Artifacts

Component	Version Source	Changelog	Web Surfaces
CLI	package.json (root)	docs/changelogs/cli.md	DocsContent (CLI section), README
GHA	package.json (root)	docs/changelogs/gha.md	DocsContent (GHA section), github-action/README.md
SDK .NET	src/sdks/dotnet/Envilder.csproj	docs/changelogs/sdk-dotnet.md	DocsContent, Sdks.astro, badge
SDK Python	src/sdks/python/pyproject.toml	docs/changelogs/sdk-python.md	DocsContent, Sdks.astro, badge
SDK Node.js	src/sdks/nodejs/package.json	docs/changelogs/sdk-nodejs.md	DocsContent, Sdks.astro, badge
SDK Go	src/sdks/go/ (tag)	docs/changelogs/sdk-go.md	DocsContent, Sdks.astro, badge
SDK Java	src/sdks/java/ (TBD)	docs/changelogs/sdk-java.md	DocsContent, Sdks.astro, badge

Workflow

Step 1: Bump Version

Update the canonical version source file for the component.

Step 2: Changelog Entry

Add entry to docs/changelogs/{component}.md following doc-maintenance skill format (categories: Added/Changed/Fixed/Documentation/Dependencies/Security).

Step 3: ROADMAP Update (if applicable)

Check ROADMAP.md for related items:

• Move completed features to appropriate status
• Update version references if roadmap tracks versions
• Skip if the release has no roadmap-tracked features

Step 4: Website Updates

For SDKs (delegate to sdk-release-checklist if new SDK)

• Version badge auto-updates via astro.config.mjs (verify build picks it up)
• Update DocsContent.astro if API changed (new methods, flags, options)
• Update Sdks.astro card if install command changed
• Update i18n keys if new strings added (types.ts + en.ts, ca.ts, es.ts)
• Changelog page sidebar already wired (no action for existing SDKs)

For CLI

• Update DocsContent.astro CLI section if new flags/options added
• Update docs/pull-command.md or docs/push-command.md if behavior changed
• Update root README.md if install or quick-start changed

For GHA

• Update DocsContent.astro GHA section if inputs changed
• Update github-action/action.yml description/inputs
• Update github-action/README.md and docs/github-action.md

Step 5: Cross-Reference Check

• Root README.md reflects current capabilities
• Examples in examples/sdk/{runtime}/ match current API
• SDK README (src/sdks/{runtime}/README.md) matches current API

Step 6: Validate

# Build website: verifies versions resolve and pages render
cd src/website && pnpm build

# Run doc-sync skill for comprehensive drift detection
# (or manually verify key surfaces)

Delegate to doc-sync skill for full cross-surface audit if uncertain.

Quick Reference: Minimum Actions Per Component

CLI / GHA release (no API change)

1. Bump version in package.json
2. Add changelog entry
3. Done (website picks up version dynamically)

CLI / GHA release (with new flag/input)

1. Bump version in package.json
2. Add changelog entry
3. Update docs (command reference, DocsContent)
4. Update README
5. Run doc-sync

SDK release (no API change)

1. Bump version in source file
2. Add changelog entry
3. Done (badge auto-updates via website build)

SDK release (with new API)

1. Bump version in source file
2. Add changelog entry
3. Update SDK README
4. Update examples
5. Update DocsContent.astro section
6. Update i18n if new strings
7. Run doc-sync

Delegation Map

Need	Delegate to
How to write a changelog entry	doc-maintenance skill
Full SDK wiring (new SDK, not version bump)	sdk-release-checklist skill
Drift detection across all surfaces	doc-sync skill
Website i18n workflow	website-i18n skill
Website styling/components	website-design-system skill

Anti-Patterns

Anti-pattern	Correct approach
Hardcoding version in website HTML	Use __SDK_*_VERSION__ or __CLI_VERSION__ globals
Updating changelog but not docs	Always check if behavior/API changed → update docs
Updating website but not SDK README	Both must match: SDK README is source of truth for API
Skipping i18n for "minor" text changes	All 3 locales must stay in sync: TypeScript catches missing keys
Forgetting ROADMAP after completing a tracked feature	Check ROADMAP on every release