marketing-img

A Claude Code plugin that turns your product + a few pointers into 4 ad-image PROMPT candidates — prompts you run in ChatGPT/Gemini together with your own product photo. It never generates an image itself.

Entry

/marketing-img:start <what you want — set up our brand / collect category ads / make prompt candidates>

The orchestrator agent routes the request and dispatches role-scoped subagents. (CLAUDE.md is a DEV reference only — it is NOT loaded for consumers.)

Pipeline (the modes the orchestrator routes into)

Install

Prerequisites: Node ≥ 20 · a local Chrome/Chromium (the collection mode drives it via CDP; set CHROME_BIN if it's in a non-standard path). macOS/Linux (the launcher uses lsof/curl).

# from a git repo (clone = a real copy):
claude plugin marketplace add github.com/mwroh-dev/marketing-ad-img
claude plugin install marketing-img@mwroh-dev
# …or local dev:
claude --plugin-dir /path/to/marketing-ad-img

# one-time: the collection/validation scripts need node deps (run in the plugin dir)
npm install     # ajv, ajv-formats, yaml, chrome-remote-interface, tsx (+ optional sharp)

• Assets resolve via ${CLAUDE_PLUGIN_ROOT} → the plugin runs from any working directory.
• Consumer state (brands, runs, collected ads) is written to ./.generate-ads-img/ in your project (gitignored).

Three names, on purpose. The repo is marketing-ad-img, the plugin (and command namespace /marketing-img:start) is marketing-img, and the runtime state directory is ./.generate-ads-img/. They are intentionally distinct: the repo hosts the plugin, the plugin name drives the command, and the state dir is per-consumer working data.

Structure

.claude-plugin/{plugin.json, marketplace.json}    plugin manifest + marketplace
settings.json                                     "agent": "orchestrator" (default/entry agent)
commands/start.md                                 /marketing-img:start — the single entry command
agents/ (flat .md)                                orchestrator + 26 active role-scoped subagents (+ 1 deprecated historical note)
skills/ (2)                                       reusable skills (agent-browser-exploration, user-answer-tooling)
knowledge/  guidelines ⊥ experience ⊥ reference   principles · learned patterns · mode runbooks + design refs
schemas/ (48, single-sourced from TypeBox)        I/O contracts per stage — `<name>.ts` → `build.ts` → `.schema.json` (validator) + lean `.view.md` (agents read)
shared/  collect · harness · validators · evals · _lib   CDP collection (run-flow self-launches Chrome), deterministic glue (close-analysis · build-market-position · normalize-artifact), schema validators + runtime gates (validate-store · validate-gen-run), behavioral eval suites + regression baseline (run-all · dispatch-agent)
flows/ (meta-ad-library, google-ads-transparency) per-source CDP collection adapters (defineFlow)
config/ (cdp-ports, image-adapters, tool-entrypoints)
AGENTS.md                                         dev entry for AI coding agents (Codex etc.) → CLAUDE.md / orchestrator / subagent-projection.md
CLAUDE.md                                         DEV reference — NOT shipped/loaded for consumers

The 26 active subagents (by stage)

• evaluation / intake — request-evaluator, interview-controller, ad-intent-deriver (typed ad-intent draft at step 4; READ-ONLY — persisted only via the sole-writer tool)
• setup — brand-researcher
• collection — keyword-planner, discovery-scout, competitor-curator, ad-creative-refiner (post-collection keep/drop is a human review + deterministic screen-images.mjs, no LLM)
• analysis — perception-extractor, ad-type-classifier, copy-analyst, layout-analyst, visual-analyst, intent-analyst, strategy-projector, ad-analyst, pattern-synthesizer, competitive-analyst, temporal-change-analyst, market-context-researcher
• generation — creative-opportunity-mapper, creative-brief-analyst, direction-verifier, copy-layout-planner, image-prompt-adapter, critic-verifier

Hard rules (single-owner: knowledge/reference/non-negotiable-rules.md)

• Prompt-only — never generate an image or call a provider.
• Ad creatives only from public ad-transparency libraries (Meta/Google); commerce stores = public review reading only, no scraping.
• Non-intrusive CDP — dedicated headless Chrome, background tabs, never steal the user's cursor/focus; STOP on block, no bypass/stealth/captcha/URL-assembly/DOM-injection.
• Credentials never in artifacts (reference profile_id / port only).
• Every subagent dispatch is code-gated: handoff_validate PASS issues a one-shot ticket; the PreToolUse hook blocks un-ticketed dispatches.
• Completion = independent verification, never self-declaration.

Responsible use

• Public data only. Ad creatives are collected from public ad-transparency libraries (Meta Ad Library, Google Ads Transparency) that require no login. Commerce stores are used for public review reading only — never scraped.
• You are responsible for compliance with each site's Terms of Service and applicable law in your jurisdiction. This tool does not bypass blocks, captchas, or auth — it stops on a block by design.
• No affiliation. Not affiliated with, endorsed by, or sponsored by Meta, Google, or any ad platform. Trademarks belong to their owners.
• Provided as is, without warranty (see LICENSE).

Status

• Verified in dev runs on real data: Meta/Google ad collection (real images) → analysis → 4 critic-passing prompt candidates. Not yet independently reproduced/CI-gated.
• Provisional (0.1.0-alpha) — gathering real user feedback before stabilizing.
• Behavior is driven by agent contracts (markdown) + mode runbooks — it evolves by editing those.