[RFC] application/optimization-plan — create and edit an app-owned plan of evidence-backed improvements

[dylanjhunt]

What type are you proposing?

application/optimization-plan, supporting create and edit. The immediate AgentReady use is edit; create is proposed for ecosystem completeness but AgentReady would not register it until starting a new plan is separately designed. If this is too broad, application/setup-plan is a possible narrower fallback.

What do merchants ask Sidekick to do?

Merchants have app-owned plans containing evidence-backed improvements and ask Sidekick to review or change the approval state of those proposals, for example:

• “Review the remaining recommendations in my store optimization plan.”
• “Approve the description and taxonomy fixes, but decline the title change.”
• “Open the current plan so I can confirm these decisions.”
• “Continue editing the optimization plan I started earlier.”

The intent opens an app-owned review UI. Proposed changes remain locally staged until a separate explicit merchant confirmation. Saving decisions does not apply or publish the underlying changes.

What apps would register it?

Apps that own merchant-reviewable plans for store readiness, accessibility, SEO, catalog quality, conversion optimization, merchandising, content quality, performance, or operational setup could plausibly register this type. The schema should describe the merchant-facing plan, not AgentReady's internal run or proposal tables.

What fields might it need?

Provisional artifact shape for Shopify review:

{
  "id": "app-owned stable plan identifier used for edit",
  "title": "merchant-visible plan title",
  "status": "draft | in_review | approved | partially_approved | completed | superseded",
  "summary": "short merchant-visible summary",
  "items": [
    {
      "id": "stable item identifier",
      "title": "merchant-visible improvement",
      "description": "bounded explanation and evidence summary",
      "decision": "unresolved | approved | declined"
    }
  ]
}

All fields should remain optional in an app action input schema; no required array should be declared. The final field names, identifier/value mapping, $ref, and additionalProperties behavior should follow Shopify's published convention. In particular, if Sidekick's canonical edit contract supplies the selected resource through top-level intent value, apps should consume that value rather than inventing a parallel inputSchema.planId.

Concurrency revisions, Store IDs, access tokens, internal database IDs, and apply/publish instructions do not belong in the model-facing schema. The extension loads authoritative revisions from its authenticated app state and attaches them only on explicit merchant confirmation.

What existing type is close?

None of the current types describes a cross-domain, app-owned plan of proposed improvements. application/campaign and application/ad are marketing artifacts; application/faq, application/review, and application/ticket describe different merchant objects. application/setup-plan would cover onboarding/setup checklists but may be too narrow for ongoing evidence-backed optimization work.

Safety and interaction boundary

The intent is a navigation/render contract, not a webhook or autonomous mutation. The merchant reviews staged decisions and clicks a separate Save decisions control. Saving approval state does not apply, publish, bill, alter a theme, or claim public verification. Apps must authenticate the Store, authorize the exact app-owned plan, reload on concurrency conflict, and preserve truthful staged/saved/applied/verified distinctions.

Questions for Shopify

1. Is application/optimization-plan appropriately general across the ecosystem, or would Shopify prefer application/setup-plan or another existing/planned type?
2. For edit, should the selected app-owned plan identifier arrive through the canonical top-level intent value, an id inside the published schema, or both?
3. Should a plan schema include bounded items/decisions, or should Sidekick pass only the plan identity while the extension loads all item state?

[vividviolet]

@dylanjhunt Thanks for the detailed RFC. Good news - we're working on making application/optimization-plan available!

Answers to your three questions below:

1. Is application/optimization-plan appropriately general?

Yes, and we'd rather have the general type than the narrower one. We looked at broader
names (plan, action-plan) and they get too abstract to be useful for routing —
"plan" could mean almost anything a merchant owns. setup-plan goes too far the other
way: onboarding is a subset of what you describe, and your own examples ("review the
remaining recommendations", "continue editing the plan I started earlier") are ongoing
optimization work, not setup. optimization-plan names the thing well — a shared,
app-owned group of proposed improvements that a merchant reviews and decides on.

Both create and edit will be enabled on the type, consistent with the rest of
application/*.

2. For edit, should the plan identifier arrive via value, a schema id, or both?

value. Your instinct in the RFC is right: it's better not to create a parallel inputSchema.planId. The intent schema has two top-level sections — value is the primary identifier of the resource being acted on, and inputSchema.properties is the additional data the caller provides. They travel separately: value becomes the value parameter of intents.invoke(), the input properties become data, and your extension reads both off shopify.intents.request.

    {
      "$schema": "https://extensions.shopifycdn.com/shopifycloud/schemas/v1/intent.json",
      "value": {
        "type": "string",
        "description": "The ID of the optimization plan to edit.",
        "mapTo": "param",
        "fieldName": "id"
      },
      "inputSchema": {
        "$ref": "https://extensions.shopifycdn.com/shopifycloud/schemas/v1/application/optimization-plan.json",
        "type": "object",
        "properties": {}
      }
    }

One gotcha if you use the admin.app.intent.link target: value always needs an explicit fieldName when you map it to a URL param or query_param, because unlike an inputSchema property it has no key to fall back to. That doesn't apply to
admin.app.intent.render.

3. Bounded items/decisions, or plan identity only?

Identity only, at least to begin with. We're going to scope the published application/optimization-plan.json only with id. Each app is able to augment the base schema with title, status, etc... to fit their use case.

[charlesdobson]

@dylanjhunt application/optimization-plan is available now. Added to the catalog.

We'd love to see what you build with it with AgentReady!