zeroshot: Instructions file for Codex

UPDATE THIS FILE when making architectural changes, adding patterns, or changing conventions.

Zeroshot v8

Operational guidance for automated agents working on this repository. Install the canonical command with npm i -g @the-open-engine-company/zeroshot or build zeroshot with Cargo.

Critical rules

• Never run zeroshot run unless the user explicitly asks to start a run.
• Never use git commands inside validator prompts; validators inspect files and observable outputs.
• Agents are non-interactive. Make autonomous, scoped decisions rather than asking runtime questions.
• Never edit CLAUDE.md unless the user explicitly requests it.
• main is the only development and release trunk. Normal PRs target main.
• Pull request titles are Conventional Commit headers because squash merge makes the title the released commit.
• Pull request descriptions keep a nonempty ## Summary with the user-facing change. Release notes come from that summary in the immutable squash commit, not from mutable GitHub metadata.
• Worker git operations are allowed only inside an isolated worktree/container or explicit PR/ship delivery flow.
• Do not recreate the retired Node.js product, its commands, configuration, state, release workflow, package exports, compatibility aliases, migration, or dual publication identities.

Product and release identity

• The Rust crate in zeroshot/ is the canonical product and owns the zeroshot CLI.
• Node.js is used for repository tooling, the npm binary delivery package, and building the static profile UI. The UI is served by Rust and never needs a production Node server.
• Canonical releases are explicit vX.Y.Z tags with major version 8 or newer.
• The npm package is @the-open-engine-company/zeroshot.
• That package owns the canonical zeroshot, zeroshot-memory-init, zeroshot-graph-design, and zeroshot-plan skills and installs managed copies for Codex, GitHub Copilot, Pi, and Claude Code at their user scopes. Do not fork skills by host. ZEROSHOT_SKIP_SKILLS=1 opts out of all user-scope skill handling in npm postinstall and zeroshot update; only the exact value 1 enables it. Executables still install/update, existing skills stay untouched, and updates skip skill downloads. Keep default managed-copy protections when the opt-out is unset.
• The target image is ghcr.io/the-open-engine/zeroshot-target.
• The Python distribution is the-open-engine-zeroshot; its import package remains zeroshot.
• Python SDK tags are zeroshot-python-vZEROSHOT_SDK and package versions are ZEROSHOT.postSDK. Canonical releases publish SDK revision 1; later SDK revisions may release independently from an exact main commit descended from the canonical tag.
• Canonical releases always publish revision 1 wheels to an immutable GitHub Release. publish_pypi defaults to true; operators may set it to false only when PyPI trusted publishing is known to be unavailable, then recover the same revision from the same source later.
• Checked-in Cargo/npm versions are development placeholders. Tags, registry metadata, and GitHub Releases are authoritative. Never commit a staged release version to main.
• zeroshot update resolves the newest canonical GitHub Release, verifies the declared host archive and canonical skill assets through that release's SHA256SUMS, smoke-checks the staged executable, and replaces the running executable in place without privilege escalation. It installs or refreshes only unchanged managed skill copies and preserves conflicts. Development-placeholder builds refuse self-update.
• Release recovery may complete missing outputs only when existing immutable artifacts match the exact version and source commit.