Distribute and Maintain Extensions

Use a portable repository layout

code-extensions/
  schema/
    autohand.extension.schema.json
  extensions/
    acme.code-health/
      autohand.extension.json
      README.md
      LICENSE
      tools/
      agents/
      tests/

Each extension directory should work when copied out of the monorepo. It must not depend on unpublished workspace packages, generated files that are absent from the release, or scripts that installation is expected to run—Extension API v1 does not execute them.

Write an operator-ready README

Document more than purpose. A user evaluating a shell-backed capability needs exact lifecycle commands and a clear permission model.

Package id, current version, Extension API version, license, and repository.
Exact tools and agents with inputs and expected output.
Executables required by each handler and supported operating systems.
Validation, user install, project install, linked development, show, doctor, disable, enable, and removal commands.
Which operations read files, mutate state, access a network, or typically prompt for permission.
Known conflicts, upgrade notes, and contribution renames.

Version both behavior and identity

The manifest version describes package behavior; extensionApi describes the runtime contract it targets. Keep them independent. A tool description correction might bump the package patch version without changing the API version. A future incompatible platform contract would require a new extension API.

Change	Suggested package bump	Release note
Clarify README or prompt without changing outputs	Patch	Documentation or prompt clarification
Fix a compatible handler bug	Patch	Input and output behavior corrected
Add a tool or agent	Minor	New contribution and permission implications
Add an optional input	Minor	Default behavior and example
Rename a tool, remove an agent, or change a required input	Major	Migration mapping and affected prompts or automation

Test the artifact users will install

A linked package proves the development loop. It does not prove a release is self-contained. Your release gate should create a clean checkout or archive, validate it, copy-install it into an isolated Autohand home and workspace, and start a fresh process.

autohand extensions validate ./extensions/acme.code-health --json
autohand extensions install ./extensions/acme.code-health
autohand extensions show acme.code-health --json
autohand extensions doctor --json
autohand extensions disable acme.code-health
autohand extensions enable acme.code-health
autohand extensions remove acme.code-health --yes

Run this lifecycle for every package in a collection. Assert exact contribution names and provenance rather than only matching a success string.

Publish immutable source

Extension API v1 accepts local directories, not remote URLs. Publish a Git tag or release archive, and instruct users to install from a checkout of that immutable version:

git clone https://github.com/acme/code-extensions.git
cd code-extensions
git checkout v1.4.0

autohand extensions validate ./extensions/acme.code-health
autohand extensions install ./extensions/acme.code-health

Do not tell users to install from an unpinned branch. A branch can change after review, making the source-to-installed-content decision irreproducible.

Maintain a compatibility matrix

Package version	Extension API	Autohand Code range	Platforms	Status
`1.4.x`	`1`	Your tested minimum through current	macOS, Linux	Supported
`1.3.x`	`1`	Previous supported line	macOS, Linux	Security fixes only
`0.x`	`1`	Historical	Varies	Unsupported

Populate the Autohand Code range from versions actually exercised in CI. Do not claim compatibility from schema validation alone; runtime executables, permission behavior, and active registry composition also matter.

Respond to a bad release

Tell users to disable the extension immediately, preserving it for inspection.
Publish the exact affected ids, versions, tools, and operating conditions.
Provide removal and rollback instructions to the previous immutable version.
Fix the source, add a regression fixture, and rerun linked plus copied lifecycle tests.
Publish a new version; never move the old tag.

For a hands-on release workflow, follow Validate and publish an extension.