shopify-app-kit

Change Admin API GraphQL calls, webhook handlers or app toml declarations in a Shopify app without breaking the API-version pins, webhook parity or error-handling contracts declared in this repo's .claude/shopify-app.json. Use when adding or editing a GraphQL query or mutation, a webhook topic or handler, a metaobject or metafield definition, or when a mutation returned userErrors or THROTTLED.

Start, run and cleanly stop a local Shopify app dev session against the dev registration named in this repo's .claude/shopify-app.json (the right --config, the right store, tunnel port in a sandbox, app dev clean at the end, theme work outside the app repo). Use when asked to run the app locally, preview a theme extension, start app dev, or when a dev session ended without cleaning up.

Put a fact, rule or decision in the one document that owns it in a Shopify app repo, keep reference docs free of dates and incidents, replace warnings with the check that enforces them, and keep the always-loaded instructions file small. Use when editing CLAUDE.md, .claude/rules, an architecture or ops doc, an ADR, or when a review found the same fact stated in two places.

Validate this repo's .claude/shopify-app.json against the kit schema, print its app facts, report vendored-hook or settings drift, check the two companions (the Shopify plugin and the graphify skill), and report the liveness of every scheduled workflow. Use when starting work in a Shopify app repo, after a kit sync, when a guard hook blocked something unexpectedly, or before creating the routine triggers.

Maintainer guide for the shopify-app-kit repo itself, covering how to add a skill, hook, agent or lesson, run the tests, bump the version and release (tags are created on merge). Use when changing the kit's own files rather than a consumer app.

Scaffold a new Shopify app repo. Runs shopify app init from the official React Router template (or clones it when init needs an account), applies the kit's repo shell from templates/ with the placeholders substituted (manifest, vendored guards, CI, secret scanning, docs map, ADR seeds), makes the edits a public app needs (expiring offline tokens, Postgres datasource, first ADR), verifies the result, and makes one local commit. Never creates the remote, the Partner registration, the hosting app, the database project or a secret; those are printed as the maintainer's checklist. Use when starting a Shopify app from scratch, when asked to scaffold or bootstrap an app repo, or to preview the shell with --dry-run.

Drive a Shopify app release the way this repo's .claude/shopify-app.json allows it. Runs the release-readiness workflow, opens the promotion PR (never merges it), releases extensions with the deploy config or says the step is operator-only, explains how the server ships from its branch, scales to zero before migrating when required, and warns before any live billing action. Use when asked to release, promote, ship, deploy, or cut a version of the app, or when the operator wants a release checklist.

Deep pre-merge review of a Shopify app branch. Runs the kit's correctness/security and code-quality review agents in parallel, each checking the diff against this repo's .claude/shopify-app.json, then synthesizes one verdict. Use when a branch or PR needs a harsh, thorough audit before merge or promotion, or when asked for a deep, thermonuclear or full review.

Vendor the kit's guard hooks into this repo's .claude/hooks/kit/, stamp their version headers, record kit.version in .claude/shopify-app.json, and print the settings.json registration snippet. Use when adopting the kit in a repo or after upgrading the pinned kit version.

Write an offline test that fails a PR the moment two places in the repo disagree (a pin and a toml, a registry and its consumers, a docs map and the docs, a hand-written list and the workflows) and says exactly which file to fix and what to write. Use when a CLAUDE.md warning could be a check, when two files must stay in sync, when a review found drift, or when asked for a tripwire, parity test or drift test.