Zeroshot distribution contract¶
.github/workflows/release.yml is the only Zeroshot release workflow. An operator supplies an
X.Y.Z version with an exact commit on main; the workflow rejects versions before major 8.
Canonical identity¶
| Release item | Identity |
|---|---|
| Git tag and release | vX.Y.Z |
| Executables | zeroshot and restic (.exe on Windows) |
| Native archives | zeroshot-vX.Y.Z-<target>.tar.gz |
| Target manifest | distribution/zeroshot-targets.json |
| npm package | @the-open-engine-company/zeroshot |
| Run skill | npm skills/zeroshot/SKILL.md; release asset zeroshot-skill.md |
| Memory init skill | npm skills/zeroshot-memory-init/SKILL.md; release asset zeroshot-memory-init-skill.md |
| Graph design skill | npm skills/zeroshot-graph-design/SKILL.md; release asset zeroshot-graph-design-skill.md |
| Plan skill | npm skills/zeroshot-plan/SKILL.md; release asset zeroshot-plan-skill.md |
| Target image | ghcr.io/the-open-engine/zeroshot-target |
| Python wheel release | zeroshot-python-vX.Y.Z_1 |
| Python package | the-open-engine-zeroshot==X.Y.Z.post1 when PyPI publication is enabled |
| Minor documentation | vX.Y/ at its newest patch, including Python SDK revision 1 |
The workflow publishes no alternate tag prefix, package, image, executable alias, source-build fallback, or compatibility artifact.
The npm installer copies every managed skill to $HOME/.agents/skills/<skill-name> for Codex,
GitHub Copilot, and Pi, and to ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills/<skill-name> for Claude
Code. Each skill has one canonical source across hosts. These fixed user scopes are installed
unconditionally so agents added later need no Zeroshot reinstall.
Package updates and zeroshot update replace only an unchanged managed copy. An edited or
conflicting skill is preserved and fails installation visibly. npm 7 and newer provide no uninstall
lifecycle, so users remove unchanged managed copies from these documented paths when they uninstall
the package.
Older updaters install only the skills they know. If zeroshot-graph-design or zeroshot-plan is
missing after an executable upgrade, run zeroshot update again. The current updater installs or
refreshes every managed skill even when the executable version is already current.
Targets¶
The target manifest declares Linux x64/arm64 musl, macOS x64/arm64, and Windows x64, and the npm target table must match it exactly. The installer stops on any other host.
Every archive contains exactly the Zeroshot executable and its pinned Restic sidecar. npm, Python
wheels, self-update, and the target image install the pair together. SHA256SUMS covers each archive
and the exact zeroshot-skill.md, zeroshot-memory-init-skill.md, zeroshot-graph-design-skill.md,
and zeroshot-plan-skill.md copied from their canonical npm sources. The workflow also rejects a Linux Zeroshot release binary that has a dynamic interpreter.
Version staging¶
Checked-in manifests carry development versions that are not release identifiers. In the release
workspace, scripts/distribution.js stage-version updates zeroshot/Cargo.toml and Cargo.lock,
then check-version verifies their coupling before compilation. Release automation does not commit
those staged versions.
Publication order¶
| Step | Release action |
|---|---|
| 1 | Build and smoke all native archives. |
| 2 | Generate and verify SHA256SUMS. |
| 3 | Build and smoke docker/zeroshot-target/Dockerfile from the same commit. |
| 4 | Create or verify the canonical GitHub Release and its exact assets. |
| 5 | Publish the image version, source-commit, and eligible latest tags. |
| 6 | Pack, install, smoke, and publish @the-open-engine-company/zeroshot. |
| 7 | Build and publish Python SDK revision 1 as an immutable GitHub wheel release. |
| 8 | Publish that wheel set to PyPI; use publish_pypi: false only when trusted publishing is unavailable. |
| 9 | Publish into vX.Y/; update the legacy stable redirect for the newest release. |
The canonical release dispatches release-python.yml on main as a standalone workflow with
the exact release source, version, revision 1, and publish_pypi selection. It records the
returned run ID and waits for success before publishing documentation. This keeps PyPI OIDC in
its configured standalone publisher; reusable workflow publication is unsupported.
PUBLISHING.md contains the operator setup and recovery rules.