Homepage Curating Agent for Shopify

Overview

The Homepage Curating Agent is agent 15 of 18 in a planned series of Shopify AI agents. It is designed to rebuild a store's homepage and merchandising every morning, replacing a homepage that is normally set once and forgotten with one that reflects live demand and the inventory a merchant actually needs to move. The project currently exists as an agent brief and build playbook (a project PDF plus AGENTS.md/CLAUDE.md context files) rather than shipped code, so this entry documents the architecture and plan as defined in those documents.

Problem

A static homepage ignores what is trending, in season, or sitting unsold in the warehouse, wasting a store's most valuable real estate every day. Manual daily merchandising does not scale, and dead inventory sits unfeatured while demand shifts underneath a page nobody is updating.

Approach

Each morning, on a pre-open cron trigger, the agent pulls demand signals (trending products, season, local weather, calendar) and yesterday's conversion data, alongside the inventory that needs to move. It scores candidate heroes, collections, and products, composes a homepage layout and featured sets, and updates the theme. The plan calls for shipping an MVP first that scores from inventory and recent conversion alone (skipping external signal feeds), before layering in trend/weather/calendar signals, a bundle composer, and full autonomy.

A secondary lever added to the plan is a native bundle composer built on Shopify Functions (Cart Transform plus an automatic bundle discount, with no third-party kit dependency). The Decide step composes daily bundles from inventory to move and high-converting anchor products, which the homepage then features to lift AOV on top of CTR.

Architecture

• Perceive: reads trend/weather data, season and calendar, inventory to move, and recent conversion by product/collection.
• Decide: a scoring model ranks candidate heroes, collections, and products, and composes bundles from inventory-to-move plus high-converting anchors, all constrained by policy guardrails.
• Act: writes the daily feature plan to the Shopify theme via the Theme/Sections API, updating hero, collection order, featured sets, and bundle blocks.
• Learn: measures homepage CTR and sell-through (and AOV for bundles), logging outcomes and refining curation weights stored in pgvector memory.
• Autonomy ramp: Shadow (proposes the daily plan, changes nothing) to Assisted (holds the layout for human sign-off) to Autonomous (publishes on its own, with a safe fallback layout if a data feed fails).

Tech stack

• LLM core for scoring and curation planning (the brief references both Codex and Claude as the intended model across drafts)
• pgvector for curation memory and weight refinement
• Shopify Admin and Theme APIs for reading inventory/conversion and writing homepage sections and metafields
• Shopify Functions (Cart Transform, automatic bundle discounts) for the native bundle composer
• Shopify Polaris (app home / admin extensions) for the Assisted-phase approval dashboard
• Trend and weather APIs for external demand signals
• Policy guardrail layer enforcing in-stock filtering, floor margins on bundles, and change-rate limits

AI work

• Designed the Perceive, Decide, Act, Learn loop as the agent's core control architecture, with pgvector-backed memory feeding the Decide step's curation weights.
• Defined a feature-scoring model contract (starter prompt) that takes signals, inventory_to_move, recent_conversion, and in_stock_collections, and outputs structured JSON (hero, collections, featured, bundles), keeping the plan coherent rather than random.
• Planned a staged autonomy ramp (shadow, assisted, autonomous) so the model's output is only trusted with unattended publishing after it has been observed and measured.
• Specified guardrails directly in the agent contract: only feature in-stock items, always keep a safe fallback layout for data failures, and constrain day-to-day change rate to prevent homepage whiplash.

Engineering highlights

• Autonomy ramp with a safe fallback: the system is designed to degrade to a known-good layout rather than publish on bad or missing data.
• In-stock filtering enforced before publish, so the agent cannot feature sold-out inventory regardless of what the scoring model ranks highest.
• Bundle discounts are planned to respect a configured floor margin, keeping the AOV lever from eroding profitability.
• Build plan is explicitly MVP-first: ship inventory plus recent-conversion scoring before adding external signal feeds, bundles, or autonomy, reducing risk before layering complexity.
• Project scaffolding maps each build step to a specific owner (Shopify skill/API), keeping architecture and implementation ownership aligned.