plugin-interaction-runtime-design

Start from a validated Plugin-Spec.md and plugin.yaml, then classify decisions into user decisions, architect decisions, and platform facts. Interview the user only on experience trade-offs, define UI-Agent request and result contracts, MCP tool catalogs, state layers, and host adapters, then validate everything through scenario walkthroughs before writing Plugin-Design.md.

App-only tools are deterministic capabilities called only by the UI, such as load_state or upload_asset, and are hidden from the model. Agent-visible tools expose domain operations to the host agent, use domain-specific names, and include requestId, version checks, and structured outputs for safe write-backs.

A runnable spike is mandatory for UI Complexity Class C, which covers infinite canvases, timelines, 3D rendering, professional editor interactions, or large media handling. The spike validates the one to three highest-risk assumptions and must pass before the design can be marked DESIGN_READY.

Each target gets its own host adapter section with a primary path, UI surface, agent trigger, fallback, and verification method based on verified platform facts. If a required target has no feasible path, the design returns to the spec phase instead of assuming an ideal architecture.

If the spec contains P0 open questions, requirements without acceptance criteria, or an unclear required target, the design phase stops and returns to the spec-building skill. The design stage never guesses requirements on behalf of the specification.