This repository versions its distributed packages with
Changesets. A changeset is a small
Markdown file in this directory that names the packages a pull request
changes, the bump each one needs, and a user-facing summary. changeset version folds pending changesets into CHANGELOG.md and package.json
versions. pkg.pr.new publishes commit-addressed previews of the result.
| Package | Path | Status |
|---|---|---|
agent-bundle |
packages/agent-bundle |
publishable |
@agent-bundle/runtime |
packages/rsc-runtime |
publishable |
rsc-markdown-stream |
packages/rsc-markdown-stream |
publishable |
create-agent-bundle |
packages/create-agent-bundle |
publishable |
agent-bundle-workbench |
packages/workbench |
private, ignored |
@agent-bundle-example/*, @agent-bundle/rsc-agent-runtime-demo |
examples/* |
private, ignored |
@agent-bundle/docs |
website |
private, ignored |
Private packages are listed under ignore in config.json and are also
excluded by privatePackages.version: false, so pnpm changeset never
prompts for them and a changeset must never name them. The workspace root
(agent-bundle-workspace) is not a workspace package and needs no entry. A
change that only touches private packages, docs/**, agent-patterns/**,
CI, or a publishable package's tests/** directory needs no changeset
(changedFilePatterns in config.json exempts tests/**).
- One changeset per pull request that changes a publishable package's
shipped surface (
src/**,bin/**,templates/**,package.json,README.md, build config). Name every affected package in that one file. Split a PR instead of writing several changesets for it; the rare exception is a PR that intentionally ships two independent user-facing changes. - Semver before 1.0:
minor= breaking change (removed or renamed exports, CLI flags, config keys, diagnostic codes, on-disk formats, or changed defaults that require consumer action);patch= everything else, including new features. Do not usemajoruntil the first1.0.0; after 1.0 the usual semver meanings apply. - Summary style: user-facing, imperative, one paragraph. Lead with what
changes for the consumer, name the affected command, export, or config key,
and mention diagnostic codes (
AB+ four digits, seedocs/diagnostics.md) when a diagnostic is added, removed, or reworded. Do not describe the implementation, the review thread, or internal refactors that leave behavior unchanged. End with the pull request reference in parentheses,(#123), when the PR number is known. - Never edit
CHANGELOG.mdor a publishablepackage.jsonversionby hand. The "Version Packages" pull request is machine-owned; it is regenerated on every push tomainand any manual edit is overwritten. skip-changesetlabel: a PR that changes publishable files but ships no observable change (comments, formatting, type-only refactors) may carry theskip-changesetlabel instead of a changeset. TheChangeset presentcheck honours the label; reviewers should challenge its use.
Run pnpm changeset and follow the prompts, or create
.changeset/<slug>.md by hand:
---
"agent-bundle": patch
"create-agent-bundle": patch
---
`agent-bundle doctor` now reports `AB6026` when a Cursor hook manifest points
at a missing built script instead of failing silently; scaffolded projects
pick up the same check. (#123)Use a descriptive kebab-case slug (the generated random names are fine too). Commit the file with the change it describes.
.github/workflows/changeset.yml runs pnpm changeset status --since=origin/main on every pull request. It fails when a publishable
package changed (per changedFilePatterns) and the PR adds no
.changeset/*.md. It is skipped for the skip-changeset label and for the
machine-owned changeset-release/main branch of this repository (not for a
fork or contributor branch of the same name). Docs-only PRs pass automatically
because they change no publishable package.
agent-bundleand@agent-bundle/runtimeversion independently (fixedandlinkedare empty).agent-bundledeclares@agent-bundle/runtimeas an optional peer with range>=0.0.0 <1: the lower bound is the first runtime version that ships every subpath the generated code imports (mount,notices,notices/inbox-route,state,state/sqlite,flight/server,lineage), so a changeset that adds a runtime subpath the compiler emits must also raise that bound; the upper bound keeps a future1.xruntime from satisfying a0.xcompiler.@agent-bundle/runtimedoes not depend onagent-bundle, so neither package needs to move when the other does. Preview tarballs pin the peer to the same commit (docs/preview-packages.md), which is a preview concern, not a version-coupling one. Revisit if the peer range ever becomes exact.create-agent-bundleversions independently, but its optionalworkspace:*peers onagent-bundleand@agent-bundle/runtimeare the release pairing record.pnpm packrewrites them to the two exact published versions; the installed scaffolder reads that record instead of assuming the packages share a version.updateInternalDependencies: "patch"withbumpVersionsWithWorkspaceProtocolOnly: true: onlyworkspace:ranges between publishable packages trigger dependent patch bumps. The runtime'srsc-markdown-stream: workspace:^edge republishes it with the renderer's new caret. The scaffolder's two optionalworkspace:*peers patch-bump and republish it whenever either member of its exact release pair moves.accessstays"restricted"at the repository level. It is harmless while Changesets only versions packages and pkg.pr.new is the distribution channel; no npm publish command consumes it.
-
PRs merge to
mainwith their changesets. -
.github/workflows/release.ymlrunschangesets/actionon every push tomain. While changesets are pending it pusheschangeset-release/mainand opens or refreshes the Version Packages pull request, which deletes the consumed changesets, bumps versions, and writesCHANGELOG.mdentries. Review it, never edit it. GitHub does not start workflows for events created with the built-inGITHUB_TOKEN, so for that PR to get PR CI the repository needs aCHANGESETS_GITHUB_TOKENsecret (fine-grained PAT or GitHub App installation token withcontents: writeandpull-requests: writeon this repository). When the workflow falls back toGITHUB_TOKEN, it explicitly dispatchesci.yml(per-PR gates, includingpnpm check:release:ci) andrelease-candidate.yml(the packed-release boundary,pnpm check:release) on the generatedchangeset-release/mainbranch after confirming the Version Packages PR exists, so no close/reopen is needed. Each dispatched run posts its verdict as a commit status on the candidate head (CI (Version Packages candidate),Release candidate (Version Packages candidate)), so the PR page andgh pr checksshow the gate; do not merge a candidate whose statuses are missing or red. When aCHANGESETS_GITHUB_TOKENis configured, that token's push tochangeset-release/mainstartsrelease-candidate.ymldirectly. -
Merging Version Packages pushes a
Version Packagescommit tomainwith no pending changesets. TheRelease packagesworkflow first calls the reusablePackage previewworkflow, which runspnpm preview:publishand verifies that all four package URLs resolve for the merge SHA. The release job depends on that proof and runspnpm check:release; a green Version Packages run therefore means both the packed gates and the exact commit-addressed previews passed. -
Consumers pin the resulting artifacts as
https://pkg.pr.new/ScriptedAlchemy/agent-bundle/<package>@<sha>. No npm registry credential is needed or expected.