merch-auditor

A Cowork plugin for expert storefront auditing, powered by merch-connector.

Give Claude deep expertise in evaluating e-commerce storefronts — scoring UX, conversion, copywriting, and competitive positioning — and surfacing specific, prioritized recommendations with tagged ownership.

---

Why merch-auditor?

Manual storefront auditing is time-consuming, inconsistent, and fragmented. Merchandisers spend hours evaluating competitor sites, checking if data appears correctly, spot-checking product pages, and documenting what changed. merch-auditor automates this workflow — it scrapes storefronts, interrogates data layers, analyzes merchandising quality through expert lenses, and produces scored audit reports with prioritized recommendations.

---

What It Does

merch-auditor wraps the merch-connector MCP with a structured agent workflow. You point it at a URL, it acquires the full storefront payload in one call, scores four audit dimensions, and saves a report to your workspace.

Workflow (v2 — 3 MCP calls total):

site_memory(read) → acquire(url, pdp_sample=2) → [score offline] → site_memory(write)

Everything between the acquire and the memory write happens against the local payload — no further live site calls. If the site is bot-protected and the acquire returns blocked: true, the agent executes the Bot-Block Fallback Protocol (Google-indexed page states, URL parameter archaeology, sibling page comparison) before reporting.

It handles both B2C and B2B/Hybrid storefronts, routing to the appropriate analysis persona automatically:

• B2C → conversion_architect (DTC/retail lens)
• B2B or Hybrid → b2b_auditor (procurement, contract pricing, catalog depth)

Reports are saved as markdown to outputs/ and findings are written back to site_memory for score trending across sessions.

---

Personas

merch-auditor automatically selects the right analysis lens based on storefront signals:

Persona	When Used	Evaluates
Conversion Architect	B2C / DTC storefronts	Funnel friction, UX gaps, copywriting, mobile readiness, checkout experience
B2B Auditor	B2B / Hybrid storefronts	Procurement readiness, spec completeness, contract pricing visibility, bulk order flow

---

Commands

Command	Usage	What it does
/audit <url>	/audit https://example.com	Full scored audit across 4 dimensions
/compare <url-1> <url-2>	/compare https://a.com https://b.com	Side-by-side scorecard comparison
/research <url>	/research https://example.com [focus]	Open-ended dossier — competitive research, client prep
/track <url>	/track https://example.com	Change-detection vs. prior audit baseline

---

Scoring System

Each audit scores four dimensions on a 1–10 scale (40 points total):

Score	Grade	Meaning
35–40	A	Exceptional
28–34	B	Solid
20–27	C	Needs work
< 20	D	Significant overhaul needed

Every finding is tagged with its owning team:

• [DATA QUALITY] — bad feed data → Merchandising/catalog
• [FRONTEND INTEGRATION] — data in API but not rendered → Engineering
• [UX DESIGN] — data renders but experience is poor → Design
• [STRATEGY] — missing entirely → Product/marketing

---

Installation

Requirements

• Cowork desktop app
• merch-connector ≥ 2.0.9 — installed automatically via npx when the plugin runs

Install the plugin

1. Download or clone this repo
2. Open Cowork → Plugin settings → Upload plugin folder
3. Select the repo root (the folder containing .claude-plugin/)
4. The plugin activates immediately — no restart needed

Verify the connection

After installing, run:

/audit https://example.com

If merch-connector isn't installed, npx will pull it automatically on first run.

---

Output

Audit reports are saved to your selected workspace folder:

outputs/audit-[domain]-[YYYY-MM-DD].md
outputs/compare-[domain-a]-vs-[domain-b]-[YYYY-MM-DD].md
outputs/research-[domain]-[YYYY-MM-DD].md
outputs/track-[domain]-[YYYY-MM-DD].md

Each run also writes a site_memory note via merch-connector, enabling score trend tracking across sessions.

---

Plugin Structure

.claude-plugin/
  plugin.json          ← manifest: version, commands, MCP config
commands/
  audit.md             ← /audit workflow
  compare.md           ← /compare workflow
  research.md          ← /research workflow
  track.md             ← /track workflow
skills/
  storefront-auditing/
    SKILL.md           ← audit framework, persona routing, scoring
    references/
      audit-rubrics.md       ← detailed dimension rubrics
      dual-lens-pattern.md   ← API vs UI gap analysis pattern
CONNECTORS.md          ← MCP connection details
CHANGELOG.md           ← version history

---

Compatibility

Plugin version	merch-connector
v0.5.x	≥ 2.0.9
v0.4.x	≥ 1.8.0 (legacy)

The plugin calls merch-connector via npx merch-connector@latest by default. To pin a version, edit .claude-plugin/plugin.json:

"args": ["-y", "merch-connector@2.0.12"]

---

Related

• merch-connector — the MCP server this plugin wraps. acquire one-pass architecture, Firecrawl + Puppeteer scraping, 5 analysis personas, bot-block detection.
• Bug reports and roadmap tracked in the Merch Project Hub on Notion.

---

Author

Built by @grahamton.