Publishing Ultimate Harness
Ultimate Harness publishes to the npm registry as @agenticengineeringagency/ultimate-harness and exposes the uh binary.
Install smoke
Section titled “Install smoke”bun add -g @agenticengineeringagency/ultimate-harnessuh --helpA release candidate installs from the next dist-tag instead, for example bun add -g @agenticengineeringagency/ultimate-harness@next or @0.11.0-rc.1.
Local preflight
Section titled “Local preflight”bun install --frozen-lockfilebun run typecheckbun run buildbun run testpython -m pip install -r apps/hermes-plugin/dashboard/requirements-dev.txtbun run plugin:typecheckbun run plugin:testbun run publish:dry-runbun run publish:dry-run wraps bun publish --dry-run --tag <dist-tag> (see Dist-tags and prereleases) so the package tarball contents and publish metadata are checked without writing to the registry. Bun 1.3.x still expects an npm token-shaped value for scoped-package dry-runs; CI supplies a dummy NPM_CONFIG_TOKEN for the dry-run job, while the real publish job uses the repository secret.
.github/workflows/publish.yml has two jobs:
| Job | Trigger | Behavior |
|---|---|---|
dry-run |
PRs to dev/main, pushes, releases, manual dispatch |
installs, builds, runs package metadata tests, then runs bun run publish:dry-run |
publish |
v* tag, GitHub release, or manual dispatch with publish=true |
rebuilds, resolves the dist-tag, and runs npm publish --access public --tag <dist-tag> after an idempotency check |
The publish job requires a repository secret named NPM_CONFIG_TOKEN. Bun respects this env var for automated registry auth.
.github/workflows/release-plugin.yml builds the Hermes plugin tarballs on a plugin-v* tag or a published GitHub release and attaches them to the release. It publishes nothing to npm.
Dist-tags and prereleases
Section titled “Dist-tags and prereleases”The npm dist-tag comes from the version in package.json, through scripts/npm-dist-tag.mjs:
| Version | Dist-tag | Example |
|---|---|---|
SemVer prerelease (has a - suffix) |
next |
0.11.0-rc.1 |
| Release | latest |
0.11.0 |
The publish job and bun run publish:dry-run both use it, so the dry-run prints the tag a real publish would use (Tag: next for a release candidate). A prerelease is never published to latest, so bun add -g @agenticengineeringagency/ultimate-harness keeps installing the last release.
On a GitHub release event, both workflows also compare the release’s pre-release flag with the version and fail before building or publishing when they disagree. That keeps a release candidate off latest on npm and keeps its plugin tarball off the stable releases/latest/download/hermes-plugin.tar.gz link, which GitHub resolves only to releases not marked as pre-releases.
To cut a release candidate:
- Set the same version, for example
0.11.0-rc.1, inpackage.json,apps/hermes-plugin/plugin.yaml,apps/hermes-plugin/dashboard/manifest.json,ACP_CLIENT_VERSIONinsrc/adapters/acp.tsandVERSIONinsrc/harness/otel-export.ts.tests/package-publish.test.tsfails while they differ. - Date the version’s
CHANGELOG.mdheading and run the local preflight above. Check that the dry-run ends withTag: nextand@<version> (dry-run). - After the release PR merges, push the tag
v<version>, or publish a GitHub release for it with Set as a pre-release checked. Either trigger publishes; a second run for the same version skips through the idempotency check. - Promote by publishing the final version (
0.11.0), which goes tolatest. Movinglatestby hand (npm dist-tag add) is not part of this flow.
GitHub secret
Section titled “GitHub secret”Create an npm automation token with publish rights for the @agenticengineeringagency scope, then set:
gh secret set NPM_CONFIG_TOKEN --repo Agentic-Engineering-Agency/ultimate-harnessDo not commit npm tokens into the repository. Do not publish from a local shell unless a maintainer explicitly asks for that release path.