Releasing a package with an AI agent

[ocots]

You can now release CTBase, CTModels, CTSolvers, CTFlows, CTDirect, CTParser, CTLie and OptimalControl with an agent. Open Claude Code in the package and say "prepare a stable release" or "prepare a beta release". The agent checks main, proposes a version and a plan, asks you to confirm and to choose a mode, opens a tracking issue, and runs the release; the rules (REL1–REL7) are checked by scripts, not by the agent.

Two modes: supervised (you merge the release PR and give the go for the registration) and autonomous (the agent merges, only through a tool that checks what actually ran, and registers). For a first release, use supervised.

• How to do it: guides/release.md
• Why it is built this way, and its limits: design/release.md
• The procedure the agent follows: recipes/release.md

The first release made this way is CTBase v0.30.12 (autonomous); supervised has not been run end to end yet, so feedback is welcome here.

[jbcaillau]

nice @ocots ! how to ensure that the agent indeed follows the instructions in the three MD files above?

[ocots]

Good questions, thanks. Short answer: we can't force an agent to follow the recipe. The design relies on that being true: the dangerous steps are made impossible without the tools, and everything else is made visible.

How the agent finds the recipe

1. Each package has a CLAUDE.md containing only @AGENTS.md, so Claude Code loads AGENTS.md at the start of every session (checked in the 8 packages). Other harnesses read AGENTS.md directly.
2. AGENTS.md has a Recurring tasks section: when asked to prepare a release, follow recipes/release.md of ct-agents, with the gh api command to read it.
3. The recipe names the tool (release.jl, from a clone of CTActions next to the packages) and the other texts to read. The conventions follow the same pattern: AGENTS.md gives the pinned tag and the clone command.

Weak points, which we know:

• The only hook is that one sentence. If the agent doesn't connect "prepare a release" to it, it improvises.
• Unlike the conventions, the recipe is not pinned: it is read from main of ct-agents, and the tool from main of CTActions. ct-agents has no tags or changelog yet.
• It needs gh authenticated and the CTActions clone in the right place.

What is enforced by tools, whatever the agent does

• The release rules (REL1-REL7: version number, changelog, a diff limited to the release files, something to ship, a stable resolving from General alone) are checked by release.jl gate, locally and in CI on the PR.
• release.jl merge merges only a release/v... branch, only if the jobs the release needs actually ran and passed on the head commit, and only at that commit.
• release.jl register posts the registration comment once, and refuses if it isn't due.
• The tag and the GitHub release are made by a workflow.
• release.jl status recomputes the phase from GitHub and the registries, so a skipped or repeated step shows up as blocked on the next run.

What is visible, not enforced

• Each phase ends with a comment on the tracking issue, with the list of steps (done / stopped) and the command it ran. A skipped step is a missing comment.
• In supervised mode it stops at each checkpoint and waits for a human.

What is not enforced

• Nothing technically prevents an agent from running gh pr merge or posting the registration comment by hand. The rule is in the recipe; the only hard limit is the permissions of the token it uses.
• "Ask stable or beta, never guess" is an instruction to the agent.
• So far there is one run: CTBase v0.30.12, in autonomous mode. supervised has not been run end to end yet.

What we plan

• Version ct-agents like ct-conventions (SemVer tags, changelog) and pin it in each AGENTS.md, so a report can cite the recipe version it applied.
• A /release command in each package that loads the recipe explicitly.
• A release.jl audit command that checks the whole trail of a release from the facts, and scenario tests of the recipe on a sandbox package.
• A token for the agent without merge permission in supervised mode.

For a first release: use supervised and read the tracking issue as it goes. Feedback is welcome.

Docs: guides/release.md (how to), design/release.md (why, and the limits), recipes/release.md (the procedure), all in ct-agents.