create-baton 1.0.0 → 1.1.0

package/templates/skills/domains/ecommerce/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: ecommerce
+description: >-
+  E-commerce patterns — product catalog, cart management, checkout flow,
+  inventory tracking, and order management. Load at Session 0 when building
+  an online store or marketplace. Stays loaded for the entire project lifecycle.
+---
+
+# E-Commerce Domain Skill
+
+> E-commerce is not a CRUD app with a checkout button. It's a system where money moves and inventory matters.
+
+---
+
+## Load This Skill When
+
+- User says they're building a store, marketplace, or selling products online
+- Project involves product listings, shopping cart, or checkout
+- Revenue model is transactional (per purchase, not subscription)
+
+---
+
+## Core Data Model (Session 0-1)
+
+### Minimum Tables
+
+```
+products           — What you're selling
+product_variants   — Size, color, etc. (optional, add when needed)
+orders             — Purchase records
+order_items        — Products in each order
+customers          — Buyers (may overlap with users)
+```
+
+### Product Schema
+
+```sql
+CREATE TABLE products (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  name TEXT NOT NULL,
+  slug TEXT UNIQUE NOT NULL,
+  description TEXT,
+  price_cents INTEGER NOT NULL,        -- Store in cents, ALWAYS
+  compare_at_price_cents INTEGER,      -- Original price for "sale" display
+  currency TEXT DEFAULT 'USD',
+  status TEXT DEFAULT 'draft',         -- draft | active | archived
+  inventory_count INTEGER DEFAULT 0,
+  images JSONB DEFAULT '[]',
+  metadata JSONB DEFAULT '{}',
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  updated_at TIMESTAMPTZ DEFAULT NOW()
+);
+```
+
+**Critical rules:**
+- Store prices in smallest currency unit (cents, fils, pence)
+- Never use floating point for money
+- Products have statuses — don't show drafts to customers
+
+---
+
+## Product Display (Session 1-3)
+
+### Product Listing Page
+
+Show:
+- Product image (first image, optimized)
+- Product name
+- Price (formatted with currency)
+- "Sale" badge if compare_at_price exists
+- "Out of stock" badge if inventory_count = 0
+
+### Product Detail Page
+
+Show:
+- Image gallery (swipeable on mobile)
+- Name, price, description
+- Variant selector (if applicable)
+- Add to cart button (disabled if out of stock)
+- Quantity selector
+
+**Price display helper:**
+```typescript
+function formatPrice(cents: number, currency = 'USD'): string {
+  return new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency,
+  }).format(cents / 100);
+}
+```
+
+---
+
+## Cart (Session 2-3)
+
+### Cart Strategy
+
+| Approach | Pros | Cons |
+|----------|------|------|
+| **localStorage** | Simple, no auth needed | Lost on device switch |
+| **Database** | Persists, works cross-device | Needs auth or session ID |
+| **Hybrid** | localStorage for guests, DB for logged-in | More complex |
+
+**Default:** localStorage for MVP. Move to database when users ask for saved carts.
+
+### Cart Data Structure
+
+```typescript
+interface CartItem {
+  productId: string;
+  variantId?: string;
+  quantity: number;
+  priceAtAdd: number;  // Price when added (prices can change)
+}
+```
+
+### Cart Rules
+
+- Validate inventory before checkout (not just at add-to-cart)
+- Show item count in header/nav always
+- Let users update quantity or remove items
+- Show subtotal, update on every change
+- Don't clear cart on page refresh
+
+---
+
+## Checkout (Session 3-5)
+
+### Checkout Flow
+
+```
+Cart → Shipping info → Payment → Confirmation
+```
+
+Keep it to ONE page if possible. Multi-step checkout kills conversion.
+
+### Use Stripe Checkout
+
+Don't build a custom payment form. Stripe Checkout handles:
+- Card input (PCI compliant)
+- Apple Pay, Google Pay
+- 3D Secure
+- Tax calculation
+- Receipt emails
+
+```typescript
+// Create checkout session
+const session = await stripe.checkout.sessions.create({
+  mode: 'payment',
+  line_items: cartItems.map(item => ({
+    price_data: {
+      currency: 'usd',
+      product_data: { name: item.name },
+      unit_amount: item.priceAtAdd,
+    },
+    quantity: item.quantity,
+  })),
+  success_url: `${baseUrl}/order/success?session_id={CHECKOUT_SESSION_ID}`,
+  cancel_url: `${baseUrl}/cart`,
+});
+```
+
+### After Payment (Webhook)
+
+```
+Payment confirmed →
+  Create order record →
+    Decrement inventory →
+      Send confirmation email →
+        Clear cart
+```
+
+**Critical:** Decrement inventory in the webhook, not at checkout start. Failed payments shouldn't reduce stock.
+
+---
+
+## Order Management (Session 4-6)
+
+### Order Statuses
+
+```
+pending → confirmed → processing → shipped → delivered
+                   ↘ cancelled
+                   ↘ refunded
+```
+
+### Order Schema
+
+```sql
+CREATE TABLE orders (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  customer_id UUID REFERENCES customers(id),
+  status TEXT DEFAULT 'pending',
+  subtotal_cents INTEGER NOT NULL,
+  shipping_cents INTEGER DEFAULT 0,
+  tax_cents INTEGER DEFAULT 0,
+  total_cents INTEGER NOT NULL,
+  shipping_address JSONB,
+  stripe_session_id TEXT,
+  created_at TIMESTAMPTZ DEFAULT NOW()
+);
+```
+
+### What Customers Need
+
+- Order confirmation page (immediately after checkout)
+- Order history page (list of past orders)
+- Order detail page (items, status, tracking)
+- Email notifications (confirmation, shipped, delivered)
+
+### What Admin Needs
+
+- Order list with filters (status, date range)
+- Order detail with ability to update status
+- Basic revenue dashboard (total sales, order count)
+
+---
+
+## Inventory (Session 3-5)
+
+### Simple Inventory Rules
+
+- Track `inventory_count` on each product
+- Decrement on confirmed order (webhook)
+- Increment on cancellation/refund
+- Show "Out of stock" when count = 0
+- Show "Low stock" when count < threshold (e.g., 5)
+
+### Don't Over-Build
+
+Skip these until you actually need them:
+- Warehouse management
+- Multi-location inventory
+- Automated reordering
+- Batch/lot tracking
+
+---
+
+## Search and Filtering (Session 4-6)
+
+### Minimum Viable Search
+
+- Text search on product name + description
+- Filter by category (if categories exist)
+- Sort by price (low-high, high-low) and newest
+
+### Don't Build Yet
+
+- Faceted search (wait for 100+ products)
+- AI-powered recommendations
+- Elasticsearch/Algolia (use database full-text search first)
+
+---
+
+## Session Checkpoints
+
+### Session 3: Storefront Check
+- [ ] Products display correctly
+- [ ] Cart works (add, remove, update quantity)
+- [ ] Price formatting is correct everywhere
+
+### Session 5: Checkout Check
+- [ ] Stripe Checkout works (test mode)
+- [ ] Webhook creates orders and decrements inventory
+- [ ] Order confirmation page shows after payment
+- [ ] Cart clears after successful purchase
+
+### Session 8: Pre-Launch Check
+- [ ] Real products loaded
+- [ ] Stripe in live mode
+- [ ] Order notification emails working
+- [ ] Admin can view and manage orders
+- [ ] Inventory tracking accurate
+
+---
+
+*Last updated: Baton Protocol v3.1*

package/templates/skills/domains/portfolio/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: portfolio
+description: >-
+  Portfolio and personal brand site patterns — case studies, project showcases,
+  contact forms, and performance optimization. Load at Session 0 when building
+  a portfolio, personal site, or creative showcase. Stays loaded entire lifecycle.
+---
+
+# Portfolio Domain Skill
+
+> A portfolio is a sales page for your skills. Every design choice should answer: "Would I hire this person?"
+
+---
+
+## Load This Skill When
+
+- User says they're building a portfolio, personal site, or showcase
+- Project is about presenting work, not building a product
+- Goal is impressions, not recurring revenue
+
+---
+
+## What Makes a Good Portfolio (Session 0)
+
+### The 5-Second Test
+
+A visitor decides in 5 seconds:
+1. **Who are you?** (name + role)
+2. **What do you do?** (one sentence)
+3. **Can I see proof?** (projects visible immediately)
+
+If any answer is missing above the fold, the site fails.
+
+### Content Priority (in order)
+
+1. Name + title + one-line bio
+2. 3-6 best projects (not everything you've ever done)
+3. Brief about section
+4. Contact method
+5. Optional: blog, resume, testimonials
+
+---
+
+## Site Structure (Session 1)
+
+### Simple and Fast
+
+```
+/                   — Hero + project grid
+/projects/[slug]    — Individual case study
+/about              — Bio, skills, background
+/contact            — Contact form or links
+```
+
+That's it. Don't add pages until you have a reason.
+
+### Navigation
+
+- Max 4 nav items: Work, About, Contact, [Blog/Resume]
+- Logo/name links home
+- Mobile: hamburger menu or bottom nav
+- Current page indicator
+
+---
+
+## Project Showcase (Session 1-3)
+
+### Project Card (Grid View)
+
+Each card shows:
+- Featured image/screenshot (16:9 or 4:3, consistent ratio)
+- Project name
+- One-line description
+- Tech tags (optional, subtle)
+
+### Case Study Page
+
+Structure each project page the same way:
+
+```markdown
+## [Project Name]
+
+**One-liner:** What it is and who it's for
+
+**The Challenge:** What problem needed solving (2-3 sentences)
+
+**The Solution:** What you built and key decisions (3-5 sentences)
+
+**Key Features:** 3-5 bullet points with screenshots
+
+**Results:** Numbers if possible (users, revenue, performance)
+
+**Tech Stack:** List of technologies used
+```
+
+**Rules:**
+- Lead with visuals — screenshot or demo above the fold
+- Keep text short — visitors skim, they don't read
+- Show 3-6 projects maximum — quality over quantity
+- Order by impressiveness, not chronology
+
+---
+
+## Design Standards (Session 1-2)
+
+### Typography
+
+- Large heading for name (40-60px)
+- Clean body font (16-18px, system font or Inter)
+- Generous line height (1.6-1.8 for body)
+- Max reading width: 680px for text blocks
+
+### Color
+
+- Dark background with light text (modern, dramatic) OR
+- Light background with dark text (clean, professional)
+- One accent color for links and CTAs
+- Don't use more than 3 colors total
+
+### Animation
+
+- Subtle fade-in on scroll (IntersectionObserver)
+- Hover effects on project cards (scale 1.02, shadow)
+- Page transitions (optional, keep fast)
+- **Never:** Auto-playing video, parallax that causes jank, loading screens
+
+### Performance
+
+Portfolio sites MUST be fast. Target:
+- First paint under 1 second
+- Full load under 2 seconds
+- Lighthouse performance score 90+
+
+Use Next.js Image component, lazy loading, and static generation.
+
+---
+
+## Contact (Session 2-3)
+
+### Options (Pick One)
+
+| Method | Pros | Cons |
+|--------|------|------|
+| **Email link** | Simplest, no backend needed | Spam exposure |
+| **Contact form** | Professional, controlled | Needs backend/service |
+| **Calendly embed** | Direct booking | Feels salesy |
+| **Social links** | Multiple channels | No single inbox |
+
+**Default for most:** Contact form with email notification.
+
+### Contact Form (If Used)
+
+Fields:
+- Name (required)
+- Email (required)
+- Message (required)
+- That's it. No phone, no company, no dropdown menus.
+
+Use a form service (Formspree, Resend, or server action) to avoid building a backend just for contact.
+
+---
+
+## SEO for Portfolios (Session 3+)
+
+### Minimum
+
+- Page title: "[Name] — [Role]" (e.g., "Sarah Chen — Product Designer")
+- Meta description: One sentence about what you do
+- Open Graph image: Screenshot of your homepage or a branded card
+- Sitemap generated automatically (Next.js does this)
+
+### Project Pages
+
+- Each project gets its own URL (`/projects/project-name`)
+- Unique title and description per project
+- Featured image as OG image
+
+---
+
+## Blog (Optional, Session 5+)
+
+Only add a blog if the user specifically wants one. Don't suggest it.
+
+If added:
+- Markdown or MDX files (no CMS unless requested)
+- Simple list page, individual post pages
+- Date, title, reading time
+- No categories, tags, or comments until needed
+
+---
+
+## Session Checkpoints
+
+### Session 2: Foundation Check
+- [ ] Homepage shows name, role, and project grid
+- [ ] At least 2 project case studies exist
+- [ ] Mobile responsive (test at 375px)
+
+### Session 4: Polish Check
+- [ ] All projects have case study pages
+- [ ] Contact method works
+- [ ] About page exists
+- [ ] Lighthouse performance 90+
+
+### Session 6: Launch Check
+- [ ] Custom domain configured
+- [ ] OG images set for all pages
+- [ ] Tested on real phones (not just browser resize)
+- [ ] Ask someone else to review for 30 seconds
+
+---
+
+*Last updated: Baton Protocol v3.1*