| 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)
For CLI
For GHA
Step 5: Cross-Reference Check
Step 6: Validate
cd src/website && pnpm build
Delegate to doc-sync skill for full cross-surface audit if uncertain.
Quick Reference: Minimum Actions Per Component
CLI / GHA release (no API change)
- Bump version in
package.json
- Add changelog entry
- Done (website picks up version dynamically)
CLI / GHA release (with new flag/input)
- Bump version in
package.json
- Add changelog entry
- Update docs (command reference, DocsContent)
- Update README
- Run
doc-sync
SDK release (no API change)
- Bump version in source file
- Add changelog entry
- Done (badge auto-updates via website build)
SDK release (with new API)
- Bump version in source file
- Add changelog entry
- Update SDK README
- Update examples
- Update DocsContent.astro section
- Update i18n if new strings
- 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 |
