pilotswarm-release

name	pilotswarm-release
description	Prepare and cut a PilotSwarm release. Use when validating release readiness, updating release-facing docs and templates, checking npm packaging, and handling commit/push/tag/publish flow.

PilotSwarm Release

Use this skill when a user wants to prepare or cut a release of PilotSwarm.

Keep the workflow tight and deterministic. The goal is to verify what will ship, fix release blockers, and only then commit, push, tag, and publish.

Mandatory Main-Branch Release Invariant

Every full release must land as exactly one new squash commit on main relative to the pre-release origin/main tip. The annotated release tag and GitHub Release must target that pushed main commit.

• A commit or tag on a feature/release-prep branch is not a completed release.
• Pushing the source branch does not satisfy the main-branch requirement.
• Never publish the GitHub Release before origin/main points at the squash commit.
• Do not rewrite an already-published tag to repair this after the fact. Prevent the mismatch before publication.
• Preparation-only requests may stop before the squash commit, but a user request to cut/publish a full release includes the squash-to-main step when commit/push/tag permission is explicit.

Treat this as a pilotswarm-repo maintainer workflow only. Do not update downstream consumers, sample app forks outside this repo, or vendored PilotSwarm copies in other repositories unless the user explicitly asks for that separate follow-up.

Release Workflow

1. Inspect the release surface.

   • Run git status --short.
   • Check changed runtime, docs, templates, examples, and workflow files.
   • Check the latest existing git tag with git tag --sort=-version:refname | head.
   • Check current package names and versions in packages/sdk/package.json, packages/horizon-store/package.json, and packages/app/package.json.
   • Report the current latest tag and the proposed next tag to the user before any tag is created.
   • Check whether each published workspace package has its own README.md.
   • Record the pre-release origin/main commit. Determine whether the current work is already on main or must be squashed from a source branch.

2. Verify feature-completeness around the change.

   • If behavior changed, confirm the canonical docs in docs/ were updated.
   • Confirm the DevOps sample in examples/devops-command-center/ still reflects the shipped behavior.
   • Confirm relevant builder templates in templates/builder-agents/ were updated when builder-facing behavior changed.
   • Confirm .github/copilot-instructions.md was updated if contributor workflow or maintenance expectations changed.
   • Update CHANGELOG.md with a new top entry for the proposed version, dated, summarizing what shipped (SDK / Portal / TUI / Tests / Maintainer Workflow / npm sections as appropriate). The CHANGELOG entry is a release blocker, not optional.
   • Update the repo-root README.md banner line that calls out the latest version (e.g. **v0.1.X** — ...) so the repo landing page matches the version about to ship.

3. Run build and full test suite.

   • Start with npm run build.
   • Run the full local integration test suite before any release:

     ./scripts/run-tests.sh
     

     All suites must pass. Do not skip suites or accept partial runs for an official release.
   • If the full suite fails, identify the specific failing test files and rerun those failing tests sequentially a few times, for example:

     ./scripts/run-tests.sh --sequential <suite-name>
     

     or run the specific file directly with npx vitest run <path-to-test>.
   • If the previously failing tests pass repeatedly in sequential mode, treat the failure as a parallel-run flake in the test harness and continue with the release. Call this out explicitly in the release notes.
   • If a test fails, investigate and fix the root cause. Do not silence failures or weaken assertions to proceed.
   • If package contents matter, run:

   npm pack --dry-run
   

   from `packages/sdk`, `packages/horizon-store`, and `packages/app`.
   

4. Validate npm-release wiring.

   • Check .github/workflows/publish-npm.yml.
   • Check .github/workflows/publish-starter-docker.yml if the starter appliance or Docker release path changed.
   • Confirm publish targets, access level, provenance flags, and required secrets still match the intended release.
   • Confirm each published package has correct repository, homepage, and bugs metadata for npm provenance verification.
   • Confirm built-in PilotSwarm plugins that must ship with the SDK are included by package files config.
   • Confirm package-local README.md files are actually present in npm pack --dry-run output for each workspace package.
   • If package names, publish workflow wiring, Docker publish wiring, or npm metadata changed, run the relevant CI workflow in dry-run or manual mode from main before tagging a real release when practical.

5. Prepare release notes for the user.

   • Summarize what changed.
   • List what was verified.
   • State the current latest git tag and the proposed next tag.
   • Ask whether the user wants the GitHub Release to trigger the starter Docker image publish as well.
   • Call out blockers or skipped checks explicitly.

6. Squash the release onto main and push only with explicit user approval.

   • Use non-interactive git commands.
   • Do not amend unless the user explicitly asks.
   • Preserve unrelated working-tree edits before switching branches and restore them afterward.
   • If the release was prepared on a feature/release branch:
     1. make the release-ready source tree coherent, including all intended tracked and untracked files;
     2. fetch origin/main and verify there is no unexpected remote-main drift;
     3. switch to local main at origin/main;
     4. run git merge --squash <source-branch>;
     5. verify the staged tree is byte-identical to the reviewed release-ready source tree;
     6. create one release commit on main.
   • If release preparation happened directly on main, ensure all release changes become one commit relative to the recorded pre-release origin/main tip. Do not leave multiple release-prep commits on main.
   • Prefer a commit message that describes the release-ready outcome, not just one file.
   • Push main, then verify git rev-parse main equals git ls-remote origin refs/heads/main.

7. Tag and publish only with explicit user approval.

   • Confirm the current commit is the pushed origin/main tip.
   • Create the annotated release tag from that exact main commit, then push the tag.
   • Verify local main, remote origin/main, and git rev-parse <tag>^{} are the same SHA.
   • Create a GitHub Release from the tag using gh release create. The npm publish workflow (publish-npm.yml) triggers on release: [published], not on tag push alone. Without a GitHub Release, the publish will not run.
   • If the user opted in, note that the same GitHub Release should also trigger .github/workflows/publish-starter-docker.yml.
   • If the user does not want the Docker starter published as part of the release, call that out explicitly and use the manual starter Docker workflow later if needed.
   • Include a concise release notes summary in the GitHub Release body.
   • If a manual workflow dispatch is used instead, report the exact inputs used.

8. Verify publication.

   • Check that the GitHub Actions publish workflow started and completed using gh run list --workflow=publish-npm.yml.
   • Report the published package names and versions.
   • Verify the registry directly with npm view <package> version.
   • If the release included the starter Docker image, also verify the published image tags directly with:

     docker buildx imagetools inspect docker.io/<user>/pilotswarm-starter:<tag>
     

     Confirm at least the release tag, bare version tag, and latest resolve successfully.
   • If publish failed, surface the workflow error rather than guessing.

Release Checklist

• build passes
• full test suite passes (./scripts/run-tests.sh) or any failing suites pass repeatedly when rerun sequentially
• sample app still reflects shipped behavior
• relevant docs and guides are updated
• relevant builder templates are updated
• CHANGELOG.md has a new top entry for the proposed version
• repo-root README.md banner line names the proposed version
• package metadata is correct
• npm pack --dry-run looks right
• package-local README.md files are present for published workspaces
• provenance metadata (repository, homepage, bugs) is correct
• latest tag and proposed next tag were reported
• release delta is exactly one squash commit on main
• pushed origin/main is the squash commit
• dereferenced release tag equals the pushed origin/main commit
• Docker starter publish intent was confirmed with the user
• release Docker tags were verified directly when applicable
• squash commit on main, main push, and tag push are complete
• publish workflow ran successfully

Current Package Surface

PilotSwarm publishes exactly three packages (in dependency/publish order):

1. pilotswarm-sdk — SDK runtime. Self-contained: the isomorphic Web API wire client ships inside it as the browser-safe subpath export pilotswarm-sdk/api (no separate api-client package exists).
2. pilotswarm-horizon-store — optional HorizonDB enhanced facts + graph providers (peer-depends on sdk).
3. pilotswarm — the application package (packages/app): terminal UI, portal server + Web API, and MCP server in one install. Bins: pilotswarm, pilotswarm-cli (alias), pilotswarm-web, pilotswarm-mcp. The former ui-core/ui-react/host layers ship inside it as subpath exports (pilotswarm/ui-core, pilotswarm/ui-react, pilotswarm/host, pilotswarm/web); there are no bundledDependencies and no prepack sync hacks.

Retired npm names (do NOT publish new versions): pilotswarm-cli, pilotswarm-web, pilotswarm-api-client, pilotswarm-mcp-server. The first two have old versions on the registry — deprecation notices pointing at pilotswarm are the correct follow-up, not new releases.

If package names change later, update this skill in the same change.

Notes

• Prefer fixing brittle tests over loosening product behavior just to get green.
• If a test failure is caused by stale hardcoded assumptions such as old model names, update the test to follow the current repo contract.
• npm package pages for workspace publishes come from the workspace-local README.md, not the repo-root README.
• When provenance is enabled for npm publish, mismatched or missing repository metadata is a release blocker, not a cosmetic issue.
• Treat the release agent as a maintainer workflow for this repository, not as an app-builder template.