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

1. Load project constraints:
   • Read CLAUDE.md (project invariants and development workflow)

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:

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:

1. Validates: git repo, on master, clean tree, gh CLI available
2. Reads current version from packages/tools/package.json
3. Computes next version
4. Updates version in: both package.json files, organon.config.json, METHODOLOGY_VERSION constant
5. Updates CHANGELOG.md with new version header + date
6. Git commits as chore: release v{version}
7. Creates git tag v{version}
8. Pushes commit and tags
9. 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/testing then @organon-methodology/tools with 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

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