shopify-theme-agent

An npm package for setting up instruction files for AI coding agents in Shopify theme projects.

The goal is to let users send short chat prompts such as:

Check file A and fix bug styles
Review this section and flag risks
Audit cart drawer Liquid and JS

The agent will automatically use the configured project context, without requiring the user to repeat long role, stack, or convention prompts. It now also inspects the existing Shopify theme base and Vite setup so the generated instructions follow the actual project standard instead of generic defaults.

The project has evolved into the SLICE Framework (Strategic Limitation and Isolated Context Engineering), implementing high-fidelity context injection, isolated discovery, and architectural drift detection.

Supported IDEs

• antigravity
• cursor
• windsurf
• copilot
• vscode

Installation

Run directly with npx:

npx shopify-theme-agent init \
  --project "Acme Theme" \
  --team "Storefront Team" \
  --ide cursor,windsurf,copilot \
  --flavor vanilla \
  --base-mode discover \
  --theme-root .

Or install it in a project:

npm install -D shopify-theme-agent
npx shopify-theme-agent init --project "Acme Theme" --team "Storefront Team"

Commands

npx shopify-theme-agent init
npx shopify-theme-agent init --project "Acme Theme" --team "Storefront Team"
npx shopify-theme-agent init --ide cursor,windsurf,copilot
npx shopify-theme-agent init --flavor vue-vite
npx shopify-theme-agent init --base-mode discover --theme-root .
npx shopify-theme-agent sync
npx shopify-theme-agent sync --focus liquid,js
npx shopify-theme-agent inspect-standard
npx shopify-theme-agent drift
npx shopify-theme-agent drift --focus wc
npx shopify-theme-agent snapshot
npx shopify-theme-agent print --mode debug --task bug_fix --template shopify
npx shopify-theme-agent doctor
npx shopify-theme-agent presets

Config

Example shopify-agent.config.json:

{
  "projectName": "Acme Theme",
  "teamName": "Storefront Team",
  "projectFlavor": "typescript",
  "agentStyle": "chat-short",
  "themeBaseMode": "discover",
  "themeBasePaths": ["src", "sections", "snippets", "assets"],
  "themeBaseProfile": null,
  "viteAware": true,
  "shopifyThemeRoot": ".",
  "requiredStacks": ["liquid", "html", "css", "js"],
  "optionalStacks": ["typescript"],
  "presets": ["shopify-core", "frontend-core", "tailwind", "theme-typescript"],
  "packageManager": "npm",
  "nodeVersion": ">=20",
  "outputDir": ".agent",
  "ideTargets": ["antigravity", "cursor", "windsurf"]
}

Important Fields

• projectFlavor: vanilla, typescript, vue-vite
• agentStyle: chat-short, chat-detailed
• themeBaseMode: discover, manual
• shopifyThemeRoot: where the Shopify theme base lives relative to the current working directory
• ideTargets: one or more IDE targets

Recommendations:

• use agentStyle: "chat-short" for teams that rely on short chat prompts
• use projectFlavor: "vanilla" unless the theme already uses TS or Vue in production
• use themeBaseMode: "discover" when running inside a real theme repo so the package can mirror the existing code standard

How Users Should Chat After Install

Users do not need long prompts such as:

You are a senior Shopify developer with experience in header components...

They can just send short, task-focused prompts:

Check file A and fix bug styles
Review this section and flag risks
Audit cart drawer Liquid and JS
Refactor this snippet without changing behavior
Explain why this section is slow

Because the package now discovers the theme base, these prompts will be guided by:

• the current Vite entry strategy
• existing Liquid and schema patterns
• the current CSS strategy
• representative section, snippet, asset, and source file conventions
• the inferred review checklist for the current theme base

Generated Output

Depending on ideTargets, the package can generate:

• antigravity -> .agent/*
• cursor -> .cursor/rules/*.mdc, AGENTS.md, AGENT_WORKFLOWS.md, sections/AGENTS.md, snippets/AGENTS.md, assets/AGENTS.md, src/AGENTS.md
• windsurf -> .windsurf/rules/*.md, .windsurf/workflows/*.md, AGENTS.md, AGENT_WORKFLOWS.md, sections/AGENTS.md, snippets/AGENTS.md, assets/AGENTS.md, src/AGENTS.md
• copilot / vscode -> .github/copilot-instructions.md, .github/instructions/*.instructions.md, AGENTS.md, AGENT_WORKFLOWS.md, sections/AGENTS.md, snippets/AGENTS.md, assets/AGENTS.md, src/AGENTS.md
• all non-antigravity targets also generate THEME_STANDARD.md and PROMPT_EXAMPLES.md

Important:

• .agent/* is generated only when ideTargets includes antigravity
• if you run init --ide cursor, the package should not create .agent/*

Theme Base Discovery

When themeBaseMode is set to discover, the package inspects the current theme repo and infers:

• Vite usage and entry conventions
• compile flow from vite.config.* and package.json scripts
• section, snippet, template, layout, asset, and source directories
• config files such as Tailwind, TS, ESLint, Prettier, and Stylelint
• representative Liquid, CSS, JS, TS, and Vue patterns
• a project-specific review checklist

Tailwind CSS v4 note:

• the package does not require tailwind.config.* to detect Tailwind CSS v4
• it can detect Tailwind v4 from CSS-first signals such as @import "tailwindcss", @theme, @utility, @source, and related Vite/PostCSS dependencies

Tech Stack Detection & Support

The shopify-theme-agent doesn't just guess; it performs a deep-scan of your codebase to tailor the AI's technical instructions.

1. Shopify Liquid (OS 2.0 Focus)

• Detection: Analyzes sections/*.liquid for modern JSON schemas and blocks usage.
• Guidance: Enforces schema-strict conventions, requiring accessible labels and merchant-safe defaults. It prevents "logic bloat" in Liquid and promotes snippet-based modularity.

2. Modern Frontend (Vite & ESM)

• Detection: Checks package.json for vite, @shopify/prettier-config, and entry points in src/.
• Guidance: If Vite-aware, the agent understands the relationship between Liquid data-attributes and JS entry points. It prioritizes ESM modules and prevents unnecessary global script sprawl.

3. Styling (Tailwind CSS v4 & Scoped CSS)

• Detection: CSS-first detection (ignores legacy config requirements). Look for @import "tailwindcss", @theme, or utility-driven patterns.
• Guidance: Enforces project-specific Tailwind tokens and layering. If using Scoped CSS, it promotes BEM or utility-first patterns consistently.

4. Custom Elements (Lit & Web Components)

• Detection: Scans for customElements.define and LitElement base classes.
• Guidance: Provides specific lifecycle rules (e.g., proper event cleanup in disconnectedCallback), attribute-driven APIs, and Shadow DOM styling management.

5. Shopify MCP (The Documentation Bridge)

• Integration: Leverages the @shopify/dev-mcp protocol to give the AI real-time access to Shopify's APIs and documentation, eliminating the need for hardcoded (and often outdated) platform limits.

SLICE Framework & MCP

The shopify-theme-agent implements the SLICE (Strategic Limitation and Isolated Context Engineering) Framework to solve the "context drift" and "hallucination" problems in large-scale Shopify development.

Isolated Discovery & Confidence

The discovery engine uses concern-specific scanners (Liquid, CSS, JS, Web Components, Schema) to build a project profile. Each discovery signal is assigned a Confidence Score (0-3):

• 3 (High): Explicit config or clear code pattern detected.
• 2 (Medium): File presence suggests the pattern, but implementation is mixed.
• 1 (Low): Guess based on directory structure or common defaults.
• 0 (None): No evidence of the pattern.

Skills and rules are dynamically injected into the agent context only when confidence ≥ 2, ensuring the agent doesn't "hallucinate" standards that don't exist.

Knowledge Persistence

Custom project decisions, naming conventions, and architectural locks are stored in .agent/knowledge/ (gitignored). This acts as a "long-term memory" for the agent across sessions.

Architectural Drift Detection

The drift command compares the current codebase against the recorded Knowledge and Theme Standard. It flags deviations, such as:

• New CSS patterns that bypass the established Tailwind/Utility strategy.
• Web Components using lifecycle hooks that violate the project's Lit/Vanilla standard.
• Hardcoded secrets or missing ADA labels in newly added sections.

@shopify/dev-mcp Integration

The agent is now MCP-aware. When the @shopify/dev-mcp preset is active, the agent follows Documentation-First rules:

• Prioritize Tools: Always uses search_documentation and introspect_schema before guessing Liquid filters or GraphQL fields.
• Schema Lock: Automatically introspects the Shopify API schema when writing Functions or App blocks.

To enable, ensure the official Shopify MCP server is configured in your IDE (Cursor/Windsurf).

Use:

npx shopify-theme-agent inspect-standard

This prints the discovered theme-base profile and the active agent context for the current project.

The output also includes compile-flow signals such as:

• build script
• dev script
• Shopify scripts
• detected compile targets
• Vite build signals like manifest, rollup input maps, and custom outDir