Release Publish Workflow
Implements PROTO-ORG-11 from
organon/protocols/PROTOCOLS.md. End-to-end release workflow from QA to npm publication.
When to Use This Skill
Use this skill when:
- Shipping a new version — any planned release of the npm packages
- After completing a milestone — new features, bug fixes, or breaking changes ready for users
Purpose: Ensure every release goes through proper QA, has correct versioning, and is published via the automated pipeline.
Context Loading
- Load project constraints:
- Read
CLAUDE.md(project invariants and development workflow)
- Read
Note: The release process is mostly automated. Additional context is only needed for version bump decisions.
Steps
Step 1: Run Pre-Publish QA
Execute /pre-publish-qa first — this runs organon-verify, npm-test, and npm-build checks. All checks must pass before proceeding.
If any check fails, fix the issue and re-run QA. Do not skip this step.
Step 2: Determine Version Bump Type
Review changes since last release to determine the correct bump:
| Bump Type | When to Use | Example |
|---|---|---|
| patch | Bug fixes only, no new features | Fix a verification gate false positive |
| minor | New features, backward-compatible | Add new CLI command, new assertion |
| major | Breaking changes to CLI, API, or methodology | Rename a command, change config format |
Decision heuristic: When in doubt between patch and minor, choose minor. When in doubt between minor and major, check if existing organon.config.json files or CLI invocations would break.
Step 3: Run Release Script
Use the release-script (scripts/release.mjs) to bump versions and create the release:
node scripts/release.mjs <patch|minor|major>
The script performs these actions atomically:
- Validates: git repo, on
master, clean tree,ghCLI available - Reads current version from
packages/tools/package.json - Computes next version
- Updates version in: both
package.jsonfiles,organon.config.json,METHODOLOGY_VERSIONconstant - Updates
CHANGELOG.mdwith new version header + date - Git commits as
chore: release v{version} - Creates git tag
v{version} - Pushes commit and tags
- Creates GitHub Release with auto-generated notes
Step 4: Verify GitHub Release
Use gh-cli to confirm the release exists:
gh release view v{version}
Check that the title, tag, and notes are correct.
Step 5: Monitor CI Publish
The .github/workflows/release.yml workflow triggers automatically when a GitHub Release is published.
gh run list --workflow=release.yml --limit 1
Monitor until the workflow completes successfully. It will:
- Build and test both packages
- Verify version/tag alignment
- Publish
@organon-methodology/testingthen@organon-methodology/toolswith provenance
Step 6: Verify npm Availability
After CI completes:
npm info @organon-methodology/tools version
npm info @organon-methodology/testing version
Both should report the new version.
Step 7: Update README (Major Versions Only)
For major version bumps, check if README.md install instructions need updating:
- Package name changes
- CLI command changes
- Configuration format changes
Version Bump Decision Heuristics
| Change Type | Bump | Example |
|---|---|---|
| Fix typo in CLI output | patch | Error message correction |
| Fix false positive in verification gate | patch | Gate was incorrectly failing |
| Add new CLI command | minor | organon discover |
| Add new verification gate | minor | New imports gate |
Add new assertion to @organon-methodology/testing |
minor | assertPattern() |
| New protocol or skill | minor | PROTO-ORG-12 |
| Rename existing CLI command | major | organon validate → organon check |
Change organon.config.json schema |
major | Rename a config key |
| Remove a verification gate | major | Drop coverage gate |
| Change methodology version format | major | Semver → calver |
Verification
- Pre-publish QA passed completely (PROTO-ORG-10)
- Version bump type is appropriate for the changes
- Release script completed without errors
- GitHub Release exists with correct tag and notes
- GitHub Actions publish workflow succeeded (green check)
- Both packages available on npm at new version
- README is current (for major version bumps)
Error Recovery
| Failure | Recovery Action |
|---|---|
| Release script fails: "not clean" | Commit or stash pending changes, then retry. |
| Release script fails: "not on master" | Switch to master: git checkout master. |
| Release script fails: "gh not found" | Install GitHub CLI: brew install gh or winget install GitHub.cli. |
| GitHub Actions publish fails: 401 | NPM_TOKEN secret is expired. Regenerate at npmjs.com and update GitHub secret. |
| GitHub Actions publish fails: 403 | Package version may already exist. Check npm for partial publish. |
| Version mismatch in CI | Release script has a bug. Fix the script, delete the tag/release, and re-run. |
| npm shows old version after publish | npm CDN may cache. Wait 5 minutes and retry npm info. |
Converted and distributed by TomeVault — claim your Tome and manage your conversions.