zeroshot AGENTS.md

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

Zeroshot: Multi-Agent Coordination Engine

Operational rules and references for automated agents working on this repo. Install: npm i -g @the-open-engine/zeroshot or npm link (dev).

CRITICAL RULES

• Never spawn without permission. Do not run zeroshot run <id> unless the user explicitly asks to run it.
• Never use git in validator prompts. Validate files directly.
• Never ask questions. Agents run non-interactively; make autonomous decisions.
• Never edit CLAUDE.md unless explicitly asked to update docs.
• Detached (-d) runs must forward all zeroshot run options via ZEROSHOT_RUN_OPTIONS (see buildDaemonEnv + buildStartOptions) so PR/worktree config cannot be dropped.
• main is the single development and release trunk. Target normal PRs at main; never recreate a long-lived dev -> main release-promotion flow.
• Pull request titles are Conventional Commit headers because squash merge makes the title the released commit. For Node-owned changes, fix:/perf: publish patches, feat: publishes minors, breaking syntax publishes majors, and docs:/chore: intentionally publish nothing.
• Node, Zeroshot Rust, and the Python SDK release independently from main. Node owns vX.Y.Z and automatic semantic releases. Rust uses explicit zeroshot-rust-vX.Y.Z releases. Python uses zeroshot-python-vRUST_SDK tags and PEP 440 RUST.postSDK package versions; Rust releases automatically publish SDK revision 1, while later SDK revisions remain separately triggerable. Its PyPI distribution is zeroshot-rust, while its import package remains zeroshot. Rust and Python releases must never affect the next Node version or generated Node notes.
• Checked-in publication manifests are non-authoritative development versions. Release tags, npm metadata, and GitHub Releases are authoritative; automation must never commit versions to main.
• Curated notes live at docs/releases/vX.Y.Z.md. Recovery may operate only from an immutable vX.Y.Z tag whose exact commit is an ancestor of main, and it must never overwrite an existing npm version or GitHub Release.
• Provider output-silence liveness checks are opt-in (enableLivenessCheck: true). Recovery tests that exercise stale-agent termination must enable the watchdog explicitly.
• Isolation copies must reuse the shared pinned-root boundary in src/copy-containment.ts for traversal, directory creation, synchronous copies, and worker copies. Revalidate the source and destination immediately before every filesystem effect; never reconstruct unchecked effect paths.