Shopify Factory Skill

Structured workflow enforcement untuk Shopify Theme Factory.

Skill ini memastikan AI agent mengikuti pipeline yang benar dengan gate validation, fresh-context subagents, dan state tracking. Seperti GSD framework, skill ini fully portable dan bisa di-install di mana saja.

✨ Features

• 🧭 GSD-like Driver Commands - /shopify-next and /shopify-run for guided/autonomous progression
• 🔄 Structured Workflow - Pipeline enforcement dari research sampai release
• 🤖 Fresh-Context Subagents - Setiap phase spawn subagent baru (prevent context rot)
• ✅ Gate Validation - Tidak bisa skip step, quality guaranteed
• 🛡️ Shopify Dev MCP Integration - Anti-hallucination untuk Liquid code
• 🎯 Buyer Journey Framework - 6 archetypes, 7-stage buying journey
• 📦 Standalone Package - Semua factory files included, no external dependencies
• 🚀 Portable - Works across VPS, folders, environments
• 📊 State Tracking - STATE.md, CONTEXT.md, registry.json

📋 Prerequisites

• Node.js 18+
• AI Agent Runtime (OpenCode, Claude Code, atau compatible)
• Shopify Partner Account (untuk theme development)
• Shopify CLI (npm install -g @shopify/cli)

🚀 Installation

Quick Install (Recommended)

# Using npx (no global install needed)
npx shopify-factory-skill@latest

# Or install globally
npm install -g shopify-factory-skill

The installer will:

1. Detect your AI agent runtime (OpenCode, Claude Code)
2. Install the skill to the appropriate location
3. Optionally initialize a factory in your current directory
4. Configure the skill to point to your factory

🆕 First Run From an Empty Folder

If you are starting from a brand-new empty directory, you do not need to create factory/, shared/, themes/, or automation/ yourself. The npm package includes a complete factory-template/, and /shopify-setup --init copies that template into your current folder.

There are two separate steps:

1. Install the skill into your AI agent runtime
2. Initialize a Shopify Factory workspace in your project folder

Option A: Install and initialize in one flow

mkdir my-shopify-factory
cd my-shopify-factory
npx shopify-factory-skill@latest

When the installer asks:

Initialize factory in current directory? (y/n):

Choose y. The installer will create the workspace folders in the current empty directory.

Option B: Skill already installed

If the skill is already installed, create an empty workspace and initialize it from inside OpenCode:

mkdir my-shopify-factory
cd my-shopify-factory

Then run in OpenCode:

/shopify-scan
/shopify-setup --init
/shopify-help

Folder tree after initialization

After init, your previously empty folder becomes:

my-shopify-factory/
├── .shopify-factory/          # workspace marker and metadata
├── AGENTS.md                  # agent instructions for this factory
├── factory/                   # registry, templates, scoring, scripts
├── shared/                    # reusable sections, snippets, styles, locales
├── themes/                    # generated THEME-NNN workspaces
├── automation/                # QA scripts and Playwright setup
├── SHOPIFY_LIQUID_CREATION_WORKFLOW.md
├── SHOPIFY_THEME_FACTORY_OPERATING_SYSTEM.md
└── THEME_FACTORY_ARCHITECTURE.md

Only after this initialization should you start creating themes:

/shopify-scaffold pet-wellness education-led-commerce
/shopify-run THEME-001 --until spec

Manual Installation

If you prefer manual installation:

# 1. Clone repository
git clone https://github.com/izestylusx/shopify-factory.git
cd shopify-factory

# 2. Copy to OpenCode skills directory
cp -r . ~/.config/opencode/skills/shopify-factory/

# 3. Initialize factory in your project
mkdir ~/my-shopify-factory
cd ~/my-shopify-factory

# 4. In your AI agent, run:
/shopify-setup --init

Verify Installation

# Check if skill is installed
ls ~/.config/opencode/skills/shopify-factory/

# Should see:
# ├── workflows/
# ├── references/
# ├── templates/
# ├── factory-template/
# ├── SKILL.md
# └── config.json

📋 Available Commands

After installation, you can use these commands in your AI agent:

/shopify-scan                              # Scan current folder and recommend next action
/shopify-help                              # Beginner guide and best practices
/shopify-next [THEME-NNN]                  # Run one next lifecycle step
/shopify-run [THEME-NNN] --until <target>  # Autonomous lifecycle chain
/shopify-assets <THEME-NNN>                 # Generate/prepare demo visual assets
/shopify-ui-review <THEME-NNN>              # Audit built theme UI/layout/accessibility
/shopify-fix <THEME-NNN> "issue"            # Apply small targeted repair
/shopify-rework <THEME-NNN> "scope"         # Plan/execute larger visual/layout rework
/shopify-scaffold <niche> <archetype>    # Create new theme
/shopify-research <THEME-NNN>            # Market research
/shopify-spec <THEME-NNN>                # Create specification
/shopify-build <THEME-NNN>               # Build Liquid theme
/shopify-qa <THEME-NNN>                  # QA validation
/shopify-package <THEME-NNN>             # Package for release
/shopify-status                          # Show all themes
/shopify-setup                           # Configure factory path

🎯 Quick Start

# 1. Create an empty workspace folder
mkdir my-shopify-factory
cd my-shopify-factory

# 2. Install the skill and answer "y" when asked to initialize
npx shopify-factory-skill@latest

Then in OpenCode:

/shopify-scan
/shopify-help
/shopify-scaffold pet-wellness education-led-commerce
/shopify-run THEME-001 --until spec
# Review strategy/spec artifacts
/shopify-assets THEME-001
/shopify-run THEME-001 --until package --yes
/shopify-status

🧭 Recommended Workflow for Beginners

Start with /shopify-scan. If no factory exists, run /shopify-setup --init. Then use /shopify-help to choose niche/archetype, /shopify-scaffold, and /shopify-run THEME-001 --until spec. Review the strategy/spec, then continue with /shopify-run THEME-001 --until package --yes.

Multi-Page Theme Coverage

The build workflow must not stop at a polished homepage. A complete theme must include and QA these storefront surfaces:

• homepage: templates/index.json
• product detail: templates/product.json
• collection/catalog: templates/collection.json
• generic page/about: templates/page.json
• cart: templates/cart.json
• search: templates/search.json

/shopify-spec, /shopify-build, /shopify-qa, and /shopify-ui-review now treat homepage-only output as incomplete.

Post-Build Maintenance and Repair

If a finished or nearly finished theme has layout bugs, broken responsive behavior, weak hierarchy, or visual polish issues, use the maintenance commands instead of restarting the whole lifecycle:

/shopify-ui-review THEME-001
/shopify-fix THEME-001 "mobile hero text overlaps image"
/shopify-rework THEME-001 "homepage layout feels cramped and product grid lacks hierarchy" --plan-only

• Use /shopify-ui-review to diagnose without editing.
• Use /shopify-fix for small localized fixes.
• Use /shopify-rework for larger multi-section or design-system changes.

Template Demo Content Mindset

This factory creates Shopify themes/templates for resale. The demo should look polished, persuasive, and complete. Sample reviews, avatar/profile images, dummy product photos, lifestyle imagery, logo placeholders, offer bars, and editable countdown sections are allowed and often necessary for showing the template well.

The boundary is: demo content must be original, replaceable, and not copied from competitors or presented as verified real merchant data.

Demo Images and Visual Assets

The skill can prepare demo visuals before build with:

/shopify-assets THEME-001

When codex-imagegen is available, this phase can generate assets such as hero banners, lifestyle/product placeholder images, testimonial avatars, decorative icons, and logo placeholders. If image generation is unavailable, it creates stable placeholders and an asset manifest instead.

Niche, Archetype, Buyer Journey, and Scoring

• Niche: the store category/customer problem, like pet-wellness, clean-beauty, or handmade-jewelry.
• Archetype: the sales journey structure. If unsure, use education-led-commerce for explanation-heavy products, gift-decision-system for gift products, editorial-lifestyle-system for visual brands, or expertise-trust-system for experts/services.
• Buyer journey: the shopper questions the theme must answer from awareness through purchase and repeat buying.
• Opportunity score: a research score that tells you whether the theme idea is strong enough to build.

🗂️ Workspace Folder Model

Shopify Factory does create a hidden workspace marker folder:

.shopify-factory/
├── README.md
└── workspace.json

Think of .shopify-factory/ as the factory anchor/marker. It tells /shopify-scan and humans, “this directory is a Shopify Theme Factory workspace.”

The actual working artifacts live outside that marker:

factory/registry.json        # status of all themes
factory/templates/           # reusable PRD/spec/QA templates
shared/                      # reusable sections/snippets/styles/locales
themes/THEME-001/            # state, research, strategy, build, QA, package

So .shopify-factory/ is the marker; factory/ and themes/ are the operational workspace.

🏗️ Architecture

Skill Structure

shopify-factory-skill/
├── package.json                    # npm package config
├── bin/
│   └── shopify-factory.js         # Installer script
├── skill/                          # Skill files (installed to runtime)
│   ├── SKILL.md                   # Main entry point
│   ├── config.json                # Path configuration
│   ├── workflows/                 # Workflow definitions
│   │   ├── scaffold-theme.md
│   │   ├── research-phase.md
│   │   ├── spec-phase.md
│   │   ├── build-phase.md
│   │   ├── qa-phase.md
│   │   ├── package-phase.md
│   │   ├── status.md
│   │   └── setup.md
│   ├── references/                # Reference documentation
│   │   ├── agent-contracts.md
│   │   ├── gate-prompts.md
│   │   ├── shopify-mcp-guardrails.md
│   │   └── buyer-journey-framework.md
│   └── templates/                 # State templates
│       ├── STATE.md
│       ├── CONTEXT.md
│       └── VERIFICATION.md
├── factory-template/              # Factory template (copied to project)
│   ├── AGENTS.md                  # Agent instructions
│   ├── factory/                   # Factory structure
│   │   ├── templates/             # Document templates
│   │   ├── scripts/               # Automation scripts
│   │   ├── checklists/            # Validation checklists
│   │   └── registry.json          # Theme registry
│   ├── shared/                    # Shared components
│   │   ├── section-library/       # Reusable sections
│   │   ├── snippet-library/       # Reusable snippets
│   │   ├── locales-base/          # Translation files
│   │   └── base-styles/           # Base CSS/JS
│   ├── automation/                # QA automation
│   │   ├── scripts/               # QA scripts
│   │   └── playwright/            # Browser tests
│   └── *.md                       # Documentation
└── README.md                      # This file

Installation Flow

┌─────────────────────────────────────────────────────────────┐
│ npm install -g shopify-factory-skill                        │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│ bin/shopify-factory.js (Installer)                          │
│                                                              │
│ 1. Detect runtime (OpenCode, Claude Code)                   │
│ 2. Copy skill/ to runtime skill directory                   │
│ 3. Ask: Initialize factory? (y/n)                           │
│ 4. If yes: Copy factory-template/ to current directory      │
│ 5. Configure skill → factory path                           │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│ Result                                                       │
│                                                              │
│ ~/.config/opencode/skills/shopify-factory/  ← Skill files   │
│ /path/to/factory/                           ← Factory files │
│                                                              │
│ Ready to use! ✅                                             │
└─────────────────────────────────────────────────────────────┘

🔄 Migration

Move to New VPS

# On old VPS
tar -czf skill-backup.tar.gz ~/.config/opencode/skills/shopify-factory/
tar -czf factory-backup.tar.gz /path/to/factory/

# On new VPS
tar -xzf skill-backup.tar.gz -C ~/
tar -xzf factory-backup.tar.gz -C /new/location/
cd /new/location
# In AI agent: /shopify-setup

Change Factory Location

mv /old/path/factory /new/path/factory
cd /new/path/factory
# In AI agent: /shopify-setup

🎨 Features

1. Structured Workflow Enforcement

• Commands enforce correct pipeline order
• Gate validation at each phase
• Cannot skip steps

2. Fresh-Context Subagents

• Each phase spawns fresh subagent
• Prevents context rot
• Better quality output

3. Shopify Dev MCP Integration

• Mandatory Liquid validation
• Prevents hallucination
• Always uses latest Shopify docs

4. Buyer Journey Framework

• 6 business archetypes
• 7-stage buying journey
• All themes address full journey

5. State Tracking

• STATE.md per theme
• CONTEXT.md for locked decisions
• registry.json for all themes

6. Portable Architecture

• Dynamic path resolution
• Auto-detection
• Works across VPS/folders

📖 Documentation

After installation, you can access comprehensive documentation:

• Skill Documentation: ~/.config/opencode/skills/shopify-factory/SKILL.md
• Factory Documentation: /path/to/factory/AGENTS.md
• Operating System: /path/to/factory/SHOPIFY_THEME_FACTORY_OPERATING_SYSTEM.md
• Architecture: /path/to/factory/THEME_FACTORY_ARCHITECTURE.md
• Liquid Workflow: /path/to/factory/SHOPIFY_LIQUID_CREATION_WORKFLOW.md

Key Concepts

Buyer Journey Framework:

• 6 Business Archetypes (education-led, gift-decision, portfolio-proofing, editorial-lifestyle, expertise-trust, replenishment-routine)
• 7-Stage Buying Journey (awareness → interest → consideration → desire → decision → retention → advocacy)
• Every theme must address all stages

Gate Validation:

• Each phase has validation gates
• Cannot proceed without passing gates
• Ensures quality and completeness
• Prevents hallucination via Shopify Dev MCP

State Management:

• STATE.md - Current phase and progress per theme
• CONTEXT.md - Locked decisions and constraints
• registry.json - Master index of all themes

🔄 Migration & Portability

Move to New VPS

# Backup from old VPS
tar -czf shopify-factory-skill.tar.gz ~/.config/opencode/skills/shopify-factory/
tar -czf shopify-factory-data.tar.gz /path/to/factory/

# Restore on new VPS
tar -xzf shopify-factory-skill.tar.gz -C ~/
tar -xzf shopify-factory-data.tar.gz -C /new/location/
cd /new/location

# Reconfigure skill
/shopify-setup /new/location

Change Factory Location

# Move factory to new location
mv /old/path/factory /new/path/factory

# Update skill configuration
cd /new/path/factory
/shopify-setup

Multi-Environment Setup

# Development environment
/shopify-setup /dev/shopify-factory

# Production environment
/shopify-setup /prod/shopify-factory

# Same skill, different factories

🐛 Troubleshooting

Skill Not Found

# Check if skill is installed
ls ~/.config/opencode/skills/shopify-factory/

# Reinstall if missing
npx shopify-factory-skill@latest

Missing factory/, shared/, themes/, or automation/

If /shopify-scan says the workspace is not initialized, you are probably in an empty folder or a folder that only has the skill installed but no factory workspace yet. Fix it with:

/shopify-setup --init

The four operational folders are generated from the bundled factory-template/; you should not create them manually.

Factory Root Not Detected

# Manually set factory root
/shopify-setup /path/to/factory

# Or auto-detect
/shopify-setup

Permission Denied

# Fix permissions
chmod +x ~/.config/opencode/skills/shopify-factory/bin/shopify-factory.js

# Or reinstall
npm install -g shopify-factory-skill

Theme Check Errors

# Ensure Shopify CLI is installed
npm install -g @shopify/cli

# Verify authentication
shopify auth status

# Re-authenticate if needed
shopify auth login

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup

# Clone repository
git clone https://github.com/izestylusx/shopify-factory.git
cd shopify-factory

# Link locally for testing
npm link

# Test installer
shopify-factory

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• GitHub Repository: https://github.com/izestylusx/shopify-factory
• npm Package: https://www.npmjs.com/package/shopify-factory-skill
• Issue Tracker: https://github.com/izestylusx/shopify-factory/issues
• Shopify Dev MCP: https://shopify.dev/docs/api

🙏 Acknowledgments

• Inspired by GSD Framework
• Built for the Shopify developer community
• Powered by Shopify Dev MCP for anti-hallucination

📊 Stats

• 87 files in complete package
• 11 pre-built sections (theme-check validated)
• 5 pre-built snippets
• 15 document templates
• 9 automation scripts
• 6 business archetypes
• 7-stage buyer journey

Built with ❤️ for Shopify theme developers

Need help? Open an issue on GitHub