Upgrade Microbus

Microbus releases ship more than a Go module. A release can include updated agent rules, revised agent skills, changes to the manifest.yaml schema, refreshed code-generation templates, and occasionally breaking API changes that need adjustments throughout your microservices. A bare go get -u updates the module but leaves the rest behind, and your project quietly drifts out of sync with the framework’s conventions.

The recommended upgrade path is agent-guided. Hand the upgrade to your coding agent and let the upgrade skill walk through the steps in order:

Get the latest version of Microbus.

What the Agent Does

The upgrade skill is opinionated about what’s in scope and runs the steps in a fixed order so the project lands in a known-good state:

  1. Bump the module. Update go.mod to the new Microbus version and run go mod tidy.
  2. Refresh framework-owned files. Replace .claude/rules/microbus.md, the framework’s .claude/skills/, and any other files marked as framework-managed. These are not edited by hand and may have changed shape.
  3. Reconcile each microservice’s manifest. Where the new release adjusts the manifest.yaml schema, walk every microservice and update its manifest to match.
  4. Regenerate. Re-run code generation across all microservices so client stubs, intermediates and OpenAPI documents reflect the current templates.
  5. Adapt for breaking API changes. Where a release includes breaking framework API changes, the skill applies the documented migration to each callsite in your project’s microservices.
  6. Build and test. Build the whole project and run the integration test suite. The skill stops if anything fails and surfaces the diagnosis rather than papering over it.
  7. Record the upgrade. Append the version bump to each microservice’s PROMPTS.md so the audit trail is intact.

If a step fails (a manifest field needs human judgment, a breaking change touches business logic the agent shouldn’t unilaterally rewrite, a test fails for a non-trivial reason) the skill stops and reports. You decide; it doesn’t guess.

Why Not Go Get?

go get -u github.com/microbus-io/fabric@latest updates the module and nothing else:

  • It does not update .claude/rules/microbus.md or .claude/skills/. Future agent sessions then code against stale conventions.
  • It does not touch manifest.yaml files, so manifests fall out of sync with the new schema.
  • It does not regenerate framework-owned code, so client stubs and intermediates drift from the templates that produced them.
  • It does not adapt callsites for breaking API changes, leaving the build broken with no migration trail.

The agent-guided path closes those gaps and keeps your project’s framework-managed surface aligned with the release you’ve actually pulled in.

Verifying the Upgrade

After the agent reports success:

  • go build ./... is clean.
  • The full integration test suite passes.
  • git diff is reviewable - the changes are scoped to the upgrade itself, with clear migration moves rather than incidental edits.
  • PROMPTS.md files reflect the upgrade.

If any of these don’t hold, treat the upgrade as in-progress and rerun the skill or hand-finish the remaining steps.

After a successful upgrade, read the Release Notes for the new version - the upgrade skill applies the mechanical migrations, but the release notes explain why a breaking change was made and any application-level decisions worth revisiting.

Backward Uniform Code Structure Microservice Substrate Forward