ci: add lockstep Changesets release automation

.changeset/README.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets).
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md).

.changeset/config.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.4/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [["agentry-test", "@agentry/core", "@agentry/claude", "@agentry/codex", "@agentry/gemini", "@agentry/antigravity", "@agentry/mcp"]],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": [],
+  "privatePackages": { "version": false, "tag": false }
+}

.changeset/pre-release-cli-rename.md

@@ -0,0 +1,2 @@
+---
+---

.github/workflows/ci.yml

@@ -28,3 +28,37 @@ jobs:
       # Unit + replay tests only — no live agent calls, so CI needs no API key.
       - name: Test
         run: pnpm test
+
+      - name: Build
+        run: pnpm build
+
+  changeset:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install
+        run: pnpm install --frozen-lockfile
+
+      - name: Require a changeset for package changes
+        # Version PRs consume the changesets while bumping package versions.
+        # Match the author and source repository as well as the release branch.
+        if: >-
+          !(github.event.pull_request.user.login == 'github-actions[bot]' &&
+            github.event.pull_request.head.repo.full_name == github.repository &&
+            github.head_ref == format('changeset-release/{0}', github.base_ref))
+        env:
+          BASE_REF: ${{ github.base_ref }}
+        run: |
+          git fetch origin "$BASE_REF"
+          pnpm changeset status --since="origin/$BASE_REF"

.github/workflows/release.yml

@@ -0,0 +1,58 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+permissions:
+  contents: write
+  pull-requests: write
+  id-token: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install
+        run: pnpm install --frozen-lockfile
+
+      - name: Typecheck
+        run: pnpm typecheck
+
+      - name: Test
+        run: pnpm test
+
+      - name: Check publishing credentials
+        if: vars.NPM_PUBLISH_ENABLED == 'true'
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          if [ -z "$NPM_TOKEN" ]; then
+            echo "::error::NPM_PUBLISH_ENABLED requires the NPM_TOKEN repository secret. See docs/RELEASING.md."
+            exit 1
+          fi
+
+      - name: Create release PR or publish
+        id: changesets
+        uses: changesets/action@v1
+        with:
+          version: pnpm version-packages
+          # Leave publishing off until npm ownership and authentication are set up.
+          publish: ${{ vars.NPM_PUBLISH_ENABLED == 'true' && 'pnpm release' || '' }}
+          commit: "chore(release): version packages"
+          title: "chore(release): version packages"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NPM_CONFIG_PROVENANCE: "true"

README.md

@@ -47,7 +47,7 @@ All TypeScript is executed directly via `tsx` — no build step required for dev
 | `@agentry/gemini` | Gemini CLI driver (`gemini -p --output-format stream-json`) |
 | `@agentry/antigravity` | Antigravity driver (`agy -p --output-format stream-json`) |
 | `@agentry/mcp` | `MockMcpServer` (JSON-RPC + stdio shim) + MCP matchers |
-| `agentry` | CLI (`agentry test`, `record`, `init`, `doctor`) |
+| `agentry-test` | CLI (`agentry test`, `record`, `init`, `doctor`); installs the `agentry` command |
 
 ---
 
@@ -58,7 +58,7 @@ The `examples/basic` directory contains a working example with a committed trans
 ### 1. Config: `examples/basic/agentry.config.ts`
 
 ```ts
-import { defineConfig } from 'agentry';
+import { defineConfig } from 'agentry-test';
 
 export default defineConfig({
   testDir: './tests',
@@ -73,7 +73,7 @@ export default defineConfig({
 ### 2. Test: `examples/basic/tests/todo.agentry.ts`
 
 ```ts
-import { test } from 'agentry';
+import { test } from 'agentry-test';
 
 test.describe('todo', () => {
   test('reads the todo file via a tool', async ({ agent, workspace, expect }) => {
@@ -237,7 +237,7 @@ agentry/
 │   ├── gemini/        @agentry/gemini — Gemini CLI driver
 │   ├── antigravity/   @agentry/antigravity — Antigravity (agy) driver
 │   ├── mcp/           @agentry/mcp — MockMcpServer + MCP matchers
-│   └── cli/           agentry — CLI binary (test, record, init, doctor)
+│   └── cli/           agentry-test — CLI binary `agentry` (test, record, init, doctor)
 ├── examples/
 │   └── basic/       Working example with committed transcript
 └── docs/

docs/RELEASING.md

@@ -0,0 +1,107 @@
+# Releasing
+
+Agentry uses [Changesets](https://github.com/changesets/changesets). All seven
+publishable packages — `agentry-test`, `@agentry/core`, `@agentry/claude`,
+`@agentry/codex`, `@agentry/gemini`, `@agentry/antigravity`, and `@agentry/mcp` —
+version and publish together at one shared version. The `fixed` group in
+`.changeset/config.json` bumps all seven even when only one changed. Private
+example workspaces are excluded.
+
+## Day-to-day flow
+
+1. Add a changeset for changes that affect a published package:
+
+   ```bash
+   pnpm changeset
+   ```
+
+   Select any affected package and the largest bump the change warrants. The
+   summary becomes a changelog entry. Commit the generated `.changeset/*.md` file
+   alongside the code. Use `pnpm changeset --empty` for changes that intentionally
+   need no release, such as pre-release package metadata.
+
+   CI rejects package changes without a changeset. The version PR opened by
+   `github-actions[bot]` from this repository's `changeset-release/main` branch is
+   exempt from this check because versioning consumes its changesets. Typecheck,
+   tests, installation, and build still run for version PRs.
+
+2. Merge to `main`. The Release workflow opens or updates a version PR that bumps
+   package versions and writes changelogs. Empty changesets alone do not open a
+   version PR or publish packages.
+
+   The workflow uses `GITHUB_TOKEN`. GitHub may require a maintainer to select
+   **Approve workflows to run** on the generated PR before its CI runs. See
+   [GitHub's workflow trigger rules](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow#triggering-a-workflow-from-a-workflow).
+   Wait for CI to pass before merging the version PR.
+
+3. Once publishing is enabled, merge the version PR. The next Release run builds
+   and publishes all seven packages with npm provenance, then pushes tags and
+   creates GitHub releases.
+
+When there are no pending changesets, an enabled Release run attempts to publish
+any package versions missing from npm. This also lets a later run retry a partial
+publish. It is not limited to commits that merge version PRs.
+
+## Repository setup
+
+- In **Settings → Actions → General → Workflow permissions**, enable **Allow
+  GitHub Actions to create and approve pull requests**. The workflow declares its
+  required token permissions; the repository's default can remain read-only.
+- Publishing is **disabled by default**. Until the repository variable
+  `NPM_PUBLISH_ENABLED` equals `true`, the workflow can manage version PRs but does
+  not invoke the publish command. This permits merging the release infrastructure
+  before npm setup is complete.
+
+## Before enabling npm publishing
+
+1. Confirm ownership or availability of `agentry-test` and create or obtain access
+   to the `@agentry` npm scope. The CLI package is `agentry-test`; its installed
+   command remains `agentry` (`npm i -D agentry-test`, then `npx agentry-test …`).
+2. Add the **`NPM_TOKEN` repository secret** with publish rights for all seven
+   package names. Use an npm [granular access token](https://docs.npmjs.com/creating-and-viewing-access-tokens/)
+   with package/scope read-write permission and **Bypass two-factor
+   authentication** enabled. Ensure its permissions allow creating the initial
+   package names, and rotate it before expiry. Organization-management permission
+   alone does not grant permission to publish packages.
+3. Keep each published package's `repository.url` set to
+   `git+https://github.com/dortort/agentry.git` and `repository.directory` set to
+   its package directory. npm [requires matching repository metadata](https://docs.npmjs.com/generating-provenance-statements/#prerequisites)
+   for provenance.
+4. Build and inspect the packed CLI:
+
+   ```bash
+   pnpm build
+   pnpm --filter agentry-test pack --pack-destination /tmp/agentry-pack
+   ```
+
+   The packed CLI must reference
+   `dist/bin.js`, which must start with `#!/usr/bin/env node`; exports must point
+   to the built JavaScript and declarations.
+5. Set the **`NPM_PUBLISH_ENABLED` repository variable** to `true` once setup is
+   complete. If enabled without `NPM_TOKEN`, the workflow fails with an explicit
+   setup error. Setting the variable alone does not start a workflow; the next
+   push to `main` uses the new setting. Remove it or set it to `false` to disable
+   publishing again.
+
+No first release is included in this infrastructure PR; packages remain at
+`0.0.0`. Configure publishing before merging the first version PR.
+
+## First release (0.0.0 → 0.1.0)
+
+After completing npm setup, add the initial minor changeset on a feature branch:
+
+```bash
+pnpm changeset            # choose "minor" for any publishable package
+git add .changeset/*.md
+git commit -m "chore(release): initial 0.1.0 changeset"
+```
+
+Merge that changeset PR to `main`, wait for the generated version PR's CI, and
+merge the version PR. All seven packages will release at `0.1.0`.
+
+## Files
+
+- `.changeset/config.json` — lockstep configuration and public access.
+- `.github/workflows/release.yml` — version PR and publish automation.
+- `.github/workflows/ci.yml` — package checks, build, and changeset gate.
+- Root `package.json` — `changeset`, `version-packages`, and `release` scripts.

docs/ROADMAP.md

@@ -141,7 +141,7 @@ Actions first-class integration.
 ## 5. MVP success criteria (the 5-minute test)
 
 A developer can:
-1. `npm i -D agentry` and `npx agentry init` in <5 min.
+1. `npm i -D agentry-test` and `npx agentry-test init` in <5 min.
 2. Write a test that starts Claude Code, sends a prompt triggering an MCP tool, and asserts on the
    tool call + a side-effect.
 3. Run in **`replay`** in <2s and **`mcp-live`/`live`** in <120s.

docs/SPEC.md

@@ -625,7 +625,7 @@ but not its internal routing, so the upstream position is the primary one for ro
 ## 10. Test Authoring API (code-first TypeScript)
 
 ```ts
-import { test, expect } from 'agentry';
+import { test, expect } from 'agentry-test';
 
 test.describe('filesystem MCP server', () => {
   test('reads a file via the MCP tool', async ({ agent, workspace, mcp }) => {
@@ -671,7 +671,7 @@ combos.
 ## 11. Configuration (`agentry.config.ts`)
 
 ```ts
-import { defineConfig } from 'agentry';
+import { defineConfig } from 'agentry-test';
 
 export default defineConfig({
   testDir: './tests',

examples/basic/agentry.config.ts

@@ -1,4 +1,4 @@
-import { defineConfig } from 'agentry';
+import { defineConfig } from 'agentry-test';
 
 export default defineConfig({
   testDir: './tests',

examples/basic/package.json

@@ -5,6 +5,6 @@
   "type": "module",
   "description": "Agentry MVP example — drive Claude to read a file, assert on behavior, replay deterministically.",
   "dependencies": {
-    "agentry": "workspace:*"
+    "agentry-test": "workspace:*"
   }
 }

examples/basic/tests/todo.agentry.ts

@@ -1,4 +1,4 @@
-import { test } from 'agentry';
+import { test } from 'agentry-test';
 
 test.describe('todo', () => {
   test('reads the todo file via a tool', async ({ agent, workspace, expect }) => {

package.json

@@ -12,9 +12,13 @@
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
     "build": "pnpm -r build",
-    "agentry": "tsx packages/cli/src/bin.ts"
+    "agentry": "tsx packages/cli/src/bin.ts",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "pnpm -r build && changeset publish"
   },
   "devDependencies": {
+    "@changesets/cli": "^2.31.1",
     "@types/node": "^22.10.0",
     "tsup": "^8.3.5",
     "tsx": "^4.19.2",

packages/antigravity/package.json

@@ -4,6 +4,11 @@
   "type": "module",
   "description": "Agentry driver for Antigravity (agy) headless stream-json.",
   "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dortort/agentry.git",
+    "directory": "packages/antigravity"
+  },
   "exports": { ".": "./src/index.ts" },
   "publishConfig": {
     "exports": { ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" } }

packages/claude/package.json

@@ -4,6 +4,11 @@
   "type": "module",
   "description": "Agentry driver for Claude Code (headless stream-json).",
   "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dortort/agentry.git",
+    "directory": "packages/claude"
+  },
   "exports": { ".": "./src/index.ts" },
   "publishConfig": {
     "exports": { ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" } }

packages/cli/package.json

@@ -1,9 +1,14 @@
 {
-  "name": "agentry",
+  "name": "agentry-test",
   "version": "0.0.0",
   "type": "module",
   "description": "Agentry CLI — Playwright for AI Agents.",
   "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dortort/agentry.git",
+    "directory": "packages/cli"
+  },
   "bin": { "agentry": "./src/bin.ts" },
   "exports": { ".": "./src/index.ts" },
   "publishConfig": {

packages/cli/src/commands/init.ts

@@ -2,7 +2,7 @@ import { writeFile, mkdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 
-const CONFIG = `import { defineConfig } from 'agentry';
+const CONFIG = `import { defineConfig } from 'agentry-test';
 
 export default defineConfig({
   testDir: './tests',
@@ -12,7 +12,7 @@ export default defineConfig({
 });
 `;
 
-const EXAMPLE = `import { test, expect } from 'agentry';
+const EXAMPLE = `import { test, expect } from 'agentry-test';
 
 test.describe('demo', () => {
   test('agent reads a file from the sandbox', async ({ agent, workspace, expect }) => {

packages/cli/src/index.ts

@@ -1,3 +1,3 @@
 // agentry — user-facing API. Re-exports the core surface so tests can do
-// `import { test, expect, defineConfig } from 'agentry'`.
+// `import { test, expect, defineConfig } from 'agentry-test'`.
 export * from '@agentry/core';