shopify-agentic-dev-workflow 0.1.0

package/docs/00-prerequisites.md

@@ -0,0 +1,88 @@
+# Prerequisites
+
+## Zero-to-working install (macOS)
+
+```bash
+# 1. Homebrew (if missing)
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+
+# 2. Node.js 18+ (required)
+brew install node
+
+# 3. Git (required)
+brew install git
+
+# 4. Shopify CLI 4.x (required)
+npm install -g @shopify/cli@latest
+
+# 5. GitHub CLI (optional — for pushing the repo)
+brew install gh
+
+# 6. This toolkit
+npm install -g github:sagarchauhan005/shopify-agentic-dev-workflow
+```
+
+## Windows
+
+- Node.js: https://nodejs.org (LTS installer)
+- Git: https://git-scm.com/download/win
+- Shopify CLI: `npm install -g @shopify/cli@latest` (run in PowerShell after Node install)
+- GitHub CLI: https://cli.github.com
+- Toolkit: `npm install -g github:sagarchauhan005/shopify-agentic-dev-workflow`
+
+## Linux (Ubuntu/Debian)
+
+```bash
+curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
+sudo apt-get install -y nodejs git
+npm install -g @shopify/cli@latest
+npm install -g github:sagarchauhan005/shopify-agentic-dev-workflow
+```
+
+## Verify
+
+```bash
+shopify-agent doctor
+# All rows should show OK
+```
+
+## Shopify access requirements
+
+Each developer needs **one** of:
+
+- Store owner access
+- Staff access with theme/app permissions
+- Collaborator access with theme/app permissions
+- **Theme Access token** (simplest for theme-only work — see below)
+
+### Theme Access token (recommended for theme work)
+
+The Theme Access token lets you run all theme commands without needing full Partners/staff login.
+
+1. In Shopify Admin → Online Store → Themes
+2. Install the [Theme Access app](https://apps.shopify.com/theme-access)
+3. Generate a password (one per developer, or one for CI)
+4. Enter it when `shopify-agent init` asks for a Theme Access token
+
+Store it as `SHOPIFY_CLI_THEME_TOKEN` in `.env` (never commit).
+
+## Auth model
+
+This toolkit supports two local auth modes:
+
+| Mode | How | Best for |
+|---|---|---|
+| Shopify CLI session | `shopify auth login` (browser OAuth) | Local dev with full Partners access |
+| Theme Access token | Password from Theme Access app | Theme-only work, CI, agencies |
+
+Shopify CLI stores its session internally. This toolkit invokes CLI commands and never reads or copies Shopify's internal tokens.
+
+## Codex MCP
+
+Install Shopify Dev MCP into Codex so it uses current Shopify docs and schemas:
+
+```bash
+shopify-agent mcp:install
+```
+
+Then restart Codex.

package/docs/01-onboarding.md

@@ -0,0 +1,111 @@
+# Developer Onboarding
+
+## First-Time Setup
+
+Clone the repo:
+
+```bash
+git clone <repo-url>
+cd <repo-folder>
+```
+
+Configure local values:
+
+```bash
+npm run setup
+```
+
+During setup:
+
+- Log in with Shopify CLI when prompted, or skip and run `npm run auth` later.
+- Enter the store domain.
+- Let the tool fetch themes.
+- Select a staging or unpublished theme.
+- Save the resulting local profile.
+
+Check the machine:
+
+```bash
+npm run doctor
+```
+
+Install Shopify Dev MCP for Codex:
+
+```bash
+npm run mcp:install
+```
+
+Restart Codex.
+
+## Authenticate Shopify CLI
+
+Preferred local path:
+
+```bash
+npm run auth
+```
+
+For browser login:
+
+```bash
+shopify theme info --store your-store.myshopify.com
+```
+
+For Theme Access token auth, put the token in `.env`:
+
+```bash
+SHOPIFY_CLI_THEME_TOKEN=...
+```
+
+## Validate Theme Access
+
+```bash
+npm run theme:list
+npm run theme:select
+npm run theme:pull
+npm run theme:check
+npm run theme:dev
+```
+
+## Profiles
+
+List profiles:
+
+```bash
+npm run profile:list
+```
+
+Switch profiles:
+
+```bash
+node ./bin/shopify-agent.js profile:use
+```
+
+Profiles let one developer switch between client stores, staging themes, and app configs without changing code.
+
+## Validate App Access
+
+From a Shopify app directory:
+
+```bash
+npm run app:dev
+```
+
+If the app is not inside this repo, run the underlying Shopify CLI command from the app repo:
+
+```bash
+shopify app dev
+```
+
+## First Codex Task
+
+Use `templates/prompts/theme-task.md` and replace the placeholders.
+
+Ask Codex to:
+
+- Inspect the current theme files.
+- Explain the files it will change.
+- Implement the smallest scoped change.
+- Run Theme Check.
+- Start local preview.
+- Use Browser QA for mobile and desktop.

package/docs/02-theme-sdlc.md

@@ -0,0 +1,106 @@
+# Theme SDLC
+
+## Default Rule
+
+Never write directly to the live theme first. Work against a staging/unpublished theme or a Shopify development theme.
+
+## Pull
+
+List and select the active theme first:
+
+```bash
+npm run theme:list
+npm run theme:select
+```
+
+```bash
+npm run theme:pull
+```
+
+Theme files are pulled into a unique folder:
+
+```text
+themes/<theme-name>-<theme-id>/
+```
+
+Do not pull theme files into the project root. Each theme folder includes `.shopify-theme.json` metadata so the CLI can detect if a folder belongs to a different store or theme.
+
+This uses:
+
+- `SHOPIFY_STORE`
+- `SHOPIFY_THEME_ID`
+- `SHOPIFY_CLI_THEME_TOKEN`
+
+If `SHOPIFY_CLI_THEME_TOKEN` is missing, Shopify CLI uses its logged-in local session.
+
+## Develop
+
+```bash
+npm run theme:dev
+```
+
+Use Codex to edit:
+
+- `sections/*.liquid`
+- `snippets/*.liquid`
+- `assets/*.css`
+- `assets/*.js`
+- `templates/*.json`
+- `config/settings_schema.json`
+
+Keep each theme's work inside its own folder. If a merchant duplicates a theme in Shopify, pull it as a separate folder and commit that snapshot before editing. Do not reuse a folder from another theme ID.
+
+## Validate
+
+```bash
+npm run theme:check
+```
+
+For visual QA, Codex should open the preview in Browser and inspect:
+
+- Home page.
+- Product page.
+- Collection page.
+- Cart.
+- Search.
+- Header/menu.
+- Mobile viewport.
+- Desktop viewport.
+
+## Push
+
+```bash
+npm run theme:push
+```
+
+Push only to the configured staging/unpublished theme.
+
+The worktree must be clean before pushing. Commit or stash changes first so the pushed code is traceable:
+
+```bash
+git add themes
+git commit -m "Describe the theme change"
+```
+
+## Publish
+
+Publishing requires an explicit environment variable:
+
+```bash
+CONFIRM_PUBLISH=yes npm run theme:publish
+```
+
+Before publishing, attach:
+
+- Files changed.
+- Theme Check result.
+- Desktop/mobile screenshots or notes.
+- Rollback theme id.
+
+## Rollback
+
+Rollback options:
+
+- Publish the previous theme from Shopify CLI.
+- Revert the Git commit and push again.
+- Restore from a duplicate theme.

package/docs/03-app-sdlc.md

@@ -0,0 +1,66 @@
+# App SDLC
+
+## App Creation
+
+For a new app:
+
+```bash
+shopify app init
+```
+
+For an existing app, keep app code in a normal Git repo and keep `shopify.app.toml` under review.
+
+## Local Development
+
+```bash
+shopify app dev
+```
+
+Shopify CLI handles the local preview, tunnel, app URL updates, and supported extension hot reload.
+
+## Extensions
+
+Generate extensions with:
+
+```bash
+shopify app generate extension
+```
+
+Use Codex with Shopify Dev MCP when creating:
+
+- Theme app extensions.
+- Admin UI extensions.
+- Checkout UI extensions.
+- Customer account extensions.
+- Shopify Functions.
+
+## Config
+
+Use `shopify.app.toml` and environment-specific files such as:
+
+- `shopify.app.dev.toml`
+- `shopify.app.staging.toml`
+- `shopify.app.production.toml`
+
+Validate config:
+
+```bash
+shopify app config validate
+```
+
+## Deploy
+
+```bash
+shopify app deploy
+```
+
+Important: `shopify app deploy` deploys app configuration and extensions. It does not deploy the web app server to Vercel, Cloud Run, Fly.io, or another hosting provider.
+
+## Logs
+
+```bash
+shopify app logs
+```
+
+Use logs during smoke tests after extension/app deploys.
+

package/docs/04-admin-api-ops.md

@@ -0,0 +1,58 @@
+# Admin API Operations
+
+## Recommended Boundary
+
+Use Shopify Admin GraphQL for store data and operations, but separate dev-store execution from production writes.
+
+Good Codex-driven operations:
+
+- Product audits.
+- SEO missing-field reports.
+- Metafield definition planning.
+- Collection analysis.
+- Inventory risk reports.
+- GraphQL query generation.
+- Dev-store mutation tests.
+
+Production writes need stronger controls:
+
+- Explicit human approval.
+- Dry-run report.
+- Mutation file committed to Git.
+- Backup/export where practical.
+- Rollback plan.
+
+## CLI Execution
+
+Run a GraphQL file against the configured store:
+
+```bash
+node ./bin/shopify-agent.js admin:query templates/graphql/shop-query.graphql
+```
+
+Shopify CLI `app execute` supports Admin GraphQL execution. Treat mutations as development-store only unless Shopify changes the CLI behavior and your team approves a production-write policy.
+
+The wrapper adapts to different Shopify CLI versions. Some versions accept `--query-file` and `--version`; older versions only accept `--query`. The toolkit detects the installed command help and uses the supported path.
+
+## Custom Admin Bridge
+
+For production automation, build a small internal app/API bridge instead of giving Codex unbounded store control.
+
+Minimum features:
+
+- Uses Shopify GraphQL Admin API.
+- Uses least-privilege scopes.
+- Has allowlisted operations.
+- Requires a dry-run mode.
+- Requires approval for mutations.
+- Logs actor, request, response, and rollback metadata.
+- Supports rate-limit backoff.
+
+Suggested MCP/tool split:
+
+- `shopify-products-admin`
+- `shopify-orders-admin`
+- `shopify-inventory-admin`
+- `shopify-content-admin`
+
+Smaller tool surfaces reduce accidental tool selection.

package/docs/05-codex-prompts.md

@@ -0,0 +1,37 @@
+# Codex Prompt Playbook
+
+## Theme Task
+
+Use:
+
+```text
+Use Shopify Dev MCP if available. Inspect the theme structure first. Implement only the requested change. Run Theme Check. Start Shopify theme dev if needed. Verify desktop and mobile with Browser. Do not publish.
+
+Task:
+<describe task>
+
+Acceptance criteria:
+<list criteria>
+```
+
+## Liquid Review
+
+```text
+Review this Shopify theme change for Liquid syntax, section schema correctness, accessibility, responsiveness, and performance. Prioritize findings with file and line references. Do not refactor unless needed to fix a bug.
+```
+
+## Admin GraphQL Draft
+
+```text
+Use Shopify Dev MCP to inspect the current Admin GraphQL schema. Generate a read-only query first. Validate scopes needed. Do not create a mutation until I approve the dry-run output.
+
+Goal:
+<describe store operation>
+```
+
+## Production Mutation Review
+
+```text
+Review this Admin GraphQL mutation for production risk. Identify required scopes, affected resource count, rate-limit concerns, rollback plan, and dry-run checks. Do not execute it.
+```
+

package/docs/06-security-guardrails.md

@@ -0,0 +1,47 @@
+# Security Guardrails
+
+## Secrets
+
+Never commit:
+
+- `.env`
+- Theme Access passwords
+- Admin API access tokens
+- Client secrets
+- Refresh tokens
+- Private app credentials
+
+Use:
+
+- GitHub Actions secrets.
+- 1Password, Bitwarden, Doppler, or another team secret manager.
+- Separate credentials for local dev and CI.
+
+## Access Scopes
+
+Use least privilege:
+
+- Theme developer: theme scopes only.
+- Product operator: product scopes only.
+- Order operator: order scopes only.
+- Inventory operator: inventory scopes only.
+
+Avoid full store scopes for daily agentic workflows.
+
+## Production Writes
+
+Production writes require:
+
+- Explicit approval.
+- Dry-run report.
+- Mutation file in Git.
+- Resource count.
+- Rollback plan.
+- Post-run audit.
+
+## Browser Automation
+
+Use Browser/Chrome/Computer Use only when CLI/API paths cannot do the job.
+
+Do not automate payment, password, or customer-sensitive workflows without explicit approval.
+

package/docs/07-github-rollout.md

@@ -0,0 +1,30 @@
+# GitHub Rollout
+
+## Create Repo
+
+With GitHub CLI:
+
+```bash
+git init
+git add .
+git commit -m "Initial Shopify agentic workflow toolkit"
+gh repo create shopify-agentic-dev-workflow --private --source=. --remote=origin --push
+```
+
+## Team Setup
+
+Add branch protections:
+
+- Require PR review.
+- Require status checks for Theme Check.
+- Require signed or linear commits if your team uses them.
+- Restrict direct pushes to `main`.
+
+Add repository secrets:
+
+- `SHOPIFY_FLAG_STORE`
+- `SHOPIFY_CLI_THEME_TOKEN`
+- `SHOPIFY_STAGING_THEME_ID`
+
+Do not store production Admin API write tokens unless you have a formal approval workflow.
+