Lesson 16.616.6 Shipping a version

In everyday life. A printed cookbook has an edition on its copyright page. The second printing fixes typos. A new edition adds chapters. A "completely revised" edition may drop a recipe you relied on. A note at the front says what changed, so a cook knows whether to buy the new one.

What you will learn. What a version number promises. What to check before you ship a version, which means release it. What a changed rule must move, how a change reaches each copy, and how anyone knows which version ran.

Why it matters. Once other people install your plugin, your changes reach them at different times, and some copies keep running the old one. They need to know what kind of change it is, and you need to know which copy ran.

What does a version number promise?

What kind of change it is. The Agent Plugins specification recommends Semantic Versioning: three numbers, major.minor.patch.

A changed business rule is never a patch, because the same invoice can now land in a different pile.

A version below 1.0.0 says "early, and may still change", and Semantic Versioning promises nothing there. Brightline's plugin starts at 0.1.0, and keeps to the same three meanings by choice.

Does the standard have a version too?

Yes. The $schema line pins the plugin to Agent Plugins 1.0.0. A later version of the specification will have a new schema address. A plugin moves to it only by changing that line, in a reviewed change.

What is a changelog?

A changelog is a file, CHANGELOG.md, with one entry per version, newest first: the date, and what was added, changed, fixed or removed. It is written for the people who install the plugin, not for the builders.

Why pin a dependency?

So nothing changes without you knowing. A dependency is something your work relies on that you did not write (Chapter 14). Brightline's connector is @modelcontextprotocol/server-filesystem@2.1.0. Without the @2.1.0, every install would fetch whatever version was newest that day, with whatever tools it had that day. Pin every dependency to an exact version, and change the pin in its own pull request, after reading what changed.

What should run before anyone shares it?

A required check. A plugin that breaks the standards loads in some products and is skipped or rejected in others. So the checks run as a required check on every pull request (Chapter 15). They check every skill against the Agent Skills rules, and plugin.json and mcp.json against the Agent Plugins schemas. They also check that every manifest has the same version, that the version moved when the plugin changed, and that the changelog has an entry for it. A plugin that fails cannot merge.

Where do people find a plugin?

In a catalog, which is where a product looks for plugins to install. It may be a catalog file in a repository, a curated directory, which means reviewers choose what it lists, or a package registry. Agent Plugins 1.0.0 defines no catalog format, so each product reads its own, and one repository may carry more than one catalog file. A catalog only lists where plugins are. A curated directory reviews what it lists, and a catalog file that anyone can publish is reviewed by no one.

Who gets it when it is installed?

An install scope says who gets the plugin when it is installed:

• You, in every project on this computer.
• This project, for everyone who works on it, through a settings file committed to the repository.
• Only you, in this project.
• Everyone in an organization, set by an administrator.

How does a change reach people?

As a new version, and each copy gets it in its own way. Some products fetch it when someone asks. Some sync it from the catalog. Some read the current files in a folder, so updating the folder is the update. Products that compare version numbers ignore a change pushed under the old number, so a change with no new version may never arrive. Each copy runs what it last received. A broken release is fixed with a new version, never by changing an old one in place.

What must move when a rule changes?

Every copy of the rule, in one reviewed change. A skill's file is written once, and every product that loads it reads that one file (16.7). A number like the limit is different. A skill also has to run in a chat with no repository, so the rule is kept in several files, on purpose:

• the rules sheet, and its copy in the skill's references/
• the engine, the tested code that does the sorting, and its Python version, because this repository keeps each tool in both languages
• the skill's own script
• the tests

So a changed rule is not in just one place. What makes it safe is one reviewed pull request that moves every copy. Its checks stay red until the copies agree, and a person's approval is recorded. One of those checks must compare the sheet with each copy in code. Without it, the sheet or one copy can change with every test still green. Chapter 8's warning still stands: a number in a skill's steps is a second copy nobody checks, so the steps name the script instead.

What does a copy that has not updated do?

It keeps running the old rule, with no error, and it cannot know that the rule changed. If the limit went down, an old copy calls an invoice ready when it now needs approval.

How would anyone know which version ran?

From the report, if the tool prints it there. Brightline's tested tool prints the plugin's version and the policy it was built from, and the report copies them onto its first line:

AP triage, run date 2027-03-08, batch invoices-intake.csv, brightline-ap 0.1.0, AP policy v3

Ana reads that line each Monday against the current policy. The report is filed with the batch, because a line in a chat is not a record. That answers the question Grace's insurance company asked in the overview. It stops no payment, which is why the third fix is where the money moves (Chapter 23).

How do I know it still works?

With repeatable test cases. The checks above prove the plugin is well formed, which means its files follow the rules. They do not prove that it works. For that, keep a small set of test cases: requests, the files they use, and what a good answer must contain. Run them before each release, more than once, because models vary. Some products can run such cases with and without the plugin and compare. Chapter 38 teaches evaluation in depth.

At work. The builder writes the changelog entry for version 0.1.0, adds the plugin check to the required checks, and tags the release. A teammate installs the plugin from the repository's catalog file into a fresh clone and runs the test cases. They pass. Two weeks later, the connector's maker releases a new version. Nothing changes for Brightline until someone reads its notes and opens a pull request that moves the pin.

Then a bigger change looks possible. Dave has been thinking of raising the limit to $10,000. So before he decides, Ana and the builder rehearse that day, which means they try it first, on a branch they will never merge.

1. Ana changes rule 4, the limit, in her sheet. A check goes red at once, because the sheet no longer names the limit in the engine, the tested code that does the sorting.
2. The agent moves the sheet's copy in the skill, then changes the tests. Chapter 15's check on existing tests refuses them, because changing a test needs a stated reason: a label on the pull request, and a line that names the new policy, AP policy v4.
3. The agent changes the limit in the engine, in the skill's own script and in the engine's Python version. Each change turns a red check green.
4. The version check blocks the release until the version moves, and the plugin check blocks it until the changelog has an entry. They choose 1.0.0, because the same invoice now lands in a different pile, so this is not a patch.

They keep a second folder at 0.1.0, to stand for a clerk who has not updated, and run the same 13 invoices in both. The old copy prints "brightline-ap 0.1.0, AP policy v3" and the pile counts 4, 2, 2, 5, with INV-6004 for $5,000.01 on Dave's pile. The new one prints "brightline-ap 1.0.0, AP policy v4" and the counts 4, 1, 2, 6, with INV-6004 ready to pay. Dave would know from that one line why the invoice reached his desk. Had the limit gone down, the old copy would have called an invoice ready that needs him, so the first line is how Ana would catch it. They delete the branch. The cost is real: changing one number means a release that changes about a dozen files, and an out-of-date copy is still possible. But anyone who reads its first line can now see it.

The operating rule: give every release a version and a changelog entry, and pin every dependency. Check the plugin in a required check, and test it with repeatable cases before anyone installs it. Move every copy of a changed rule in one reviewed change, and make the report say which version ran.

Figure 16.9. A version moves from a reviewed change to a catalog to an install. A fix is a new version, never an edit to an old one.

Figure 16.10. The same batch in two copies. The first line says which version and which policy gave each answer.

Practice it. Practice: shipping a version, in your own tool, fifteen minutes.