Docs / Releasing AOS 1.0

Releasing AOS 1.0

This is the maintainer runbook for cutting a 1.0 release from main. One tag ships two things: the aos-harness CLI on npm, published by .github/workflows/release.yml, and the Claude Code plugin, which users install straight from this repository through .claude-plugin/marketplace.json. The workflow refuses to publish unless the tag, the branch, the worktree, and every versioned manifest agree, so most of this runbook is getting those to agree before you push the tag.

The npm latest tag stays on the 0.x line until 1.0.0 final. 0.11.x patches release from the release/0.11 branch, not from main; this runbook does not cover that line.

Before you start

You need push access to the repository (to push the tag), gh authenticated, Bun 1.3.11 or later, and Claude Code for the plugin checks. You do not need npm credentials to release, only to roll back.

The workflow publishes through npm trusted publishing: npm trades the job’s GitHub OIDC token for a short-lived credential, so there is no npm token to store, rotate, or let expire. It is set up once, on npmjs.com: the aos-harness package’s Settings > Trusted Publisher names GitHub Actions, organization aos-engineer, repository harness, workflow release.yml, and environment npm-publish. If any of those change (a renamed workflow file or environment, a moved repository), update the trusted publisher first, or the publish step fails with an authentication error.

1. Pick the version

Versionnpm dist-tagGitHub release
Prerelease, with a hyphen, such as 1.0.0-next.1nextmarked as a prerelease
Plain semver, such as 1.0.0latesta normal release

The workflow decides this from the tag alone: any tag containing - goes to next. That is what keeps latest from moving by accident while 1.0 is in prerelease.

2. Bump every versioned manifest

scripts/release/verify-tag.ts fails the release unless each of these files carries exactly the tag’s version. The list lives in scripts/release/versioned.ts, which bun run validate:configs also reads on every pull request, so drift between them fails review before it can fail a release:

  • package.json
  • cli/package.json
  • kernel/package.json
  • hosts/claude-code/package.json
  • hosts/claude-code/.claude-plugin/plugin.json
  • packs/feature-delivery/package.json

The version users see for the plugin comes from hosts/claude-code/.claude-plugin/plugin.json. Checking it against the npm package’s version is what keeps the CLI and the plugin from drifting apart.

Then always rebuild the plugin and commit the result. The bump alone changes the bundle, because the MCP server embeds kernel/package.json’s version, so skipping the rebuild fails build:plugin:check. The marketplace installs from git, so the committed bundles are what users get:

bun run build:plugin
git add hosts/claude-code/dist hosts/claude-code/pack

3. Add a CHANGELOG section

Add a section to CHANGELOG.md headed with the bare version, and move the entries collected under ## Unreleased into it:

## 1.0.0-next.1

### Fixed

- ...

The workflow builds the GitHub release notes from this section. It extracts every line after a heading that matches ^## <version>( |$) up to the next ## heading, so ## 1.0.0-next.1 and ## 1.0.0-next.1 (2026-10-20) both work, and ## v1.0.0-next.1 does not.

The release workflow extracts this section right after it verifies the tag, before anything is published, and fails if the section is missing or empty. bun run validate:configs, a required check on every pull request, fails the same way for the version the manifests carry, so a missing section is caught in review.

4. Run the checks locally

bun run lint
bun run test
bun run build:plugin:check
AOS_E2E_HOOK=bundle bun test ./tests/e2e
bun run validate:configs
claude plugin validate .
claude plugin validate ./hosts/claude-code

build:plugin:check exits 1 when the committed bundles or the plugin’s pack copy differ from a fresh build. The end-to-end run with AOS_E2E_HOOK=bundle sends every hook through the launcher and the committed bundle, which is what a marketplace install runs. validate:configs checks that the versioned manifests agree, that every pack (including the plugin’s copy) loads, that the marketplace entry points at the plugin, and that CHANGELOG.md has a non-empty section for the version. The two claude plugin validate calls check the marketplace manifest and the plugin manifest; warnings do not fail them, but read each one.

5. Merge to main through a pull request

main is protected: changes land only through a pull request, and direct pushes are blocked. Open a PR with the version bump, the rebuilt plugin, and the CHANGELOG section, wait for the two required checks, and merge it:

  • test: lint and typecheck, the test suite, the plugin bundle check, and the end-to-end run through the committed bundle.
  • validate-configs: bun run validate:configs.

6. Tag the merged commit

Tag the commit on main, not your branch. verify-tag requires the tag to point at HEAD, HEAD to be on origin/main, and the worktree to be clean.

git switch main
git pull --ff-only
git tag v1.0.0-next.1
git push origin v1.0.0-next.1

The tag must be v followed by the version, exactly as in the manifests.

7. What the workflow does

Pushing a v* tag runs .github/workflows/release.yml on Ubuntu in the npm-publish environment, with Bun 1.4.0 and Node 24. Its permissions are contents: write (to create the release) and id-token: write (for npm provenance). In order:

  1. Verify the tag, the branch, and every version. bun run scripts/release/verify-tag.ts reads the tag from GITHUB_REF_NAME and fails unless it is v<semver>, points at HEAD, HEAD is an ancestor of origin/main, the worktree is clean, and all six manifests carry the version.
  2. Extract the release notes from the version’s CHANGELOG.md section (runbook step 3), and fail if there are none. This runs before anything is published, because a published version number can never be reused.
  3. Install with bun install --frozen-lockfile.
  4. Lint and typecheck with bun run lint.
  5. Test with bun run test, which also starts the bundled MCP server through sh bin/aos.sh mcp over stdio.
  6. Check the plugin bundles with bun run build:plugin:check.
  7. Run the end-to-end suite through the shipped plugin with AOS_E2E_HOOK=bundle bun test ./tests/e2e: every hook goes through bin/aos.sh and the committed dist/ bundle.
  8. Validate the release configs with bun run validate:configs: versions, packs, the marketplace entry, and the CHANGELOG section.
  9. Pack the CLI. scripts/release/pack-cli.ts bundles the CLI with the kernel and its dependencies into dist/aos.js, copies the reference pack to pack/, adds the CLI README and the license, and writes a manifest with no runtime dependencies.
  10. Smoke the packed CLI by running bun dist/aos.js --version from the packed directory.
  11. Choose the dist-tag: next if the tag contains a hyphen, otherwise latest.
  12. Install npm 11.21.1, pinned, because trusted publishing needs npm 11.5.1 or later.
  13. Publish with npm publish --access public --tag <dist-tag> --provenance, authenticated by trusted publishing.
  14. Wait for the registry. scripts/release/wait-for-npm.ts asks npm for aos-harness@<dist-tag> up to 30 times, 10 seconds apart, until it resolves to the new version. It then installs that exact version into a scratch directory and runs the installed dist/aos.js --version under Bun, so the release is proven installable from the registry, not only uploaded.
  15. Create the GitHub release with the notes extracted in step 2. If a release for the tag already exists it edits its notes; otherwise it creates one with --verify-tag. Prerelease versions are marked --prerelease.

The plugin needs no publish step. Once the tag is pushed, it is installable from the tag, and main already carries the same version.

8. Verify the release

npm

npm view aos-harness dist-tags
npm view aos-harness@next version

For a prerelease, next should name the new version and latest should still be the 0.x version. Then install it and run it:

npm install -g aos-harness@next     # or: bun add -g aos-harness@next
aos --version
aos doctor

The CLI is a Bun script, so Bun must be on PATH even when npm installed it.

The marketplace

Install the plugin at the tag you just pushed, preferably in a scratch Claude Code configuration so your own install is untouched:

claude plugin marketplace add aos-engineer/harness#v1.0.0-next.1
claude plugin install aos@aos-harness
claude plugin list

The #v1.0.0-next.1 suffix pins the marketplace to that git ref: a ref that exists is cloned at that ref, and one that does not fails at clone. If the aos-harness marketplace is already added, refresh it instead with claude plugin marketplace update aos-harness. claude plugin list should show the version from plugin.json. Then start Claude Code in a scratch git repository and run a short bounded run (/aos:run add a --shout flag to greet) through to its first approval, approving it with the CLI you just installed.

9. Recover from a partial failure

Look at which step failed before re-running anything.

  • Before npm publish: nothing reached npm. If the cause was outside the repository (a trusted-publisher setting on npmjs.com that does not match the repository, workflow, or environment; a registry outage), fix it and re-run the workflow for the same tag. If the fix needs a new commit, the tag no longer points at what you want to release, and the pushed tag may already be pinned by someone installing the plugin, so do not move it: bump to the next version and start again from step 2.
  • The registry wait or the install smoke failed (step 14): the package is on npm and may be broken. Do not finish the release by hand: go to step 10 and roll forward.
  • After npm publish and the install smoke succeeded, and only the GitHub release step failed: re-running the workflow fails at npm publish, because that version already exists. Create the release by hand. Write the notes to a file and run:
gh release create v1.0.0-next.1 --title v1.0.0-next.1 --prerelease --verify-tag --notes-file notes.md

Drop --prerelease for a plain semver release. To rebuild the notes the workflow would have used, run the awk command from the workflow’s “Extract the release notes” step against CHANGELOG.md at the tag.

10. Roll back a bad prerelease

Never move or delete a tag that has been published: npm provenance, the GitHub release, and anyone who pinned the plugin to the tag all point at it. Roll forward instead.

  1. Point next back at the last good 1.0 version, so new installs stop getting the bad one:

    npm dist-tag add aos-harness@1.0.0-next.0 next
    

    Before 1.0.0-next.0 is published, next points at an old 0.x release candidate (0.7.0-rc.2); publishing 1.0.0-next.0 moves it to 1.0. So if 1.0.0-next.0 itself is bad, there is no good 1.0 version to point at: skip this step, never point next back at the 0.x candidate, and deprecate 1.0.0-next.0 and ship 1.0.0-next.1 instead.

  2. Deprecate the bad version, so anyone who installs it sees why:

    npm deprecate aos-harness@1.0.0-next.1 "<what is wrong>; use 1.0.0-next.2"
    
  3. Ship a fixed prerelease (1.0.0-next.2) through this runbook from step 1.

Do not reach for npm unpublish. npm’s unpublish policy restricts when it is allowed, and a version number that has been published can never be used again, even after an unpublish. A deprecation plus a moved dist-tag gets users off a bad version without either cost.

For the plugin, the marketplace entry points at this repository, and a user who added it without a ref follows main. Revert the bad change on main through a PR (bumping the version as part of the fixed prerelease), and tell users to update with:

claude plugin update aos@aos-harness

Users who added the marketplace pinned to a tag (aos-engineer/harness#v1.0.0-next.1) stay on that tag until they add the marketplace again at a newer one. How quickly an unpinned install sees a change on main depends on Claude Code refreshing the marketplace; claude plugin marketplace update aos-harness forces a refresh.

View this page's source on GitHub