Mitasu for Apparel — AI Operations Guide (spec for AI agents)

Version 2026-07-10 (kept in sync with the app; consistency is test-enforced). How to use: paste this entire document into an AI assistant that can reach the Shopify Admin API (Claude + the Shopify connector, Claude Code + a Shopify MCP, or a custom agent), then ask it to register or assign product information. 日本語版: https://mitasu.tech/ai/apparel-agent-guide.ja.md

All of this app’s data lives in Shopify metafields/metaobjects (no external database; every key is under the apparel_info namespace). Any AI agent with Admin GraphQL access can therefore create templates and assign them to products without going through the app’s admin UI.

Most important: the two safe paths

1. [Safest — recommended] The CSV path — use the app’s CSV export → the AI fills in the columns → CSV import (Pro). Name-based references, validation and caps are all enforced by the app. Columns: title, handle, size_chart, spec, outfits, models, faq (references go by template name; Q&A by question text; multiple values |-separated; empty columns are left unchanged).
2. [Advanced] Direct GraphQL — follow this spec exactly. Only ever create templates (metaobjects) and assign references — never write any other key.

Absolute rules (violations break the storefront and/or the app admin)

1. Store measurements in cm only (never store inch — the app converts at display time).
2. Write only template creations and ref assignments. Never write *_override / fit_feedback / return_stats / fit_baseline / review_pending / insights_cache / installed_at / plan / plan_cancel_at (app-managed aggregates & internals). For per-product tweaks, tell the owner to use the app’s override UI.
3. Never create new data in legacy keys: inline materials / care / model_fit / fit_details (product AND variant), the singular outfit_ref, the old faq JSON, faq_custom_items, faq_order — all read-only fallbacks. Fabric composition, color, stretch etc. belong in Shopify’s standard category metafields (entered on the product page); the app displays them automatically in the Features tab. Do not mirror them into the app namespace.
4. Assignment caps: outfit_refs ≤ 4 / model_refs ≤ 4 / faq_items ≤ 10; worn products per outfit (items) ≤ 6.
5. Search for an existing template by name before creating one (no duplicates). Delete templates only through the app UI (a raw delete skips the assignment/override cleanup).
6. Before destructive changes (replacing existing refs, bulk updates), read the current values and confirm with the user.
7. metafieldsSet accepts ≤ 25 entries per call. Always check userErrors.

Data model (current = Plan A: template references + per-product overrides)

Templates = metaobjects (5 reusable types)

apparel_info_size_chart

apparel_info_spec (fabric & spec profile)

apparel_info_model (model fit): name (required) / height_cm / weight_kg / size_worn / fit_tag (tight/regular/loose/oversize) / comment / image (photo URL string)

apparel_info_faq (one Q&A pair): question (required) / answer (required)

apparel_info_outfit (complete-the-look): name (required) / items (list.product_reference — product GIDs, ≤ 6) / note / image (file_reference — a Files GID; omit if unavailable)

Product metafields (assignment — these 6 are the ONLY writable ones)

Variant metafields (writable)

size_chart_ref / spec_set_ref only (e.g. separate charts for “Regular” vs “Tall” variants).

Shop settings (SHOP-owned) — prefer pointing the owner to the app’s Settings

feature_flags (section on/off) / section_order / section_titles / default_unit (cm|inch) / week_start (mon|sun). Reading them is fine.

Care codes (for apparel_info_spec.care)

Recommended workflow (analyze products → create templates → assign)

1. Read the products — classify garment type, audience (men/women/kids) and fabric feel from title/description/type/tags/standard category.
2. Search existing templates first — metaobjects(type: "...", first: 250) and check names. Reuse matches (owners often already imported some of the app’s 68 bundled size-chart templates via the UI).
3. Create only the missing templates — follow the schemas above exactly (especially measurement_type and cm-only).
4. Assign — metafieldsSet with the refs (list values are a JSON string like "[\"gid://...\"]"). Or generate a CSV and have the owner import it (the safest route).
5. Verify — have the owner check the coverage badges on the app’s “Products” screen or the Insights coverage.

GraphQL examples

Create a size-chart template

mutation {
  metaobjectCreate(metaobject: {
    type: "apparel_info_size_chart",
    fields: [
      { key: "name", value: "Men's tee S-XL" },
      { key: "category", value: "top" },
      { key: "audience", value: "men" },
      { key: "measurement_type", value: "garment" },
      { key: "unit_primary", value: "cm" },
      { key: "fit_tag", value: "regular" },
      { key: "stretch", value: "false" },
      { key: "length_tag", value: "regular" },
      { key: "rows", value: "[{\"size_label\":\"S\",\"measurements\":{\"chest_cm\":86,\"length_cm\":66}},{\"size_label\":\"M\",\"measurements\":{\"chest_cm\":92,\"length_cm\":69}}]" }
    ]
  }) { metaobject { id } userErrors { field message } }
}

Assign to a product (size chart + spec + Q&A)

mutation {
  metafieldsSet(metafields: [
    { ownerId: "gid://shopify/Product/123", namespace: "apparel_info", key: "size_chart_ref",
      type: "metaobject_reference", value: "gid://shopify/Metaobject/456" },
    { ownerId: "gid://shopify/Product/123", namespace: "apparel_info", key: "spec_set_ref",
      type: "metaobject_reference", value: "gid://shopify/Metaobject/789" },
    { ownerId: "gid://shopify/Product/123", namespace: "apparel_info", key: "faq_items",
      type: "list.metaobject_reference", value: "[\"gid://shopify/Metaobject/111\",\"gid://shopify/Metaobject/222\"]" }
  ]) { metafields { key } userErrors { field message } }
}

List existing templates (duplicate check / get GIDs for assignment)

{ metaobjects(type: "apparel_info_size_chart", first: 250) {
    nodes { id field(key: "name") { value } }
    pageInfo { hasNextPage endCursor } } }

Troubleshooting

• UNDEFINED_OBJECT_TYPE / definition errors → have the owner run the app’s “Settings → Re-check” (definitions self-heal).
• Assigned but not visible on the storefront → check in order: ① is the feature Pro-only while the store is on Free (model fit / spec / outfits / votes / confidence badge are Pro)? ② is the section toggled off in Settings? ③ is the app block placed in the theme?
• Refs beyond the caps are not rendered — keep lists within the limits.