Linked Extension Development Workflow

Understand linked state

A linked install places a directory link at the selected extension root and records linked: true in separate Autohand state. The authored package remains at its original path. Disable and enable update state only; removal deletes the registered link and state, not the source.

Mode	Runtime reads	Best use	Release proof?
Linked	Your working directory	Fast editing and local iteration	No
Copied	A validated copy under the extension root	Normal use and immutable-version testing	Yes, with a fresh process

Install an explicit development link

autohand extensions validate ./acme.code-health
autohand extensions install ./acme.code-health --link
autohand extensions show acme.code-health --json

Confirm linked is true and root resolves to the authored package. If a different package with the same id is installed, do not delete it manually; remove it deliberately or use --replace after reviewing the ownership change.

Run the edit–validate–refresh loop

Edit one declared tool or agent file.
Run autohand extensions validate ./acme.code-health against source.
Run autohand extensions doctor against the installed registry.
In a normal active session, disable and re-enable the package to load a new complete snapshot.
Repeat a focused smoke task and inspect the result.

/extensions disable acme.code-health
/extensions enable acme.code-health
/extensions show acme.code-health
/extensions doctor

Mutations refresh tools and agents in the active session transactionally. For prompt changes that could be affected by conversation context, start a new session after refresh.

Recover from an invalid edit

Temporarily add an unknown field to a tool fixture or break a declared path. Validation should fail, and doctor should diagnose the installed linked package. Because a package activates as a unit, its other contributions should not remain partially active.

autohand extensions validate ./acme.code-health --json
autohand extensions doctor --json

Restore the last valid file, validate again, then disable/enable. Do not edit files inside ~/.autohand/extensions; the source directory is the authoring truth.

Test removal safety

autohand extensions remove acme.code-health --yes
test -d ./acme.code-health
autohand extensions list
autohand extensions doctor

The source-directory check should succeed. The installed registry should no longer list the package. If it does, use show with an explicit scope to find a second user or project installation.

Prove a copied installation

After the linked loop passes, install a copy from a clean source checkout:

autohand extensions validate ./acme.code-health
autohand extensions install ./acme.code-health
autohand extensions show acme.code-health --json
autohand extensions doctor --json

Move or temporarily rename the source checkout; the installed package should remain usable.
Start a new Autohand process.
Exercise every contributed tool with expected approvals.
Delegate one task to every contributed agent.
Disable, enable, and remove the copied package.

Release rule: never publish from a tree that only passed linked testing. Copied installation catches undeclared files, path mistakes, and accidental dependencies on the authoring checkout.