Shopify Virtual Agent Team

A virtual agency team of AI agents for Shopify store builds, migrations, and ongoing support. Built for Claude Code.

The Team

Core Shopify Agents

Agent	Role	What They Do
Orchestrator	Coordinator	Manages workflows, enforces quality gates, tracks progress
Zuri	Config & Setup	Store settings, shipping, payments, redirects, metaobjects
Nasir	Content & Data	Product import, collections, metafields, pages, media
Morgan	Theme Build	Coordinates theme agents, Liquid/CSS/JS, bug fixes, design tokens
Alex	QA	Smoke tests, link checks, responsive, pagespeed, accessibility
Nia	Reporting	SEO audits, launch checklists, handoff docs, status reports

Theme Specialists (coordinated by Morgan)

Agent	Role	What They Do
Rick	Theme Architect	Figma design → section/block/snippet architecture plans
Yuriy	Liquid Developer	Architecture plans → production Liquid code
Roy	Asset Manager	Figma export → Shopify Files upload → template JSON injection
Rob	Theme Deployer	Push theme files to Shopify stores (GitHub, CLI, or REST API)

Audit & Remediation

Agent	Role	What They Do
Tiffany	Figma Design Auditor	Compares Figma designs with live sites, identifies visual discrepancies
Jules	Accessibility Auditor	WCAG compliance audits, ARIA analysis, a11y best practices
Ja	QA Remediator	Surgical code fixes for audit findings (design, a11y, performance)

General Engineering

Agent	Role	What They Do
Hal	Optimization Architect	API performance shadow-testing, cost/security guardrails
Cindy	Frontend Developer	React/Vue/Angular, UI implementation, performance optimization
Cas	Backend Architect	System design, database architecture, API development
Justin	Fullstack Scaffolder	Translates plans/specs into scaffolded project codebases

Quick Start

# Clone the repo
git clone https://github.com/your-org/barrel-virtual.git
cd barrel-virtual

# Preview what will be installed
./install.sh

# Install agents + skills globally
./install.sh --install

This copies agents, skills, and observations to ~/.claude/, making them available in all Claude Code sessions.

Usage

Start a new store build

> Use the shopify-orchestrator to kick off a new store build for Acme Co.
> Here's the project brief: [paste or attach brief]

Use individual agents

> Use zuri to set up shipping zones for US, Canada, and UK with flat rates.
> Use nasir to import products from products.csv.
> Use morgan to fix the broken image grid on the product page.
> Use alex to run a full QA pass on staging.myshopify.com.
> Use nia to generate a pre-launch checklist.

Project Structure

barrel-virtual/
├── agents/                    # Agent definitions (→ ~/.claude/agents/)
│   ├── barrel-shopify-orchestrator.md
│   ├── zuri-shopify-config.md
│   ├── nasir-content-updating-specialist.md
│   ├── morgan-engineering-shopify-theme-developer.md
│   ├── alex-qa-expert.md
│   ├── nia-reporting-data-ops-specialist.md
│   ├── rick-engineering-shopify-theme-architect.md
│   ├── yuriy-engineering-shopify-liquid-developer.md
│   ├── roy-engineering-shopify-asset-manager.md
│   ├── rob-enigneering-shopify-theme-deployer.md
│   ├── tiffany-figma-design-auditor.md
│   ├── jules-accessibility-auditor.md
│   ├── ja-engineering-qa-remediator.md
│   ├── hal-engineering-autonomous-optimization-architect.md
│   ├── cindy-engineering-frontend-developer.md
│   ├── cas-engineering-backend-architect.md
│   └── justin-fullstack-scaffolder.md
├── skills/                    # Skill references (→ ~/.claude/skills/)
│   ├── store-settings/
│   ├── product-import/
│   ├── section-builder/
│   ├── playwright-smoke/
│   ├── seo-audit/
│   ├── launch-checklist/
│   ├── plan-first/            # Workflow: plan → approve → implement → QA
│   ├── shopify-qa/           # Workflow: local + Figma visual QA
│   ├── retainer-release/     # Workflow: retainer release/deploy process
│   └── ... (23 skills total)
├── observations/              # Established patterns (→ ~/.claude/observations/)
│   └── shopify-patterns.md    # Distilled lessons from past builds
├── orchestration/             # Workflow docs (stay in repo)
│   ├── workflows.md
│   ├── access-tiers.md
│   └── handoff-templates.md
├── mcp/                       # MCP server configs
│   ├── README.md
│   ├── global-mcp-servers.json
│   └── project-mcp-servers.json
├── templates/
│   └── project-claude.md      # Template CLAUDE.md for client projects
├── CLAUDE.md                  # Project instructions for Claude Code
├── install.sh                 # Installer script
├── sync-check.sh              # Drift detection between project and ~/.claude/
└── shopify-agent-team.md      # Original spec

Access Tiers

Tier	Rule	Examples
Autonomous	Execute freely	Read APIs, run tests, generate reports
Notify	Show plan, wait for approval	Create products, modify theme, write metafields
Gate	Requires PM approval	Deploy to production, go live, DNS changes

MCP Servers

Agents leverage MCP (Model Context Protocol) servers for direct tool access to external services:

MCP	What It Does	Used By
@shopify/dev-mcp	Shopify docs search, API schemas, Theme Check	All agents
shopify-mcp	70+ Admin API tools (products, orders, metafields, redirects)	Zuri, Nasir, Nia
@playwright/mcp	Browser automation via accessibility tree	Alex, Nia
pagespeed-insights-mcp	Lighthouse scores, Core Web Vitals	Alex, Nia
shopify-liquid-mcp	Offline Liquid reference (198 pages, <1ms search)	Morgan, Yuriy
Figma MCP	Design-to-code pipeline, screenshots	Morgan, Rick, Roy, Tiffany

Global MCPs (store-agnostic) are merged into ~/.claude/mcp_servers.json by the installer. Per-project MCPs (store-specific, like shopify-mcp) go in <project>/.claude/mcp_servers.json with credentials from .env.

See mcp/README.md for setup details.

Agent Workflow

Morgan coordinates the theme specialist agents for end-to-end section builds:

Figma Design
    ↓
Rick (Architect) → section/block/snippet plan
    ↓                (includes existing theme conventions)
Yuriy (Liquid Dev) → production Liquid/CSS/JS code
    ↓                  (scans existing sections for conventions first)
Roy (Asset Manager) → Figma export → Shopify Files upload
    ↓
Rob (Deployer) → push to staging theme
    ↓
Tiffany (Design Audit) → compare deployed vs Figma     ← MANDATORY
    ↓ DISCREPANCIES?
Ja (Remediator) → surgical fixes → Tiffany re-audits
    ↓
Alex (QA) → smoke tests, links, responsive, pagespeed,
             accessibility, theme convention check
    ↓ FAIL?
Morgan → fixes → re-QA
    ↓ PASS
Nia (Reporting) → launch checklist → 🔴 Go Live gate

All agents involved in theme builds consult observations/shopify-patterns.md before starting work. This file contains distilled patterns from past builds that prevent known failure modes (e.g., missing width classes, incorrect padding placement on full-width sections).

Keeping Agents in Sync

Agents may be edited in ~/.claude/agents/ during build sessions. Use sync-check.sh to detect and reconcile drift:

# Show what's out of sync (dry run)
./sync-check.sh

# Pull changes from ~/.claude/ into the project (after builds modify agents)
./sync-check.sh --pull

# Push project changes to ~/.claude/ (after committing edits here)
./sync-check.sh --push

Recommended workflow: Edit agents here → commit → ./sync-check.sh --push. If agents were modified during a build, run ./sync-check.sh --pull → review → commit.

Observations

The observations/ directory contains validated patterns from past builds. These are referenced by agents via a "Required Reading" section and installed to ~/.claude/observations/ by the installer.

Pattern promotion flow:

1. A build reveals a failure or anti-pattern
2. Log the raw observation in ~/.claude/agent-observations.md or ~/.claude/shopify-observations.md
3. Once validated, distill the pattern into observations/shopify-patterns.md
4. If the pattern requires an agent behavior change, update the relevant agent file in agents/
5. Run ./sync-check.sh --push to deploy changes

Setting Up a Client Project

1. Copy templates/project-claude.md to <client-project>/.claude/CLAUDE.md
2. Fill in store credentials, Figma keys, and project context
3. Create a .env file with sensitive credentials (never commit)
4. Start with the orchestrator or use individual agents as needed

Workflows

See orchestration/workflows.md for detailed workflow diagrams covering:

1. New Store Build — setup → content → theme → QA → launch
2. Platform Migration — redirects → import → theme adjust → QA → SEO verify
3. Post-Launch Support — fix → QA → deploy per ticket

Workflow Skills

Three process skills (vendored from barrel/claude-skills) drive multi-step engineering workflows and trigger proactively from their frontmatter description:

Skill	Trigger	What it does
plan-first	"implement", "build", "add feature", "refactor" on non-trivial work	Gates implementation behind a saved plans/<task>.md and explicit approval, then implements, auto-runs QA, and captures lessons.
shopify-qa	"QA", "compare to Figma", "verify", after a theme change	Read-only visual QA of a theme change on the local dev server, optionally diffed against a Figma design. Never pushes or commits.
retainer-release	"release", "deploy", "bump version", or RET-### ticket IDs	Runs the retainer release process — release branches, ticket merges/cherry-picks, version bump, changelog, asset build, deploy to live.

plan-first and shopify-qa compose: plan-first's implement phase auto-invokes shopify-qa, picking up any ## Figma Reference recorded in the plan. plan-first also keeps cross-project memory in ~/.claude/skills/plan-first/LESSONS.md and PLAN_LOG.md.

Note: shopify-qa's dev-server port detection reads /proc, so it assumes a Linux runtime; on macOS it falls back to port 9292.

Subagents vs Agent Teams

This project currently uses subagents — the orchestrator spawns agents within a single Claude Code session via the Agent tool. This is stable and works today with no special flags.

Claude Code also has an experimental Agent Teams feature where agents run as independent sessions that coordinate via a shared task list and direct messaging. This is a separate capability that may be valuable as it matures.

Comparison

	Subagents (current)	Agent Teams (experimental)
How agents run	Spawned within orchestrator's session	Independent terminal sessions
Parallelism	Sequential or background subagents	True parallel (separate processes)
Communication	Agent returns result to parent	Shared task list + direct messages
Context	Orchestrator sees all agent output	Each agent has its own context window
Quality gates	Orchestrator enforces inline	Agents self-coordinate; gates need task-list conventions
Access tier enforcement	Parent controls what agents do	Each session has its own permissions
Flag required	None	CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
Status	Stable	Experimental (known limitations)

What changes with Agent Teams

If you switch to agent teams, almost everything stays the same:

Stays the same (no changes):

• All 17 agent definitions (agents/*.md)
• All 23 skills (skills/*/SKILL.md)
• MCP server configurations (mcp/)
• Access tier definitions
• Per-project setup (CLAUDE.md, .env)

What changes:

1. Enable the flag — add to ~/.claude/settings.json:

   {
     "env": {
       "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
     }
   }

2. Orchestrator coordination model — instead of spawning subagents via the Agent tool, the orchestrator would create tasks on a shared task list that teammate agents pick up. The orchestrator agent definition would need updates to use task-based coordination instead of direct agent spawning.

3. Access tier enforcement — with subagents, the orchestrator controls everything and can gate operations before they happen. With agent teams, each agent runs independently, so access tiers would need to be enforced within each agent's own definition (they already are — each agent has its tier documented) rather than by the orchestrator intercepting actions.

4. Handoffs — instead of passing context via the Agent tool's prompt, agents would communicate through the shared task list or direct messages. The handoff templates in orchestration/handoff-templates.md would be used as task descriptions.

When to consider Agent Teams

Agent teams would add value for:

• Large store builds where Zuri (config) and Nasir (content) genuinely benefit from running in parallel across separate terminals
• Long-running QA passes where Alex runs a full test suite while Morgan continues theme work
• Multi-store operations where different agents work on different client stores simultaneously

Current limitations (experimental)

As of March 2026, agent teams have these known limitations:

• No session resumption while teammates are in-progress
• Task status can lag behind actual completion
• Slow shutdown when stopping a team
• Split-pane mode requires tmux or iTerm2

We recommend staying with subagents until these stabilize, then testing agent teams on a non-critical project first.