Plugin Migration Plan

This page is a practical migration guide for future refactors.

Migration goal

Move from old workflow-centric logic toward the current model:

• session owns execution
• plugins expose explicit actions
• hooks use pipeline / guard / effect / resolve
• managed plugins own long-lived runtime behavior only when needed

Decision rules

Keep logic in session-adjacent execution when

• it changes how one run is composed or executed
• it depends on history, prompt, or model-loop behavior
• it is part of turn ownership

Move logic into a plugin when

• it exposes capability to callers
• it augments a stable runtime point
• it injects system guidance
• it owns one managed runtime module

How to choose the four hook semantics

pipeline

Use for serial transformation.

guard

Use for validation that can block progress.

effect

Use for side effects only.

resolve

Use for single-owner value selection.

Standard migration steps

1. Identify whether the logic belongs to execution ownership or capability ownership.
2. If it is capability ownership, decide whether it is an action, hook, system block, or managed runtime concern.
3. Replace ad-hoc extension behavior with one of the four stable hook semantics.
4. Push dependency checks and availability logic into the plugin boundary.
5. Update docs when the public behavior or contributor mental model changes.

Good reference cases

• auth around chat ingress
• voice transcription as inbound augmentation
• skill lookup and install as explicit actions
• shell runtime as a managed plugin

What to check next

• whether a file still describes a separate top-level extension layer
• whether workflow ownership is being confused with capability exposure
• whether a plugin is trying to replace session execution instead of augmenting it