Shopify Storefront Integration — Agent Guide

Instructions for agents working on Shopify storefront integrations. This is the single source of truth for how integration work is structured, coordinated, and verified.

For the overall system architecture, see automation-architecture.md (historical design doc — this file is the operational truth).

What to read for your role

This file is long; most roles need only a few sections. Read your row, skip the rest (use Grep to jump to a section heading):

Role	Read these sections
Team lead	All of it (once per session)
css-implementer	Two "workspaces"; Workflow A; Escalation Model; CSS Architecture Reference
css-verifier	Nothing required — your agent definition embeds the selectors, viewports, and checklist. Consult Verification Standards only if your definition lacks something.
finisher	Workflow A-Review (incl. collation order); cross-section checks are embedded in your definition
code-implementer	Two "workspaces"; Escalation Model; Third-Party App Integration (your app's guide ONLY — the lead passes it)
code-verifier	Nothing required — checklist + severity rubric are embedded in your definition
search-tuner / search-verifier	Two "workspaces"; Escalation Model. Override-header mechanics are in your definitions.
qc-investigator	Two "workspaces"; Escalation Model; Tooling Reference

Two "workspaces" — keep them distinct

This skill has TWO concepts of "where work happens." They are different and the distinction matters; conflating them is a known footgun.

Concept	Path	Scope	Used for
Worktree	.claude/worktrees/ (one per teammate)	PRIVATE to each teammate. Team spawns are NOT auto-isolated (isolation: "worktree" is ignored for them — harness fact, see "How to spawn a teammate"); implementer teammates SELF-PROVISION via git worktree add. Transient spawns with the flag are auto-isolated.	Editing code, branches, commits, pushes. Git state, period.
Shared workspace	tmp/integrations/<shop-slug>/ (one per integration)	SHARED across lead and every teammate	CSS outputs, screenshots, escalations, reports — the artifact channel

Throughout this skill and every agent definition (.claude/agents/<role>.md), the placeholder ${SHARED_WORKSPACE} refers to the second one — the shared artifact directory.

Shared workspace contract

All integration artifacts are namespaced under tmp/integrations/<shop-slug>/ to avoid collisions between parallel or sequential integrations. The lead creates it at session start and records its absolute path:

SHARED_WORKSPACE="$(pwd)/tmp/integrations/<shop-slug>"

Structure inside ${SHARED_WORKSPACE}:

tmp/integrations/muji-us/
├── css/cards.css, filters.css, ...     # CSS output per section
├── screenshots/cards-1440.png, ...     # Native theme screenshots
├── screenshots/final-cards-1440.png    # Finisher verification screenshots
├── escalations/cards.json, okendo.json # Escalation files (all task types)
├── decisions/quickshop-modal.json      # /grill-me decision records
└── verification-report.json            # Finisher pass/fail report

The lead passes SHARED_WORKSPACE=<absolute-path> in every teammate's spawn prompt. Agent definitions consistently reference ${SHARED_WORKSPACE}/... for every artifact path, so the placeholder resolves to the lead's repo workspace at runtime — same physical files on disk for lead and every teammate. No copies, no syncing. Concurrent-write safety comes from convention: each teammate owns its own filenames (cards owns css/cards.css, filters owns css/filters.css, etc.).

Why this matters now: without the absolute path, a teammate's worktree has its own private tmp/ (gitignored). A relative tmp/integrations/<slug> in the teammate's cwd resolves to a SEPARATE directory the lead can't see — COLLATE and escalation reads silently fail. The absolute-path contract is what keeps the shared workspace shared across worktree isolation.

tmp/work/<slug>/ for non-merchant general-dev work

Non-Shopify workflows (refactors, infra changes, library updates — anything driven by the general-feature-pr skill) use the parallel root tmp/work/<slug>/ instead of tmp/integrations/<slug>/. Hook scripts (task-completed.sh, task-created.sh, teammate-idle.sh) walk both roots via the shared resolve_workspace helper in .claude/hooks/_lib.sh, so escalation gates and idle-nudge checks fire from either location. Pick tmp/work/ for non-merchant slugs (e.g. tmp/work/ecs-bulk-sync/); pick tmp/integrations/ for actual Shopify merchants (e.g. tmp/integrations/muji-us/). When both exist for the same slug, tmp/work/ wins — but in practice slugs should not collide between the two roots.

---

How Integration Work is Organized

All integration work uses an agent team. The coordinator (your session or the team lead) spawns teammates, each running a deterministic workflow for their assigned section.

  /integrate-storefront <shop>
  |
  | Lead determines scope:
  |   Full setup  -> 4 teammates (cards, filters, paging, heading)
  |   Tweak       -> 1 teammate (specific section)
  |   Integration -> 1 teammate (Workflow B)
  |   Tuning      -> 1 teammate (Workflow C)
  |
  | Each teammate runs a workflow for their section
  | Lead handles escalations, collates outputs, gates prod changes

---

Tooling Shapes: Workflows, Subagents, Teammates

Three orchestration primitives. Pick the right one or the work breaks.

Primitive	How invoked	Lifetime	Messaging	Use for
Workflow	Workflow({name, args})	Deterministic script runs to completion	None — script orchestrates	A scripted implement→verify→iterate loop inside one role. Teammates run workflows themselves.
Subagent	Agent({subagent_type, prompt, ...}) (no team_name)	One turn — runs, returns, dies	None	One-shot research, lookups, focused exploration where only the result matters.
Teammate	Agent({team_name, name, subagent_type, isolation: "worktree", prompt, ...})	Persistent — alive for the team's lifetime	SendMessage({to: "<name>", ...}) — both ways	Long-running roles (CSS implementer, code implementer, finisher, search tuner) that iterate, receive feedback, follow up on PR review, verify post-deploy.

How to spawn a teammate

1. Create the team first (one team per integration session):

   TeamCreate({team_name: "<shop-slug>-integration", description: "..."})

2. Spawn each teammate with team_name, name, subagent_type, AND isolation: "worktree". The name is the SendMessage address; the subagent_type is the agent definition under .claude/agents/<name>.md. Keep passing isolation: "worktree" (correct intent), but the harness currently IGNORES it for team spawns — teammates run in the lead's cwd regardless (verified 2026-06-10/11; the agent-teams docs define no teammate isolation). Real isolation comes from the spawn-prompt directive that the teammate self-provision a worktree (git worktree add .claude/worktrees/<your-name> -b <branch>) before any git work.

   Pass SHARED_WORKSPACE=<absolute-path> in every spawn prompt so the teammate's agent-definition references to ${SHARED_WORKSPACE}/... resolve to the lead's repo workspace (see "Shared workspace contract" above).

   Agent({
     team_name: "<shop-slug>-integration",
     name: "cards",
     subagent_type: "css-implementer",
     isolation: "worktree",
     description: "CSS for product cards",
     prompt: `
       SHARED_WORKSPACE=${SHARED_WORKSPACE}    # absolute path from Phase 1.1
   
       <role-specific brief follows>
     `,
     run_in_background: true
   })

   Why per-teammate worktrees matter. A teammate without its own worktree runs in the lead's cwd on the lead's current branch. When a second teammate starts git work, it switches the shared cwd to its own branch, resetting the first teammate's working tree mid-edit. Stashes accumulate, commits land on wrong branches, pre-commit hooks shuffle files between teammates. With a self-provisioned worktree, each teammate gets its own git working directory under .claude/worktrees/ backed by the same .git — checkout, stash, commit, push independently. The lead cleans up with git worktree remove <path> after merge.

   Why the absolute ${SHARED_WORKSPACE} matters. The worktree shares git state but nothing else — tmp/ is gitignored, so each worktree gets its own private tmp/. A relative tmp/integrations/<slug>/css/cards.css in the teammate's cwd resolves to a separate directory the lead can't see; COLLATE and escalation reads silently fail. Setting ${SHARED_WORKSPACE} to the absolute path the lead recorded in Phase 1.1 makes every artifact reference in the agent definitions land on the same physical files on disk.

3. Message the teammate by name when you have feedback, scope changes, or want them to verify after deploy. They go idle between turns but resume on message.

4. Cleanup: send each teammate a shutdown_request via SendMessage, then the team is torn down.

Workflow ownership

Workflows in this skill set (feature-pr, css-section, search-tuning) were designed to be invoked by the teammate — but teammates do NOT have the Workflow tool (harness restriction, verified 2026-06-10/11), so in team contexts the implement/verify loop runs hub-and-spoke instead (see Canonical Loop below). Only the lead or a plain non-team session can invoke a workflow, and a lead-invoked run is detached from any persistent teammate: you lose the ability to follow up on PR review comments, post-deploy verification, etc. The right mental model: spawn the teammate for anything with a future and run hub-and-spoke; reserve direct workflow invocation for genuinely detached one-off work.

Canonical Loop: inline-iterate is the default

The teammate's default loop for feature/integration code work is NOT the full Workflow. It is:

1. Implement inline — the teammate writes code in its own worktree.
2. Spawn an independent reviewer subagent — Agent without team_name, fresh context, one turn. Pass the diff + spec + project gates from /docs/dev/orchestration/code-review-guide.md.
3. Iterate up to 3 rounds with fresh reviewer subagents each round.
4. /raise + /monitor-pr as today (teammate-owned).

Harness reality (verified 2026-06-10/11): team-spawned teammates have NO Agent and NO Workflow tools, and isolation: "worktree" is not applied to them (per the agent-teams docs, teammates share the project directory and only the lead spawns agents — intended behavior, not a bug). Working protocol: teammates self-provision a worktree before any git work (item 1 of the loop in code-implementer.md §3 "Implement + Review") and route reviews through the LEAD (hub-and-spoke — see the integrate-storefront SKILL "Canonical Loop"), who spawns the reviewer and relays the verdict. Reviewers must SendMessage their verdicts — their final text is invisible to the spawner.

The full Workflow remains available and should be invoked when the work genuinely needs the script's rigidity (by non-team sessions — teammates lack the Workflow tool): multi-section parallel fan-out (CSS), repeated tuning rounds with hard ratchet (search-tuning), or where the script's max-rounds bound is what you actually want.

For the full pattern taxonomy (A workflow / B inline-iterate / C pair-driven / D persistent reviewer / E B→D mode-switch), see /docs/dev/orchestration/iteration-patterns.md.

---

Universal Work Unit

Every task — CSS, features, search tuning — follows the same phases:

1. CLARIFY — define the problem, element selector, reference screenshot
2. PLAN — write the CSS/code change description, scope estimate
3. GATE — auto-approve if specific and scoped; /grill-me if vague or novel
4. IMPLEMENT — implementor agent writes CSS or code
5. VERIFY — verifier agent (separate from implementor) checks the work
6. ITERATE — workflow script passes verifier feedback to implementor, max 3 rounds
7. OUTPUT — CSS candidate, raised PR, config diff, or gap report

The implementor and verifier are always separate agents with separate definitions, tools, and prompts. The implementor never verifies its own work. The verifier never writes implementation code.

The workflow script orchestrates the handoff between them: implementor produces output → verifier evaluates → if fail, script passes feedback back to implementor → repeat.

---

Agent Role Definitions

All agent roles are defined as subagent definitions in .claude/agents/. Each definition specifies the role's tools, model, and instructions. The workflow script composes them.

Role architecture

  .claude/agents/
  +-- css-implementer.md         # Writes CSS based on design spec
  +-- css-verifier.md            # Evaluates CSS against native theme
  +-- code-implementer.md        # Writes code for integrations/features
  +-- code-verifier.md           # Reviews code quality, tests, CLAUDE.md compliance
  +-- search-tuner.md            # Builds config overrides
  +-- search-verifier.md         # Validates search result ordering
  +-- finisher.md                # Full CSS cross-check after collation

What each definition contains

# .claude/agents/<role>.md frontmatter
---
name: <role-name>
description: <one-line description>
model: claude-opus-4-6
tools:
  - <allowed tools for this role>
---

# Body: role-specific instructions
- What this agent does
- Steps to follow
- Checklist to verify/optimize against
- What it outputs
- What it CANNOT do

Implementor vs verifier separation

  +---------------------------+---------------------------+
  | Implementor               | Verifier                  |
  +---------------------------+---------------------------+
  | Writes CSS / code         | NEVER writes impl code    |
  | Knows the design spec     | Knows the acceptance      |
  |                           | criteria / checklist       |
  | Has: write tools,         | Has: browser tools,       |
  |   browser for inspection  |   screenshot tools        |
  | Does NOT: evaluate its    | Does NOT: fix issues —    |
  |   own output              |   only describes them     |
  +---------------------------+---------------------------+

  Workflow script composes them:

  for (i = 0; i < 3; i++):
    output = implementor({ spec, previousFeedback })
    result = verifier({ output, acceptanceCriteria })
    if (result.pass): break
    previousFeedback = result.feedback

Current role definitions

Role	Workflow	Tools	Checklist
css-implementer	A	Read, Write, Edit, Grep, Glob, Bash, browserN (inspect native)	Write Layer 3 CSS matching native theme tokens
css-verifier	A	browserN (inject CSS, screenshot, compare)	Font, color, spacing, layout, hover states match native
code-implementer	B	Read, Write, Edit, Grep, Glob, Bash, browserN	Write code changes, run tests
code-verifier	B	Read, Grep, Glob, Bash, browserN	Code quality, CLAUDE.md compliance, test coverage, no side effects
search-tuner	C	Bash (curl for search queries)	Build override JSON, test with header
search-verifier	C	Bash (curl for search queries)	Result ordering matches expectations, no regressions
finisher	A-Review	browserN (inject full CSS, screenshot all elements)	All sections pass, no cross-section conflicts

These are the starting definitions. New roles can be added for future workflows (e.g., accessibility-verifier, performance-verifier, mobile-verifier).

---

Parallel Playwright Browsers

Each teammate gets an exclusive browser instance via .mcp.json:

Teammate	Browser tools	Use ONLY these
cards	mcp__browser1__*	mcp__browser1__browser_navigate, mcp__browser1__browser_take_screenshot, etc.
filters	mcp__browser2__*	mcp__browser2__browser_navigate, mcp__browser2__browser_take_screenshot, etc.
paging	mcp__browser3__*	mcp__browser3__browser_navigate, mcp__browser3__browser_take_screenshot, etc.
heading	mcp__browser4__*	mcp__browser4__browser_navigate, mcp__browser4__browser_take_screenshot, etc.
finisher	whichever is free	Implementation teammates are done by this point

The coordinator (lead) uses the Playwright plugin (mcp__plugin_playwright_playwright__*) for interactive work with the human.

Rules:

• NEVER use another teammate's browser tools
• Call browser_close when your workflow completes
• If you see a SingletonLock error, remove the lock file — do NOT kill Chrome processes

---

Workflow A: CSS (Single Section)

Each CSS teammate runs this workflow for their assigned section. The workflow script controls the iteration; the agent does the creative work.

Input (from team lead via task)

• Section name: cards, filters, paging, or heading
• Assigned browser: mcp__browserN__*
• Merchant doc path: docs/integrations/<shop>.md
• Native theme URL: https://<store>.com/?preview_theme_id=<published_theme_id>
• Marqo theme URL: https://<store>.com/?preview_theme_id=<marqo_theme_id>
• Current settings backup: tmp/<shop>_settings_<timestamp>.json

Steps (orchestrated by workflow script)

Step 1: Inspect native theme (implementor agent)

Navigate to the native theme URL using assigned browser. Screenshot the specific element(s) for the section (see Verification Standards). Extract design tokens (fonts, colors, spacing) using browser_evaluate with getComputedStyle().

Step 2: Implement (implementor agent)

Write CSS targeting Layer 3 (custom_css.value.css). Follow the three-layer architecture:

• Layer 1 (CSS Variables) — auto-generated, don't touch
• Layer 2 (Template CSS) — shared defaults, don't touch
• Layer 3 (Custom CSS) — your target. Highest priority, per-merchant overrides.

Use the CSS customization guide for patterns and the existing Muji or MSQC docs as references.

Log escalations for any features that can't be replicated with CSS (review stars, wishlist buttons, custom badges, etc.). See Escalation Model.

Step 3: Verify (verifier agent — separate from implementor)

The verifier is a different agent with a different prompt and checklist. It receives the implementor's CSS output and the native theme reference.

1. Inject the CSS into the Marqo theme preview page via browser_evaluate:

// Inject CSS via browser_evaluate on assigned browserN
document.head.insertAdjacentHTML('beforeend',
  '<style id="marqo-test-css">' + cssText + '</style>');

2. Screenshot the target element(s) on both native and Marqo themes
3. Compare against the verifier's checklist (font, color, spacing, layout, hover states)
4. Report pass or fail with specific gap descriptions

The verifier does NOT fix issues — it only describes them. The CSS is NOT pushed to the settings API — it stays local to the browser session.

Step 4: Iterate (workflow script orchestrates)

If the verifier reports fail, the workflow script:

1. Passes the verifier's feedback to the implementor agent
2. Implementor writes updated CSS
3. Verifier agent evaluates again (clean browser — remove old <style> first)

Max 3 rounds. After that, the gap is logged and escalated to the lead.

Output

Write these files (the TaskCompleted hook validates they exist):

1. CSS output: ${SHARED_WORKSPACE}/css/<section>.css (e.g., ${SHARED_WORKSPACE}/css/cards.css)
2. Screenshots: ${SHARED_WORKSPACE}/screenshots/<section>-<viewport>.png (e.g., ${SHARED_WORKSPACE}/screenshots/cards-1440.png)
3. Escalation file: ${SHARED_WORKSPACE}/escalations/<section>.json (even if empty [])

Also report to the lead:

{
  "section": "cards",
  "css_file": "${SHARED_WORKSPACE}/css/cards.css",
  "screenshots": ["${SHARED_WORKSPACE}/screenshots/cards-1440.png", "${SHARED_WORKSPACE}/screenshots/cards-375.png"],
  "escalations": "${SHARED_WORKSPACE}/escalations/cards.json",
  "iterations": 2
}

---

Workflow A-Review: Full CSS Verification

After all section teammates complete, a finisher teammate takes over. The finisher COLLATES the section CSS files into one candidate, then verifies the combined output. This teammate did NOT write any of the CSS — it's an independent verification agent that tests the full combined output and fixes integration issues. (Collation is implementation-adjacent work, which is why it belongs to the finisher, not the lead — see the lead CANNOT rules in the integrate-storefront skill.)

Individual teammates verify their own sections in isolation, but the combined CSS can have problems they couldn't catch: z-index collisions, specificity fights between sections, layout shifts from combined margin/padding changes, filter sidebar width affecting the product grid, etc.

Input (from lead)

• The CSS directory ${SHARED_WORKSPACE}/css/ with one file per completed section
• Merchant doc with design tokens
• Native theme URL + Marqo theme URL
• An available browserN (implementation teammates are done)

Steps

Step 0: Collate

Merge the section CSS files from ${SHARED_WORKSPACE}/css/ into one candidate, in this order: heading → layout → cards → filters → paging → sort → count → states. Keep each section's comment header (/* === PRODUCT CARDS === */). Write the result to ${SHARED_WORKSPACE}/css/collated.css.

Step 1: Inject full collated CSS

Navigate to the Marqo theme preview using your assigned browser. Inject the entire collated CSS via browser_evaluate (same <style> tag technique as Workflow A).

Step 2: Verify every section

Screenshot EACH element from the Verification Standards table on both native and Marqo themes. Compare them all. Report per-section:

  cards:    pass
  filters:  pass
  paging:   fail — pagination buttons overlap sort dropdown
  heading:  pass
  cta:      fail — hover reveal clipped by card overflow

Step 3: Fix integration issues

For each failing section:

1. Diagnose the root cause (which sections' CSS is conflicting)
2. Write a targeted CSS fix
3. Remove old test CSS, inject updated full CSS, re-screenshot
4. Re-verify the failing section AND any sections that might be affected by the fix

Max 3 rounds per failing section. After that, log as unresolved gap.

Step 4: Output

Write these files (the TaskCompleted hook validates they exist):

1. Final screenshots: ${SHARED_WORKSPACE}/screenshots/final-<section>-<viewport>.png for every element
2. Verification report: ${SHARED_WORKSPACE}/verification-report.json

{
  "final_css": "/* Full collated + fixed CSS */\n...",
  "verification": {
    "cards": "pass",
    "filters": "pass",
    "paging": "pass (fixed: reduced pagination margin to prevent overlap)",
    "heading": "pass",
    "cta": "fail (unresolved: clip-path conflicts with filter sidebar z-index)"
  },
  "fixes_applied": [
    "Reduced .marqo-pagination margin-top from 24px to 12px",
    "Added z-index: 10 to .marqo-product-card on hover"
  ],
  "unresolved_gaps": [
    {
      "element": ".marqo-product-card:hover CTA",
      "issue": "CTA hover reveal clipped when filter sidebar is open",
      "reason": "Needs JS fix — CSS alone can't resolve the stacking context conflict"
    }
  ],
  "screenshots": {
    "cards_1440": "${SHARED_WORKSPACE}/screenshots/final-cards-1440.png",
    "cards_375": "${SHARED_WORKSPACE}/screenshots/final-cards-375.png",
    "filters_1440": "${SHARED_WORKSPACE}/screenshots/final-filters-1440.png"
  }
}

Write this JSON to ${SHARED_WORKSPACE}/verification-report.json.

The lead then presents this to the human: the final CSS, what passed, what was fixed, and any remaining gaps. Human approves before the lead pushes to settings.

---

Verification Standards

Full-page screenshots are useless for verifying small CSS changes. Each subtask screenshots the SPECIFIC ELEMENT that changed.

Section	Element selector	Viewports
Product cards	.marqo-product-card	1440, 375
Filter sidebar	.marqo-filter-sidebar	1440
Filter drawer	.marqo-filter-drawer	375
Pagination	.marqo-pagination	1440, 375
Sort dropdown	.marqo-sort-select	1440
Results count	.marqo-results-count	1440
Page heading	.marqo-collection-header	1440, 375
No results	.marqo-no-results	1440
CTA hover	.marqo-product-card:hover	1440

How to verify

1. Screenshot the element on the native theme (reference)
2. Screenshot the same element on the Marqo theme (current)
3. Compare visually. Report:
   • pass — element matches native theme in font, color, spacing, layout
   • fail — describe the specific gap (e.g., "title font is sans-serif, should be Roboto Condensed")

Viewport setup

Use browser_resize before screenshotting:

• Desktop: { width: 1440, height: 900 }
• Mobile: { width: 375, height: 812 }

---

Escalation Model

When you find a feature on the native theme that cannot be replicated with CSS alone, you do NOT attempt a workaround. Workarounds create tech debt that's hard to unwind when the feature is properly integrated.

What to do

1. Skip the feature/blocker entirely — no placeholder, no workaround
2. Write a structured escalation file to ${SHARED_WORKSPACE}/escalations/<task-name>.json

The escalation file name matches your task name (e.g., cards.json for [IMPLEMENT] Cards, okendo.json for [IMPLEMENT] Okendo). The TaskCompleted hook validates this file exists before allowing your task to complete.

The escalation file is always a JSON ARRAY of escalation objects. An empty array [] means "nothing to escalate". The TaskCreated hook validates the file parses as JSON and is non-empty before an [INTEGRATION-CODE] task can be created from it. One file can carry multiple escalations:

[
  {
    "task": "cards",
    "type": "integration",
    "feature": "Okendo review stars",
    "location": "product card, below title",
    "context": "Stars show 1-5 rating + review count, loads via JS after page render",
    "screenshot": "${SHARED_WORKSPACE}/screenshots/native-card-okendo.png",
    "impact": "Cards CSS is complete but review stars area is unstyled",
    "suggested_action": "Enable Okendo integration per apps/okendo.md"
  },
  {
    "task": "okendo",
    "type": "blocker",
    "issue": "Okendo Shopify app is not installed on this store",
    "context": "Cannot enable review widget without the app. Checked Shopify admin — no Okendo app found in installed apps list.",
    "impact": "Integration cannot proceed until app is installed by merchant",
    "suggested_action": "Ask merchant to install Okendo app, then resume"
  },
  {
    "task": "okendo",
    "type": "clarification_needed",
    "issue": "Store has both Okendo and Judge.me installed — which to configure?",
    "context": "Both apps are active. Okendo has 500 reviews, Judge.me has 50. They may conflict.",
    "impact": "Cannot proceed without knowing which provider to use",
    "suggested_action": "Invoke /grill-me to ask human which provider"
  }
]

Fields: task (your task slug), type, and context are required; use feature/location/screenshot for integration findings and issue/impact/suggested_action for blockers and scope questions.

Valid types: integration, config_change, code_change, blocker, scope_expansion, clarification_needed

3. Message the lead: "Escalation logged: {issue}. See ${SHARED_WORKSPACE}/escalations/{task-name}.json"
4. Continue work on everything in scope that isn't blocked
5. Always write the escalation file, even if empty ([]). The TaskCompleted hook validates it exists before allowing your task to complete.

What you CANNOT do (tool restrictions)

• Push to production (no storefront settings API access)
• Enable integrations (no admin API access)
• Write to DynamoDB
• Modify application code

What the lead does with escalations

The lead reads your escalation file and decides:

• Clear scope (app documented below in Third-Party Apps): spawn a new teammate for Workflow B
• Unclear scope: invoke /grill-me with the human, then dispatch or defer
• Notify other teammates if the escalation affects their section

---

Third-Party App Integration

Quick reference for common third-party apps found on merchant stores. If the app is listed here, the lead can auto-dispatch a Workflow B teammate. If not, /grill-me with the human.

Per-app guides live in docs/integrations/apps/ — read ONLY the guide for the app you're integrating (the lead passes its contents or path in the spawn prompt as appGuide). Do not read all of them.

App	What it does	Guide
Okendo Reviews	Star ratings + review count on cards, review widget on PDP	apps/okendo.md
Swym Wishlist	Heart/wishlist button on product cards	apps/swym.md
Selly / Treedify (TDF)	Promotional badges/labels on product images	apps/selly-tdf.md
Videowise	Video content tiles in the product grid	apps/videowise.md
Quickshop	Quick-add modal on card CTA click	apps/quickshop.md

---

CSS Architecture Reference

The storefront widget uses a three-layer CSS system. All per-merchant work goes in Layer 3.

Layer	What	Where	Who edits
1	CSS Variables	Auto-generated from window.MarqoUIConfig.uiComponents	Admin UI controls
2	Template CSS	Stored in uiComponents[key].css	Advanced editor (shared defaults)
3	Custom CSS	Stored in custom_css.value.css	Per-merchant overrides (your target)

Key rules:

• custom_css must be the LAST key in uiComponents — CSS injection order follows key order
• Use higher specificity for overrides (e.g., .marqo-filter-sidebar .marqo-filter-section)
• ProductCard renders <a class="marqo-product-title-link"> inside <h3> — target the <a> for title styling
• CSS variables are scoped to .marqo-search-layout (not :root)

Full details: shopify-styling-architecture.md

---

Shared Task List Structure

The team lead creates this task structure when spawning the team. Dependencies are enforced by the agent team runtime — blocked tasks cannot be claimed.

Full setup (4 sections)

Task 1:  [CLARIFY] Cards           blocked by: (none)
Task 2:  [CLARIFY] Filters         blocked by: (none)
Task 3:  [CLARIFY] Paging          blocked by: (none)
Task 4:  [CLARIFY] Heading         blocked by: (none)
Task 5:  [IMPLEMENT] Cards         blocked by: Task 1
Task 6:  [IMPLEMENT] Filters       blocked by: Task 2
Task 7:  [IMPLEMENT] Paging        blocked by: Task 3
Task 8:  [IMPLEMENT] Heading       blocked by: Task 4
Task 9:  [COLLATE] Merge CSS       blocked by: Tasks 5,6,7,8
Task 10: [FINISH] Full verify+fix  blocked by: Task 9

Tasks 9 (COLLATE) and 10 (FINISH) are both claimed by the finisher teammate, who runs Workflow A-Review — collation is its Step 0. The lead never merges CSS itself (lead CANNOT rule).

Single tweak

Task 1: [CLARIFY] {section}        blocked by: (none)
Task 2: [IMPLEMENT] {section}      blocked by: Task 1
Task 3: [FINISH] Full verify+fix   blocked by: Task 2

For a single tweak, COLLATE is unnecessary (only one section). The finisher still runs to independently verify the change.

Integration tasks (created mid-flight from escalations)

Task N:   [INTEGRATION-CODE] Okendo PR    blocked by: (none)
          → Runs in parallel with CSS work
          → Workflow B teammate: write code, raise PR, /monitor-pr
          → Output: approved PR link to lead

Integration CODE tasks are NOT blocked — the PR can be written while CSS work continues. The two streams converge when the human merges, deploys, and enables the integration.

When the human comes back and says "Okendo is deployed, verify it," the lead messages the SAME integration teammate to continue:

Task N+1: [INTEGRATION-VERIFY] Okendo    blocked by: Task N, FINISH
          → Same teammate verifies the integration is working
          → Screenshots elements, checks new UI renders correctly
          → If CSS adjustments needed (spacing around stars, etc.),
            writes CSS fixes and verifies
          → Output: verification report + any CSS patches for lead to collate

The integration teammate stays alive as a long-running peer and picks up verification when the human is ready. It has full context of what it built.

---

Tooling Reference

Tool	What it does	Usage
scripts/ecom/storefront_settings.py	Backup, push, diff, extract-css, inject-css for storefront settings	python scripts/ecom/storefront_settings.py backup <shop> --api-key <key>
scripts/ecom/shopify_graphql.py	Ad-hoc Shopify Admin GraphQL queries with auto DDB token retrieval	python scripts/ecom/shopify_graphql.py --shop <shop> --env prod --profile controller --query '<query>'
scripts/ecom/inject_marqo_blocks.py	Programmatic Liquid block injection into Shopify themes	See block injection guide

Run scripts via pants run scripts/ecom/<script>.py -- <args> to get the correct Python environment and dependencies.

---

Related Documentation

• Automation Architecture — full system design, all workflow diagrams
• CSS Customization Guide — detailed CSS how-to, common patterns, agent prompt templates
• Styling Architecture — three-layer CSS system, 53 variables, injection order
• Storefront Extensibility — DOM events, grid injections, third-party widget hydration
• Block Injection Guide — programmatic Liquid block injection
• MSQC Integration — first completed integration reference
• Muji Integration — multi-store reference with block coverage
• Laura Geller Integration — feature-heavy reference (Okendo, Quickshop, promos, market scoping, A/B)
• Shopify Diagnostics — GraphQL queries, metafield debugging, access tokens