vercel-labs--zerolang/AGENTS.md

Contributor Notes

Zero is a pre-1 experiment in building an agent-first programming language. Keep public-facing changes honest about what works today without weakening that positioning.

Project Direction

Zero is still being shaped around the needs of agents. Breaking changes are acceptable when they move the language, standard library, compiler, or tooling closer to that goal.

Do not preserve legacy behavior by default. Prefer the clearer agent-facing design over compatibility shims, migration layers, or carrying old paths forward. Keep examples, docs, tests, and command contracts aligned with the new behavior so the repository describes one coherent current system.

This does not mean broad churn for its own sake. Make direct changes that advance Zero's agent-first goals: on-the-fly learnability, deterministic inspection and repair, strong standard-library coverage, exceptional developer experience, and regular patterns over syntactic convenience.

Safety Expectations

Security vulnerabilities should be expected. Zero is not ready for production systems, sensitive data, or trusted infrastructure.

Run and develop Zero in safe environments: isolated workspaces, disposable inputs, and systems where compiler crashes, malformed output, or unsafe runtime behavior cannot damage production state. Treat generated artifacts and examples as experimental unless they have been reviewed for the specific environment where they will run.

Development

• Build the local compiler with make -C native/zero-c.
• Use bin/zero for focused checks; it execs the local native compiler at .zero/bin/zero.
• Keep examples runnable and docs copyable.
• Prefer small, direct changes over broad refactors.
• Use direct emitters for compiler output.
• For broad local validation, run pnpm run agent:checks. It mirrors the CI buckets in parallel, including conformance, command contracts, native test shards, sanitizer smoke, and workspace checks. It uses isolated /tmp workspaces so agents can validate uncommitted changes without local artifact races.
• Before ending any agent turn that changes the repository, run pnpm run conformance unless pnpm run agent:checks already passed for the same changes. If validation cannot complete, report the blocker and the failing command.

Useful Checks

pnpm run agent:checks
pnpm run docs:build
pnpm run conformance
pnpm run native:test
pnpm run command-contracts

pnpm run agent:checks already includes conformance. Do not run conformance again after it passes unless you need to recheck later changes.

Shard native tests locally with ZERO_NATIVE_TEST_SHARD=1/4 pnpm run native:test:local. PR CI runs representative native runtime cases in two fast shards. Scheduled and manual deep CI runs the full native runtime matrix in six shards, plus full conformance and full graph performance fixtures.

pnpm run conformance:local and pnpm run command-contracts:local use the aggregate validation runner. Add -- --shard 1/4 to run one conformance phase shard, -- --phases name,name to match a focused CI phase set, -- --list to see phases, and -- --fail-fast only when a narrow loop should stop at the first failing phase. Use ZERO_NATIVE_TEST_SCOPE=fast only when reproducing PR CI coverage. Leave it unset for the exhaustive native runtime matrix. pnpm run conformance runs the sandbox suite with four isolated conformance check workers. Local validation stays serial by default; set ZERO_CONFORMANCE_CHECK_JOBS=<n> only when measuring that path on the current machine. Validation scripts prefer the built native compiler at .zero/bin/zero after native-build; set ZERO_BIN=<path> only when comparing another compiler binary deliberately.

For focused compiler work:

bin/zero check --json <graph-input>
bin/zero inspect --json <graph-input>
bin/zero size --json <graph-input>
bin/zero explain <diagnostic-code>
bin/zero fix --plan --json <graph-backed-file-or-package>

Project Layout

• native/zero-c/: native compiler implementation.
• examples/: small runnable programs and packages.
• conformance/: language and CLI fixtures.
• docs/: public documentation site.
• scripts/: validation and release support tooling.

Public Docs Policy

Docs should describe current user-facing behavior, not internal development history. Avoid release-planning language, validation-report narratives, and implementation diary details in pages intended for external readers.

Releasing

Releases are manual, single-branch affairs. The maintainer controls the changelog voice and format.

To prepare a release:

1. Create a release branch, such as ctate/v0.1.1.
2. Bump the release version in package.json, docs/package.json, extensions/vscode/package.json, and native/zero-c/src/main.c.
3. Update command-contract expectations that assert the compiler version.
4. Write the CHANGELOG.md entry for the new version, wrapped in <!-- release:start --> and <!-- release:end --> markers.
5. Remove the release markers from the previous release entry. Only the latest release entry should have markers.
6. Include a ### Contributors section in the marked changelog entry. Derive contributors from commit authors and Co-authored-by trailers since the previous tag.
7. Run focused checks before opening or updating the PR:

make -C native/zero-c
bin/zero --version --json
pnpm run test:zero
pnpm run command-contracts:local
pnpm run docs:build

The release workflow reads the version from package.json, builds release assets, and uses the content between the changelog markers as the GitHub release body.