Scope: BeStore

A single brand online store where customers browse products, add them to a cart, and pay by card (as a guest or with an optional account), plus an admin panel where a few admins run the catalog, orders, discounts, and sales stats. It sells in one country, in one language and one currency, and ships at a flat rate.

Build approach: Tracer Bullet (prove one real thread through every layer first, then thicken one segment at a time, each slice shipped end to end). Workflow: Beta (after /develop: /check verify, then /test). The project default level of rigor. /architect is the recommended first stop for a feature with a real decision, but skippable when you already know the build. Features that touch money or sign in carry · GA for an extra fresh model review.

These are recommendations to keep your build orderly, not requirements. Skip anything that does not fit: if you already know how to build a feature, use /develop and skip /architect. You decide when a feature is done.

At a glance

#	Feature	Phase	Status
1	Stack & architecture	Foundation	done
2	Coding standards & tooling	Foundation	done
3	Data model	Foundation	done
4	Design system & UI foundation	Foundation	done
5	Admin sign in	Slice 1	done
6	Core buy loop	Slice 1	done
7	Card payment & paid orders	Slice 1	done
20	One Stripe session state	Slice 1 follow up	done
21	Report Stripe skill doc bugs upstream	Slice 1 follow up	done
8	Shipping address & flat rate	Slice 2	done
22	Purge PII from expired orders	Slice 2 follow up	done
9	Admin catalog management	Slice 3	done
10	Admin order management	Slice 4	done
11	Order emails	Slice 5	done
12	Customer accounts	Slice 6	done
13	Categories, search & filters	Slice 7	done
14	Discounts & promo codes	Slice 8	done
15	Admin sales dashboard	Slice 9	done
23	Native controls in GET forms	Slice 9 follow up	done
16	Legal pages & cookie consent	Launch	done
17	SEO for storefront pages	Launch	done
18	Analytics & error tracking	Launch	planned
19	Production deploy	Launch	planned

Foundations

1. Stack & architecture · done

Decide the stack (storefront, admin, back end, database, hosting) and scaffold a runnable project so every slice builds on real structure. The storefront must be renderable for search engines, so SEO is a stack requirement from day one. Done when: the stack is recorded in a spec, and the empty scaffold boots locally and passes build. spec 0001 · code in app/, src/, prisma/, supabase/

Decide the stack (spec): /architect stack & architecture
Scaffold from the decision: /develop stack & architecture
Verify it: /check verify stack & architecture
Test it: /test stack & architecture

2. Coding standards & tooling · done

Capture conventions from the real scaffolded project, then install lint, format, type checks, pre commit hooks, and CI. Done when: root AGENTS.md reflects the real stack, and lint, format, and pre commit run clean. code in package.json, .github/workflows/

Capture conventions + tooling choices: /audit
Build it: /develop tooling
- Stricter types (noUncheckedIndexedAccess, no any)
- Prettier with Tailwind class sorting
- Pre commit hook (lint, format, typecheck)
- CI on GitHub Actions

3. Data model · done

Core entities every feature builds on: products, variants (size, color) with their own price and stock, categories, images, carts, orders and order lines, customers, admins, discounts, shipping settings. Done when: the schema supports every planned slice (variants, guest and account orders, refunds, promo codes) without a breaking migration, and order lines keep the price paid even if the product changes later. spec 0002 · code in prisma/, tests/db/

Design it (spec): /architect data model
Build it: /develop data model
- Thin thread: products, variants and settings migrated, db test suite and CI Postgres running (AC-1, AC-2, AC-4, AC-9, AC-14)
- Full catalog, people and cart tables with their constraints and tests (AC-5, AC-7, AC-10)
- Orders, money and operations tables, no drift, constraint and race tests (AC-3, AC-6, AC-8, AC-11, AC-12, AC-15)
- Demo seed with the local host guard (AC-13)
Verify it: /check verify data model
Test it: /test data model

4. Design system & UI foundation · done

Visual language, layout, and base components shared by the storefront and the admin panel, built to WCAG AA from the start. Done when: design.md covers type, color, spacing, and components; base components work by keyboard and screen reader and meet AA contrast. spec 0003 · design design.md · code in src/components/, src/lib/brand/, app/style-guide/, app/globals.css

Design it (spec): /architect design system & UI foundation
Build it: /develop design system & UI foundation
- Thin thread: shadcn on Base UI, brand files, fonts, STORE_LOCALE, first storefront shell, gated /style-guide, axe and Playwright in CI (AC-1, AC-5, AC-11, AC-16)
- Tokens with measured contrast, the core component set on the style guide, design lint, placeholder and reduced motion (AC-3, AC-4, AC-12, AC-14, AC-15)
- Storefront and admin shells complete, with keyboard and axe tests on desktop and phone (AC-6, AC-7, AC-8, AC-9)
- Money formatting and Price, error pages, and docs/design.md (AC-2, AC-10, AC-13)
Verify it: /check verify design system & UI foundation
Test it: /test design system & UI foundation

Slice 1: Core buy loop (the walking skeleton)

The thinnest real thread: an admin signs in and adds a product, a customer finds it, buys it, pays, and the paid order shows up in admin. Real database, real payment, real UI, just narrow.

5. Admin sign in · done · GA

Only admins reach the admin panel. One role, a few admin accounts, no public sign up. Done when: an admin can sign in and out; every admin page and admin action refuses anyone who is not signed in as an admin. spec 0004 · code in src/features/admin-auth/, app/admin/, scripts/admin/, docs/runbooks/admin-accounts.md

6. Core buy loop · done

The narrow end to end path: an admin creates a product with variants, price, stock, and one image; the storefront shows a product list and a product page; a customer picks a variant, adds it to a cart, and reaches checkout as a guest. Done when: a product created in admin appears on the storefront; a customer can choose a variant, change quantities in the cart, and the cart survives a page reload; out of stock variants cannot be added. spec 0005 · code in src/features/catalog/, src/features/cart/, src/lib/cart/, app/(store)/, app/admin/(panel)/products/, src/features/checkout/

Design it (spec): /architect core buy loop
Build it: /develop core buy loop
- Thin thread: Cache Components on with the admin and auth refit (proxy admin gate with real 404s, sign out as a POST route), admin create and list for a simple product, cached home grid and product page, add to cart with the signed cookie, cart survives reload in e2e (AC-1, AC-3, AC-6, AC-8, AC-9, AC-14, AC-15, AC-19, AC-20)
- Options and variants: option types, generated variant grid, field errors, product page picker with availability (AC-2, AC-4, AC-7)
- Product image: signed upload to Storage, alt text, image config, Storage in CI (AC-5)
- Full cart and checkout stub: quantity and remove, stale line flags, header count, /checkout summary (AC-10, AC-11, AC-12, AC-13)
- Expired cart cron, logs, and the accessibility pass (AC-16, AC-17, AC-18)
Verify it: /check verify core buy loop
Test it: /test core buy loop

7. Card payment & paid orders · done · GA

Guest card payment at checkout, confirmed on the server, turning the cart into a paid order that appears in a basic admin order list. Done when: a successful payment creates exactly one paid order and reduces stock; a failed or abandoned payment creates no paid order; the order shows in admin with its lines and total; paying twice for the same cart is not possible. spec 0006 · code in src/features/checkout/, src/features/orders/, src/lib/orders/

Slice 1 follow ups (from the review of feature 7)

20. One Stripe session state · done

Replace the three places that each work out what a Checkout Session's status and payment_status mean (src/features/checkout/queries.ts, src/features/orders/reconcile.ts, src/features/checkout/actions/start-checkout.ts, overlapping decideEvent in src/features/orders/event-decision.ts) with one shared pure function, shipped as its own PR. from spec 0006 Done when: every caller reads the session through the one function, it has unit tests for each status and payment status pair, and every existing checkout, webhook and reconcile test still passes unchanged. spec 0006 · code in src/lib/orders/session-state.ts

Build it: /develop one Stripe session state
Review it (fresh model): /check review one Stripe session state

21. Report Stripe skill doc bugs upstream · done · Prototype

The vendored stripe-best-practices skill has broken docs.stripe.com/undefined.md links in references/tax.md (lines 23, 38, 41, 57, 87) and a v2 Financial Accounts endpoint in references/treasury.md (line 10) that CodeRabbit says is wrong. A local fix would be overwritten on update, so it goes to the source. Done when: an issue on stripe/ai lists the broken links and the endpoint question, and its link is noted here. issue stripe/ai#554

Report it: open an issue on stripe/ai (gh issue create --repo stripe/ai)

Slice 2: Shipping

8. Shipping address & flat rate · done

Checkout collects a delivery address and adds one flat shipping fee, free above an amount the admin sets. Done when: checkout requires a valid address, the total includes the right shipping fee (or free above the threshold), and admin sees the address on the order. spec 0007 · code in src/lib/shipping/, src/features/checkout/, src/features/settings/

Slice 2 follow ups (from spec 0007)

22. Purge PII from expired orders · done

Orders that expire without payment keep the customer's name, address, phone and email. A daily cron blanks them once an order has been expired for a set number of days, in line with the privacy policy from feature 16. from spec 0007 Done when: orders expired longer than the retention period hold no name, address, phone or email, paid orders are never touched, and the cron refuses calls without CRON_SECRET. spec 0008 · code in src/features/orders/

Design it (spec): /architect purge PII from expired orders
Build it: /develop purge PII from expired orders
- Migration (nullable email, pii_purged_at, CHECKs, partial index) and the nullable email ripple through readers and fixtures (AC-3, AC-9)
- Purge function, cron route, vercel.json schedule and logs (AC-1, AC-2, AC-4, AC-5, AC-6, AC-7, AC-10)
- Admin list and detail show "Personal data removed" (AC-8)
- Safety net: DB tests for the purge, guards, overlap and failure; e2e with axe for a purged order (AC-1 to AC-9)
Verify it: /check verify purge PII from expired orders
Test it: /test purge PII from expired orders

Slice 3: Catalog

9. Admin catalog management · done

Thicken the admin product editor: edit and hide products, manage categories, several images per product, stock per variant. Done when: an admin can create, edit, hide, and reorder products and categories, upload and order several images, and change stock per variant; hidden products vanish from the storefront. spec 0009 · code in src/features/catalog/, src/features/categories/

Slice 4: Orders

10. Admin order management · done

Run orders after payment: filter and search orders, move them through statuses (paid, shipped, delivered, cancelled, refunded), and issue refunds. Done when: an admin can find any order, change its status with a history of who changed what, and refund all or part of it through the payment provider; a refund returns stock when chosen. spec 0010 · code in src/features/orders/, src/lib/orders/, app/admin/(panel)/orders/, prisma/migrations/

Slice 5: Emails

11. Order emails · done

Tell customers what is happening with their order. Done when: customers get an order confirmation after payment and an email when the order ships or is refunded; emails are sent once, even if a step is retried. spec 0011 · code in src/lib/email/, emails/, src/features/orders/, prisma/migrations/

Design it (spec): /architect order emails
Build it: /develop order emails
- Thin thread: migration, env and transports, the outbox, one confirmation email sent from the paid webhook (AC-1, AC-8, AC-10, AC-16)
- All three emails: full confirmation layout and content, shipped, refunds with frozen cancel wording (AC-2 to AC-7, AC-18)
- Failure handling: error sorting, in process retry, daily sweep in the reconcile cron, give up and flag, missing email (AC-9, AC-11, AC-12)
- Admin Emails section and Send again, logs, e2e with axe (AC-13 to AC-15, AC-17, AC-18)
Verify it: /check verify order emails
Test it: /test order emails

Slice 6: Accounts

12. Customer accounts · done · GA

Optional accounts: guest checkout stays the default, customers who sign up see their order history and saved address. Done when: a customer can sign up, sign in, reset a password, and see past orders; guest checkout still works; a guest can later create an account with the same email and see earlier orders. spec 0012 · code in src/features/account/, src/lib/customer/, src/lib/cart/merge.ts, src/lib/email/, emails/, app/(store)/account/

Slice 7: Discovery

13. Categories, search & filters · done

Help customers find products: category pages, text search, filters by price and variant options, sorting. Done when: a customer can browse by category, search by name, filter and sort results, and the URL reflects the filters so results can be shared; empty and no results states render. spec 0013 · code in src/features/catalog/listing/, src/features/categories/

Design it (spec): /architect categories, search & filters
Build it: /develop categories, search & filters
- Thin thread: categories cache tag and its expiry, the cached listing index, header nav, category pages with paging, not found and empty states (AC-1 to AC-3, AC-5, AC-22)
- Home and search: home becomes the full listing, text folding, the header search box, /search with Best match and the short query prompt (AC-4, AC-6 to AC-10)
- Filters and sort: option groups and counts, per variant matching, price, stock and sale, URL repair and serialization, sort, the panel, Sheet, chips and no results states (AC-11 to AC-21)
- Admin arrange inside a category (AC-23)
- Safety net: category metadata and canonicals, e2e with axe and keyboard on home, category and search (AC-1 to AC-25)
Verify it: /check verify categories, search & filters
Test it: /test categories, search & filters

Slice 8: Discounts

14. Discounts & promo codes · done · GA

Admin created promo codes (percent or fixed amount, with dates and usage limits), applied at checkout. Done when: a valid code lowers the total correctly before payment; expired, used up, or invalid codes are rejected with a clear message; the discount is saved on the order and in refunds. Spec: 0014 · code in src/features/discounts/, src/lib/discounts/

Slice 9: Insights

15. Admin sales dashboard · done

The admin landing page: revenue, order count, average order value, and best sellers over a chosen period. Done when: numbers match the orders in the database for the chosen period, refunds are subtracted, and the page loads fast with a year of orders. Spec: 0015 · code in src/features/dashboard/

Design it (spec): /architect admin sales dashboard
Build it: /develop admin sales dashboard
- Thin thread: store day helper, default period, live totals, the four cards on /admin, the Dashboard nav item, skeletons and failure logging (AC-1, AC-2, AC-5 to AC-8, AC-14)
- Period picker and comparison: presets, custom range with clamp and fallback, previous window, change text, currency notice (AC-2 to AC-4, AC-7, AC-10)
- Best sellers and chart: the top 10 table, shadcn Chart with day, week and month buckets, the table toggle (AC-8, AC-9, AC-11, AC-12)
- Orders link and safety net: dates=paid on the orders list, the seeded year speed and exactness test, e2e with axe and keyboard (AC-13, AC-15, AC-16)
Verify it: /check verify admin sales dashboard
Test it: /test admin sales dashboard

Slice 9 follow ups (from spec 0016)

23. Native controls in GET forms · done

Every filter, period picker and search box uses native controls (NativeSelect, native checkbox and radio) and a submit button, so it works before the app's JavaScript loads. The admin orders, discounts and products filters move off the Base UI Select and Checkbox, and the hand rolled selects move to NativeSelect. from spec 0016 Done when: no GET form uses a Base UI control, ESLint bans @/components/ui/select outside the style guide, and every GET form has a passing e2e test with the app's scripts blocked. spec 0016 · code in src/components/ui/native-select.tsx

Design it (spec): /architect native controls in GET forms
Build it: /develop native controls in GET forms
- NativeSelect from the shadcn registry, with its states on /style-guide
- Move the orders, discounts, products, dashboard, sort and checkout country controls to native ones, with the e2e steps that open them updated
- blockAppScripts helper and one no JavaScript e2e test per GET form, then the ESLint ban
Verify it: /check verify native controls in GET forms
Test it: /test native controls in GET forms

Launch readiness

16. Legal pages & cookie consent · done

Terms, privacy policy, returns and shipping policy, and a cookie banner that blocks non essential cookies until the customer agrees. Done when: the legal pages are linked from every page footer and from checkout; no analytics or marketing cookies are set before consent; the customer can change their choice later. spec 0017 · code in src/lib/legal/, src/lib/consent/, src/features/legal/

Design it (spec): /architect legal pages & cookie consent
Build it: /develop legal pages & cookie consent
- Thin thread: the terms page from Markdown, the footer link, the checkout checkbox recording the version on the order, the admin line and the confirmation email (AC-1, AC-2, AC-4, AC-7 to AC-11, AC-13, AC-14)
- The other four pages with live shipping values, the model withdrawal form, print styles and the sign up notice (AC-1 to AC-3, AC-5 to AC-7, AC-12)
- Consent core: the cookie, the registry, ConsentProvider, useConsent and ConsentGate, and the cookie table (AC-15, AC-17, AC-22)
- Banner, settings dialog, withdrawal, GPC, the style guide demo and the first visit privacy e2e (AC-16, AC-18 to AC-21, AC-23, AC-24)
Verify it: /check verify legal pages & cookie consent
Test it: /test legal pages & cookie consent

17. SEO for storefront pages · done

Make products findable: titles, descriptions, canonical links, sitemap, product rich results, and social share cards on every public page. Done when: every product and category page has unique metadata and structured product data, the sitemap lists all visible products, hidden products and admin pages are never indexed. spec 0018 · code in src/lib/seo/, src/features/catalog/seo.ts, app/sitemap.ts, app/robots.ts

Design it (spec): /architect SEO for storefront pages
Build it: /develop SEO for storefront pages
- Thin thread: metadataBase, the shared metadata helper, full product metadata and Product JSON-LD with Offers and shipping, a products only sitemap, robots with the production rule (AC-1, AC-2, AC-5 to AC-11, AC-20)
- Brand card, logo and icon; home, legal and search pages on the helper; Organization and WebSite JSON-LD (AC-3, AC-4, AC-15, AC-17)
- Listing canonicals and paged titles, category descriptions and BreadcrumbList (AC-12 to AC-14, AC-16)
- Full sitemap (home, legal, categories, images) and the hidden and private page checks (AC-18, AC-19, AC-21, AC-22)
Verify it: /check verify SEO for storefront pages (the Rich Results Test waits for the first preview deploy, a spec 0018 follow-up)
Test it: /test SEO for storefront pages

18. Analytics & error tracking · needs a decision

See how customers move through the store and know when something breaks. Done when: the funnel (view product, add to cart, start checkout, pay) is tracked with consent respected; front end and server errors, including failed payments, raise alerts.

Design it (spec): /architect analytics & error tracking

19. Production deploy

The last step: ship to Vercel and the production Supabase project, and turn on the production only settings every earlier slice left for deploy time. Done when: the production app runs on Vercel against production Supabase, and each production only item below is applied and checked there.

Build it: /develop production deploy
- Admin sign in, from the runbook docs/runbooks/admin-accounts.md: production Supabase auth settings, Resend SMTP, recovery template, redirect URLs, asymmetric JWT keys, the first real admin (spec 0004 AC-10, AC-11)
- Vercel Firewall rate limit on POST to /admin/sign-in, /admin/mfa, /admin/forgot-password: 10 per minute per IP, deny 10 minutes (spec 0004 AC-15)
- Vercel Firewall rate limit on POST /checkout (promo code Apply and Pay), generous enough for real Pay clicks (spec 0014 Follow-up)
Verify it: /check verify production deploy

Deferred

Out of scope for the current build pass, kept so the plan stays honest.

Tax / VAT calculation: per region tax rules; for now prices are shown tax inclusive in one country · needs a decision · GA
Admin roles & permissions: owner, staff, support with different rights · needs a decision
Zone or weight based shipping: rates by region or package weight · needs a decision
Several languages & currencies: selling abroad · needs a decision
Product reviews: customer ratings on product pages · needs a decision
Wishlist: save products for later · needs a decision
Return window and delivery time as data: real values so the product Offer can carry hasMerchantReturnPolicy and deliveryTime · from spec 0018
Dark mode: a dark token set with its own contrast pass and a theme switch; the semantic tokens rule keeps it a token change · needs a decision · from spec 0003
Sweep abandoned product image uploads: delete files in product-images that no image row and no order line references, older than a day, if storage cost grows · from spec 0009
Storefront listing in SQL: move search, filters and counts from the cached in memory index to SQL per request (pg_trgm, unaccent) once the catalog passes about 2,000 active products or the index nears the cache entry limit · needs a decision · from spec 0013
Trigram search indexes for admin orders: pg_trgm indexes on the searched order columns, once the list is measured as slow · from spec 0010
Redact customer data at Stripe: remove the name, email and address Stripe keeps on expired Checkout Sessions, if its redaction tooling fits · needs a decision · from spec 0008
Resend bounce and complaint webhooks: record bounced and complained on email_sends and show "Bounced" on the order page, once live · from spec 0011
Email sweep on its own 10 minute cron: when the project moves to Vercel Pro (feature 19) · from spec 0011
Customer email change: Supabase secure email change, keeping customers.email and order linking in step · needs a decision · from spec 0012
Order data retention and export: set the accounting retention period, extend the spec 0008 purge to settled orders past it, and offer account holders a data export · needs a decision · GA · from spec 0012
Admin customers page: search customers and see their orders, if support needs it · needs a decision · from spec 0012

Legend

The decision box. Every feature carries exactly one, the sub task whose label ends with (spec). Its wording varies (Design it (spec) normally, Decide the stack (spec) on Stack & architecture), so skills locate it by that (spec) suffix, never by an exact label. Every other box is an execution box and /architect never ticks one.

Feature lifecycle: the scope updates as a feature moves; each row is what it shows and who sets it:

State	Set by	The feature shows
`planned` · needs a decision	`/scope`	one box: `Design it (spec): /architect <feature>`
`in-progress` (designed)	`/architect` at spec capture	`Design it` ticked; spec linked; `Build it: /develop <feature>` + 2 to 5 milestones; the tier's closing boxes (`Verify it` Alpha+, `Test it` Beta+, `Review it` + `Document it` GA); any surfaced follow up enrolled
`in-progress` (building)	`/develop`	milestone sub boxes tick one by one; code pointer filled
`in-progress` (verified)	`/check verify`	`Build it` + milestones ticked; `Verify it` ticked
`done`	you, when you decide it is (any skill sets it when you say so); `/sync` reconciles	boxes you ran ticked, skipped ones marked skipped; the tier's last stage (`Prototype` → after `/develop`; `Alpha` → after `/check verify`; `Beta`/`GA` → after `/test`) is the suggested point to call it done; `/sync` captures conventions

Next step = the first unticked box (always a command or a tracked milestone).
needs a decision = run /architect first; otherwise straight to /develop (or /audit for standards & tooling). The tag drops once the spec is captured.
Atomic build tasks live in the spec's ## Build plan, not here: the scope carries only the milestone rollup.
Status planned → in-progress → done, plus existing (pre workflow) and dropped (de scoped, kept for history).
Approach tag beside a heading (e.g. · Facade) overrides the project default for that feature; no tag = inherits it.
Workflow tier tag beside a heading (e.g. · GA) sets that one feature's rigor above or below the project default; no tag inherits the default. It decides the feature's check boxes and each skill's next suggestion.
Workflow (header line) is the project default, what runs after /develop: Prototype = nothing (trust develop's own build time self check); Alpha = /check verify; Beta = /check verify then /test; GA = adds a fresh model /check review then /document. A feature built on an unratified decision (an Assumed spec) stays flagged, but that never blocks done.
Pointer line (spec <n> · code in <path>): the spec link added by /architect, the code path by /develop.

FilesExpand file tree

scope.md

Latest commit

History