resonatehq/resonate-plugins/plugin-prepare

plugin-prepare

Read plugin first — the goal, the approach, the algebra.

Write plugins/<name>/spec/preparation.md: the design the specification is then written from. It decides what the plugin exposes and what shape each operation has; the specification decides how. Every claim comes from the provider's documentation fetched now, never from memorized API knowledge.

Procedure

1. Fetch the API documentation, and the OpenAPI document if one is

published. Actually fetch each URL and confirm what came back is the document rather than an error page or a login wall. Where one is unreachable from here, record what you read instead — a mirror, the provider's shipped source, an official client library. Never fall back on recall.

1. Name the motions: what people actually do with this system, in their

words, not the API's. "Render an image from a template." "Open a support ticket and see it through." A motion a caller would not perform through a durable promise is not a motion for us.

1. Name the resources those motions act on, and pick the primary one —

the one the plugin is about. Most providers have exactly one.

1. Map each motion onto the provider's endpoints, method and path. This is

where the provider's async splits become visible: a motion answered by a submit endpoint plus a status endpoint is one motion, not two.

1. Decide the surface. The primary resource's whole lifecycle, every verb

the provider offers on it; the durable units; the reads that find ids, constrain arguments, and inspect records. Out: instance administration (users, permissions, licences, settings, schema management the provider expects out of band) and transport mechanics (poll endpoints, token exchanges, webhook registration, pagination plumbing).

1. Give each operation its algebra — call or call + poll, nothing

finer. call + poll wherever the provider splits submit from status, since collapsing that split is the point. How the operation begins safely is the specification's Invocation rung and is not decided here. Add <resource>.submit only where the wait is long enough that a caller might not want it and the handle stays good long enough to be redeemed.

1. Write the document. Where a decision was close, say so in Open questions

rather than burying it — the specification agent inherits your judgement and should know which parts were judgement.

Template

~~~markdown

<Provider> — preparation

Motions

Surface

Lifecycle — <primary resource>

Out of scope

Open questions

• <a judgement the specification agent should know was a judgement>

~~~

Write — in the lifecycle table where the provider has no such endpoint; that is an answer. A verb the provider offers and the plugin does not expose needs a reason here and in the specification, not silence.

Style

Tables, endpoints, and short clauses. No prose paragraphs, no alternatives considered, no restating what the plugin skill already says.