AutoPilot: 5 AI agents that autonomously run your Shopify store

.claude/tracking/issue-1/tracking.md

@@ -0,0 +1,96 @@
+# Issue #1: Shopify Hackathon — AutoPilot AI Agents
+
+## Status: dev/implement
+## Branch: `issue-1-shopify-autopilot`
+
+## Definition of Done
+
+- [ ] `intelligence.ts` scores products into 4 tiers with velocity + stockout prediction
+- [ ] Autopilot page renders 4 agent cards with live status
+- [ ] Inventory tab shows scored/tiered products in DataTable
+- [ ] At least 2 autonomous actions fire (discount creation + email alert)
+- [ ] Storefront widget deployed via `injectStorefrontScript()` and visible on store
+- [ ] Customer segments page with DonutChart + DataTable
+- [ ] Daily insight card renders with rotating merchandising tip
+- [ ] Shell nav updated with new pages
+- [ ] All pages handle loading/empty states
+
+## Acceptance Criteria
+
+### AC1: Intelligence Layer
+- `scoreProducts()` accepts Shopify products + orders + inventory
+- Outputs scored items with: score 0-100, tier (Core/Strong/Slow/Exit), velocity, daysLeft, trend
+- Uses Plus2's power-scale algorithm (`(value/max)^0.25 * 100`)
+- Tier thresholds: Core 70+, Strong 55-69, Slow 40-54, Exit 0-39
+
+### AC2: Autopilot Page — Agents Tab
+- 4 agent cards: Rick (Ops), Hank (Supply Chain), Ron (Finance), Marcus (Chief of Staff)
+- Each shows: name, emoji, domain, status indicator, last action, action count
+- Live activity feed below cards, timestamped and tagged by agent
+
+### AC3: Autopilot Page — Inventory Tab
+- DataTable with columns: Product, Score (color bar), Tier (badge), Stock, Velocity, Days Left, Trend
+- KPICards: Total SKUs, Critical (<3 days), Warning (<7 days), Healthy
+- Sorted by urgency (days-until-stockout ascending)
+
+### AC4: Autopilot Page — Actions Tab
+- Log of autonomous actions: discounts created, emails sent, widgets deployed
+- Each with: timestamp, agent name, action type, details, status
+
+### AC5: Autopilot Page — Live Tab
+- useEventStream() powering LiveFeed
+- KPICards: Orders This Hour, Revenue This Hour
+- Incoming orders trigger score check → flash alert if low-stock product
+
+### AC6: Autonomous Actions
+- Rick: stockout alert emails for products <3 days stock
+- Ron: clearance discounts for slow movers (velocity declining + excess stock)
+- Marcus: deploys storefront widget, generates daily insight
+- All agents use hasActed map to prevent duplicate actions
+
+### AC7: Customer Segments Page
+- RFM scoring: Recency, Frequency, Monetary (1-5 quintiles)
+- Segments: Champions, Loyal, At Risk, New, Lost
+- DonutChart of segment distribution
+- DataTable with customer details + segment + scores
+- KPICards: Total Customers, Champions, At Risk, Avg LTV
+
+### AC8: Daily Insight Card
+- Emerald-green card at top of autopilot page
+- Rotates daily from pre-written merchandising insights
+- Adapted from Plus2's Pickle of the Day
+
+### AC9: Storefront Widget
+- `public/low-stock-widget.js` — vanilla JS
+- Shows "Only X left!" badge on product pages for items with <10 stock
+- Injected via `api.injectStorefrontScript()`
+
+### AC10: Navigation
+- Shell.tsx updated with Autopilot and Segments nav items
+
+## Files to Create/Modify
+
+| File | Action |
+|------|--------|
+| `frontend/lib/intelligence.ts` | CREATE |
+| `frontend/lib/agents/types.ts` | CREATE |
+| `frontend/lib/agents/rick.ts` | CREATE |
+| `frontend/lib/agents/hank.ts` | CREATE |
+| `frontend/lib/agents/ron.ts` | CREATE |
+| `frontend/lib/agents/marcus.ts` | CREATE |
+| `frontend/pages/autopilot.tsx` | CREATE |
+| `frontend/pages/segments.tsx` | CREATE |
+| `frontend/components/AgentCard.tsx` | CREATE |
+| `frontend/components/ActionLog.tsx` | CREATE |
+| `frontend/components/DailyInsight.tsx` | CREATE |
+| `frontend/public/low-stock-widget.js` | CREATE |
+| `frontend/components/Shell.tsx` | MODIFY |
+
+## Build Order
+
+1. **Phase 1** — `intelligence.ts` + `agents/types.ts` (foundation)
+2. **Phase 2** — Agent modules (`rick.ts`, `hank.ts`, `ron.ts`, `marcus.ts`)
+3. **Phase 3** — UI components (`AgentCard`, `ActionLog`, `DailyInsight`)
+4. **Phase 4** — Pages (`autopilot.tsx`, `segments.tsx`)
+5. **Phase 5** — Storefront widget + Shell nav update
+6. **Phase 6** — Wire up agent loop in autopilot page

CLAUDE.md

@@ -1,4 +1,37 @@
-# Shopify Hackathon — Builder's Guide
+# AutoPilot — AI Agent Command Center for Shopify
+
+## What We Built
+5 autonomous AI agents that monitor, decide, and act on a Shopify store. Each agent has a distinct personality powered by Claude (Haiku) and takes real actions — product deactivation, purchase orders, discount codes, email drafts, customer segmentation.
+
+### Agents
+| Agent | Domain | What They Do |
+|-------|--------|-------------|
+| **Rick** | Operations | Deactivates zero-stock products, stockout alerts, health checks |
+| **Hank** | Supply Chain | Scores products (Core/Strong/Slow/Exit), creates draft POs, reorder recs |
+| **Ron** | Finance | Detects slow movers, creates discount codes in local DB |
+| **Marty** | Marketing | RFM customer segmentation, drafts win-back + VIP email campaigns |
+| **Marcus** | Chief of Staff | Coordinates all agents, deploys storefront widget, daily insights |
+
+### How It Works
+- **Backend** (`backend/app/agents/`): Orchestrator runs every 60s as an asyncio background task. Each cycle: load data → score products → detect issues → take actions → narrate via Claude → persist to SQLite.
+- **Frontend** (`frontend/pages/autopilot.tsx`): Polls `/agents/states`, `/agents/actions`, `/agents/stats` every 5s. Pure read-only dashboard — agents run independently of the browser.
+- **Shopify integration**: Agents attempt Shopify mutations (GraphQL/REST) first. When Shopify is unavailable, all actions are applied to the local SQLite database. The wiring exists for: product status updates, tag mutations, price rules, discount codes, ScriptTag injection.
+- **Seed data**: When Shopify sync fails, `backend/app/agents/seed.py` creates 25 products, ~200 orders, 40 customers with realistic velocity patterns to trigger all agent behaviors.
+
+### Key Files
+- `backend/app/agents/orchestrator.py` — Main agent loop, all 5 agents
+- `backend/app/agents/intelligence.py` — Scoring, stockout detection, RFM segmentation
+- `backend/app/agents/personas.py` — Claude system prompts per agent
+- `backend/app/agents/voice.py` — Claude API client for personality narration
+- `backend/app/agents/models.py` — AgentAction, PurchaseOrder, Discount SQLAlchemy models
+- `frontend/components/AgentDialogue.tsx` — Chat-style agent feed with avatars
+- `frontend/pages/autopilot.tsx` — Command center with 4 tabs
+- `frontend/pages/purchase-orders.tsx` — PO management page
+- `frontend/pages/segments.tsx` — Customer segmentation with donut chart
+
+---
+
+# Shopify Hackathon — Builder's Guide (Starter Repo Docs)
 
 ## What You Have
 A working Next.js 14 dashboard connected to a real Shopify store with live data flowing.

DEMO-VIDEO.md

@@ -0,0 +1,67 @@
+# AutoPilot Demo Video — Script
+
+## Format
+~90 seconds. Motion graphics with voiceover narration. 5 scenes. The story is simple: meet the agents, watch them work.
+
+---
+
+## Scene 1: THE HOOK (10s)
+Dark screen. Text fades in: "What if your Shopify store ran itself?"
+Beat. Then the AutoPilot command center fades in — dark dashboard, 5 agent cards glowing green.
+**VO**: "Meet AutoPilot. Five AI agents that don't just monitor your store — they run it."
+
+---
+
+## Scene 2: MEET THE CREW (20s)
+Each agent card animates in one at a time with their avatar, name, role, and a one-line action they just took:
+
+- **Rick** (Operations) — "Deactivated 'Vintage Tee' — zero stock, no open POs."
+- **Hank** (Supply Chain) — "Created PO-001: 144 units of Black Hoodie, $5,126."
+- **Ron** (Finance) — "Generated discount EXIT-VINTAGE-TEE-30 for slow movers."
+- **Marty** (Marketing) — "Launched win-back email to 4 at-risk customers."
+- **Marcus** (Chief of Staff) — "Overrode Ron's discount — Marty wants to try content first."
+
+**VO**: "Rick handles operations. Hank manages supply chain. Ron watches the money. Marty runs marketing. And Marcus keeps them all in line. Each one powered by Claude — with a real personality."
+
+---
+
+## Scene 3: WATCH THEM ARGUE (25s)
+The agent dialogue feed scrolls into view. Speech bubbles from each agent, showing a real conversation:
+
+> **Hank**: "Black Hoodie is down to 12 units. 3 days of runway. Drafting a PO."
+> **Ron**: "Vintage Tee hasn't moved in 9 days. Creating a 30% clearance code."
+> **Marty**: "Hold on Ron — before we slash prices, let me try a content play. I'll push it to the Champions segment first."
+> **Marcus**: "Marty's right. Ron, hold the discount 24 hours. Marty, you've got one cycle. If velocity doesn't move, Ron's discount goes live."
+
+**VO**: "They don't just execute — they debate. Marty pushes back on Ron's discounts. Marcus mediates. Every decision is reasoned, logged, and reversible."
+
+---
+
+## Scene 4: REAL ACTIONS, REAL DATA (20s)
+Quick cuts showing actual results of agent actions:
+
+1. A purchase order with line items and costs (Hank created it)
+2. A discount code live in Shopify (Ron created it)
+3. A product marked inactive (Rick did it)
+4. An email sent to at-risk customers (Marty triggered it)
+
+**VO**: "These aren't suggestions in a dashboard. Rick deactivated a product. Hank filed a purchase order. Ron created a discount code. Marty sent the email. Real actions on real Shopify data — happening right now."
+
+---
+
+## Scene 5: THE CLOSE (15s)
+Pull back to full command center. All 5 agents active. Action count ticking up. Live orders streaming in.
+
+Text overlay: **"AutoPilot. Your store runs itself."**
+
+**VO**: "Five agents. One command center. Zero hand-holding. Built in 24 hours at the NS Shopify Hackathon."
+
+---
+
+## Notes
+- Total: ~90 seconds
+- The story arc: hook → meet the characters → watch them interact → see the proof → close
+- The dialogue scene (Scene 3) is the money shot — it shows these aren't dumb bots, they reason and disagree
+- Scene 4 is the credibility shot — real Shopify mutations, not mockups
+- Dark theme throughout, accent green #00FF94 sparingly
+- Brand colors: #0A0A0B background, #151518 cards, Inter font

backend/app/agents/__init__.py

@@ -0,0 +1 @@
+"""Autonomous agent system — server-side orchestration with Claude-powered personalities."""