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 to ~/.claude/agents/ and skills to ~/.claude/skills/, 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  # Workflow coordinator
│   ├── zuri-shopify-config.md          # Config & Setup
│   ├── nasir-content-updating-specialist.md  # Content & Data
│   ├── morgan-engineering-shopify-theme-developer.md  # Theme Build
│   ├── alex-qa-expert.md               # QA
│   ├── nia-reporting-data-ops-specialist.md  # Reporting
│   ├── rick-engineering-shopify-theme-architect.md   # Theme Architect
│   ├── yuriy-engineering-shopify-liquid-developer.md # Liquid Developer
│   ├── roy-engineering-shopify-asset-manager.md      # Asset Manager
│   ├── rob-enigneering-shopify-theme-deployer.md     # Theme Deployer
│   ├── tiffany-figma-design-auditor.md  # Figma Design Auditor
│   ├── jules-accessibility-auditor.md   # Accessibility Auditor
│   ├── ja-engineering-qa-remediator.md  # QA Remediator
│   ├── hal-engineering-autonomous-optimization-architect.md  # Optimization
│   ├── cindy-engineering-frontend-developer.md  # Frontend Developer
│   ├── cas-engineering-backend-architect.md      # Backend Architect
│   └── justin-fullstack-scaffolder.md            # Fullstack Scaffolder
├── skills/                    # Skill references (→ ~/.claude/skills/)
│   ├── store-settings/
│   ├── product-import/
│   ├── section-builder/
│   ├── playwright-smoke/
│   ├── seo-audit/
│   ├── launch-checklist/
│   └── ... (20 skills total)
├── orchestration/             # Workflow docs (stay in repo)
│   ├── workflows.md           # New Build, Migration, Post-Launch flows
│   ├── access-tiers.md        # Autonomous / Notify / Gate definitions
│   └── handoff-templates.md   # Agent-to-agent, QA, gate request templates
├── mcp/                       # MCP server configs
│   ├── README.md              # Setup guide for all MCPs
│   ├── global-mcp-servers.json  # Global MCPs (→ ~/.claude/mcp_servers.json)
│   └── project-mcp-servers.json # Per-project template (→ <project>/.claude/)
├── templates/
│   └── project-claude.md      # Template CLAUDE.md for client projects
├── install.sh                 # Installer script
└── 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
    ↓
Yuriy (Liquid Dev) → production Liquid/CSS/JS code
    ↓
Roy (Asset Manager) → Figma export → Shopify Files upload
    ↓
Rob (Deployer) → push to staging theme
    ↓
Alex (QA) ← Tiffany (design audit) + Jules (a11y audit)
    ↓ FAIL?
Ja (Remediator) → surgical fixes → re-QA
    ↓ PASS
Nia (Reporting) → launch checklist → 🔴 Go Live gate

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

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 20 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.