// Safeword semver commitment and release discipline. Use when bumping versions, cutting releases, deciding what goes in a patch vs minor vs major, or reviewing changelog entries. Also use when auto-upgrade logic needs to know what's safe to apply silently.
| name | versioning |
| description | Safeword semver commitment and release discipline. Use when bumping versions, cutting releases, deciding what goes in a patch vs minor vs major, or reviewing changelog entries. Also use when auto-upgrade logic needs to know what's safe to apply silently. |
| allowed-tools | * |
| audience | maintainer |
Safeword follows strict semver. This contract enables auto-upgrade to trust patch AND minor bumps within the same major. Major bumps are the only class that requires user action.
Auto-applied silently at SessionStart, same as patch. The contract: minors are strictly additive. They may add capability but must not remove or change existing behavior. If a change can't fit this constraint, bump major instead.
The only class that breaks auto-upgrade silence. User runs
bunx safeword@<version> upgrade manually after reviewing the changelog.
"If a project auto-upgrades to this version at SessionStart, will anything break?"
No, only fixes -> patch. No, but adds new capability -> minor (still auto). Possibly -> major (notify only).
Safeword is pre-1.0 but follows strict semver anyway. The ecosystem convention (Renovate, Dependabot) treats 0.x as inherently unstable — Renovate excludes 0.x from auto-merge by default. Our patch + minor auto-upgrade policy is a deliberate commitment backed by this skill, not an ecosystem default. Contributors are held to a higher standard than the ecosystem expects for 0.x packages: minor releases must be strictly additive and pass the "auto-upgrade at SessionStart — does anything break?" test in the negative.
The publish path is CI-driven via OIDC trusted publishing. Tag push → GitHub Actions Release workflow → npm with provenance. No local bun publish needed (or wanted) for normal releases.
Procedure:
Decide the bump using rules above. Patch / Minor / Major.
Bump version in both files (pre-commit hook enforces they match):
packages/cli/package.json → versionmarketplace.json → plugins[0].versionPR + admin-merge. main is protected:
git checkout -b release/vX.Y.Z
git add packages/cli/package.json marketplace.json
git commit -m "chore(release): vX.Y.Z"
git push -u origin release/vX.Y.Z
gh pr create --title "chore(release): vX.Y.Z" --body "..."
# after CI green:
gh pr merge --delete-branch --admin < num > --squash
Annotated tag on the merge commit. Body should roll up changes since the prior tag — see git show v0.35.1 for the style.
git checkout main && git pull --ff-only origin main
git tag -a vX.Y.Z HEAD -m "Release vX.Y.Z
<rollup of changes since prior tag>"
git push origin vX.Y.Z
Tag push triggers .github/workflows/release.yml.
Verify the publish. Watch the run, then confirm on npm:
gh run view conclusion -q '.conclusion' < id > --json # → success
npm view safeword version # → X.Y.Z
Optional: bunx safeword@latest upgrade in this repo to round-trip the dogfood install.
Named failure modes (match symptoms, then fix):
.github/workflows/release.yml. Move the tag forward to a commit that has it (git tag -d vX.Y.Z && git tag -a vX.Y.Z origin/main ... && git push --delete origin vX.Y.Z && git push origin vX.Y.Z).404 Not Found - PUT /safeword at npm publish step — trusted-publisher config on https://www.npmjs.com/package/safeword/access doesn't match the OIDC claims. Verify Organization/Repository/Workflow filename/Environment name fields exactly match release.yml.422 Unprocessable Entity ... repository.url is "" — packages/cli/package.json lost its repository field. Restore it.node-version higher in release.yml.404 OIDC token exchange ... package not found — npm trusted publisher entry was deleted or never saved. Re-create on npmjs.com.Failure-mode triage: the workflow's release.yml has inline comments at each non-obvious step; read those before guessing. The publish-job step list (post-#146) is intentionally minimal — failures are localized.
Deep code review with web research. Use when double-checking code against latest docs, verifying dependency versions, or reviewing security concerns. Complements automatic quality hook with ecosystem verification.
Run comprehensive code audit for architecture, dead code, and test quality. Use when reviewing overall codebase health, checking for architectural violations, or before marking a feature complete.
Behavior-first feature development — use when building new capabilities, continuing feature work, or when work introduces new state or multiple user flows. Discovers desired behavior through examples and scenarios before implementation. Do NOT use for bug fixes, typos, or small isolated changes.
Root cause debugging before fixes. Use when investigating bugs, diagnosing test failures, troubleshooting unexpected behavior, or when previous fix attempts failed. Enforces investigate-first discipline.
Explore and debate options with fresh documentation and research before committing. Use when facing a real decision with multiple plausible approaches — library/framework choice, architecture call, API or schema design, algorithm selection, or any communication / strategy call where being wrong has cost. Enumerates relevant research domains, looks up current docs and evidence-based methods, weighs options on correctness and elegance, resists bloat. Do NOT use for divergent ideation (brainstorm), extracting user intent (elicit), or reviewing already-written code (quality-review).
Use when completing a TDD step and wanting a quality check. Reviews test quality after RED, implementation correctness after GREEN, and scenario completeness after REFACTOR.