create-baton 1.0.0

package/templates/skills/core/ui-ux/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: ui-ux
+description: >-
+  UI/UX design defaults and polish standards for AI-generated interfaces.
+  Covers layout, typography, color, responsive rules, component libraries,
+  and accessibility basics. Use when building UI, reviewing design quality,
+  or when screens look unpolished.
+---
+
+# UI/UX Skill — Look Good Out of the Gate
+
+> Every screen should look polished on first build. No "we'll fix the UI later."
+
+---
+
+## The Problem
+
+AI-generated UIs are functional but ugly. Common issues:
+- Inconsistent spacing and sizing
+- No visual hierarchy — everything looks the same importance
+- Missing loading, empty, and error states
+- Looks broken on mobile
+- No feedback when users click things
+
+**If it looks bad, users don't trust it — even if it works perfectly.**
+
+---
+
+## Design Defaults (Use Unless Told Otherwise)
+
+### Layout
+- **Mobile-first** — design for phone, scale up to desktop
+- **Max content width:** 1200px centered, with side padding
+- **Consistent spacing:** pick a scale (4, 8, 12, 16, 24, 32, 48, 64px) and stick to it
+- **White space is good** — when in doubt, add more breathing room
+
+### Typography
+- **One font family** — system font stack or one Google Font, never more
+- **3 sizes max** for body text: small (14px), normal (16px), large (18px)
+- **Headings:** clear size steps (h1: 36px, h2: 28px, h3: 22px)
+- **Line height:** 1.5 for body, 1.2 for headings
+- **Max line width:** 65-75 characters for readability
+
+### Color
+- **2-3 colors max** — primary, neutral, one accent
+- **Use opacity/shades** of your primary instead of adding more colors
+- **Text contrast:** minimum 4.5:1 ratio (WCAG AA)
+- **Don't convey meaning with color alone** — add icons or labels too
+
+### Components
+- **Use a component library** — shadcn/ui (recommended), Radix, or Headless UI
+- **Don't build custom components** when a library has them
+- **Consistent border radius** — pick one (6px or 8px) and use everywhere
+- **Consistent shadows** — one subtle shadow for elevation, not five different ones
+
+---
+
+## Every Screen Must Have
+
+### 1. Loading State
+```
+Show skeleton or spinner while data loads.
+Never show a blank screen or flash of unstyled content.
+```
+
+### 2. Empty State
+```
+When there's no data, show:
+- A clear message explaining what goes here
+- A call to action (button to create first item)
+Never show an empty table or blank page.
+```
+
+### 3. Error State
+```
+When something fails, show:
+- What went wrong (in human language, not error codes)
+- What to do about it (retry button, contact support, etc.)
+Never show a raw error message or silent failure.
+```
+
+### 4. Success Feedback
+```
+When an action succeeds:
+- Toast notification, or
+- Inline confirmation, or
+- Redirect with success message
+Never let the user wonder "did that work?"
+```
+
+---
+
+## Responsive Rules
+
+| Breakpoint | Width | Layout |
+|-----------|-------|--------|
+| Mobile | < 640px | Single column, stacked |
+| Tablet | 640-1024px | Adjusted spacing, may show sidebar |
+| Desktop | > 1024px | Full layout |
+
+**Test every screen at 375px width (iPhone SE).** If it breaks there, fix it.
+
+---
+
+## Quick Wins That Make Everything Look Better
+
+1. **Add padding to containers** — 16px mobile, 24px+ desktop
+2. **Align everything to a grid** — no random positioning
+3. **Use subtle borders or backgrounds** to separate sections, not heavy lines
+4. **Make buttons look clickable** — clear hover/active states
+5. **Size touch targets 44px minimum** — fingers are bigger than cursors
+6. **Add transitions** — 150ms ease on hover states, nothing flashy
+7. **Consistent icon style** — all outline OR all filled, never mixed (use Lucide)
+
+---
+
+## Don'ts
+
+| Don't | Do Instead |
+|-------|-----------|
+| Rainbow of colors | 2-3 color palette |
+| Five font sizes on one page | Consistent type scale |
+| Custom scrollbars, animations | Subtle, standard interactions |
+| Auto-playing anything | User-initiated actions |
+| Walls of text | Short copy, clear hierarchy |
+| Pixel-perfect custom everything | Component library + small tweaks |
+| Different button styles everywhere | One primary, one secondary, one ghost |
+
+---
+
+## Accessibility Basics (Non-Negotiable)
+
+- All images have `alt` text
+- All form inputs have labels (not just placeholders)
+- Keyboard navigation works (Tab through the page)
+- Focus states are visible (don't remove outline without replacing)
+- Color is not the only indicator (add icons/text to status)
+
+---
+
+## When User Doesn't Specify Design
+
+Default to:
+1. **Clean and minimal** — white/light gray background, dark text
+2. **shadcn/ui components** (if using React/Next.js)
+3. **Lucide icons** (consistent, clean)
+4. **Inter or system font**
+5. **Rounded corners (8px), subtle shadows**
+6. **Blue primary color** (#2563EB or similar)
+
+This gives a professional baseline. User can customize later.
+
+---
+
+*Last updated: Baton Protocol v3.1*

package/templates/skills/patterns/api-integration/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: api-integration
+description: >-
+  External API integration patterns. Covers retry logic, error handling,
+  AI/LLM API specifics, rate limiting, and environment variable management.
+  Use when integrating external APIs, calling AI model APIs, or when
+  dealing with API failures and rate limits.
+---
+
+# API Integration Skill
+
+> External APIs fail. Plan for it from line one.
+
+---
+
+## Before Writing Any API Code
+
+1. **Read the official documentation** — don't guess endpoints, auth methods, or model names
+2. **Check for SDKs** — official client libraries are always better than raw HTTP calls
+3. **Note rate limits** — know your ceiling before you hit it
+4. **Check pricing** — free tiers have limits, know what they are
+
+---
+
+## Retry Logic (Implement From the Start)
+
+Every external API call must have retry logic. Don't add it later when things break.
+
+```
+Minimum: 3 retry attempts
+Strategy: Exponential backoff (1s, 2s, 4s)
+Retry on: 429 (rate limit), 500, 502, 503, 504
+Don't retry: 400 (bad request), 401 (auth), 403 (forbidden), 404
+```
+
+### Pattern
+
+```
+try call → if transient error → wait → retry → if still failing → graceful error to user
+```
+
+Always log which attempt succeeded. If retries are frequent, something is wrong.
+
+---
+
+## AI/LLM API Specifics
+
+When calling AI model APIs (Gemini, OpenAI, Anthropic, etc.):
+
+### Token Limits
+- Set `max_tokens` higher than you think you need
+- Shorter prompts = more room for output
+- If responses feel cut off, you're hitting the limit
+
+### Check Finish Reasons
+```
+"stop" → completed normally ✓
+"length" → truncated — increase max_tokens
+"safety" → content filtered — adjust prompt
+"error" → something broke — retry
+```
+
+**Always check the finish reason.** Truncated responses without checking = silent bugs.
+
+### Prompt Efficiency
+- Shorter, clearer prompts perform better AND cost less
+- Put instructions first, data second
+- Don't repeat yourself in prompts
+- Use structured output (JSON mode) when parsing responses
+
+---
+
+## Error Handling
+
+### What Users Should See
+
+| Situation | Show User |
+|-----------|----------|
+| API timeout | "Taking longer than usual. Retrying..." |
+| Rate limited | "Busy right now. Trying again in a moment..." |
+| API down | "Service temporarily unavailable. Please try again." |
+| Bad response | "Something went wrong. Please try again." |
+| Auth failure | Nothing — this is a bug, log it, alert developer |
+
+**Never show raw API errors to users.** No stack traces, no error codes, no JSON blobs.
+
+### What Developers Should See
+
+Log everything:
+- Request timestamp
+- Response status code
+- Retry attempt number
+- Finish reason (for AI APIs)
+- Response time
+
+---
+
+## Environment Variables
+
+```
+API keys → environment variables, NEVER hardcoded
+Model names → environment variables (models change, keys don't)
+Base URLs → environment variables (staging vs production)
+```
+
+### Pattern
+```
+GEMINI_API_KEY=xxx
+GEMINI_MODEL=gemini-2.5-flash
+OPENAI_API_KEY=xxx
+OPENAI_MODEL=gpt-4o
+```
+
+Make the model name configurable. New models drop constantly.
+
+---
+
+## Rate Limiting Your Own Users
+
+If your app calls an external API per user request:
+- Add your own rate limiting (e.g., 10 requests/minute per user)
+- Queue requests if needed
+- Cache responses when possible (same input = same output)
+- Show remaining quota to users if applicable
+
+**Your free API tier is shared across ALL your users.** One heavy user can burn your quota.
+
+---
+
+## Checklist Before Shipping
+
+- [ ] All API keys in environment variables
+- [ ] Retry logic on every external call
+- [ ] Graceful error messages for users
+- [ ] Finish reason checked (AI APIs)
+- [ ] Rate limiting on user-facing endpoints
+- [ ] Timeouts set (don't wait forever)
+- [ ] Logging on failures
+- [ ] Tested with API returning errors (not just happy path)
+
+---
+
+*Last updated: Baton Protocol v3.1*

package/templates/skills/stacks/nextjs/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: nextjs
+description: >-
+  Next.js App Router patterns and conventions for production applications.
+  Covers Server Components, Server Actions, route groups, loading/error
+  states, and common pitfalls. Use when working with Next.js 14+,
+  React Server Components, or App Router projects.
+---
+
+# Next.js Skill File
+
+> Proven patterns from production Next.js projects. Check here before searching the web.
+
+---
+
+## Version Compatibility
+
+This file covers Next.js 14-16 with App Router. Update version notes as needed.
+
+---
+
+## Project Structure
+
+```
+src/
+├── app/
+│   ├── (auth)/           # Auth route group
+│   ├── (dashboard)/      # Main app route group
+│   ├── api/              # API routes
+│   ├── layout.tsx        # Root layout
+│   └── page.tsx          # Landing page
+├── components/
+│   ├── ui/               # shadcn/ui components
+│   └── [feature]/        # Feature-specific components
+├── lib/
+│   ├── actions/          # Server actions
+│   ├── db/               # Database utilities
+│   └── utils.ts          # Helper functions
+└── types/
+    └── index.ts          # Type definitions
+```
+
+---
+
+## Key Patterns
+
+### Server Components First
+
+Default to Server Components. Only use `'use client'` when you need:
+- useState, useEffect
+- Event handlers (onClick, onChange)
+- Browser APIs
+
+```tsx
+// Server Component (default) - can fetch data directly
+export default async function Page() {
+  const data = await getData()
+  return <div>{data}</div>
+}
+
+// Client Component - only when needed
+'use client'
+export function InteractiveButton() {
+  const [count, setCount] = useState(0)
+  return <button onClick={() => setCount(c => c + 1)}>{count}</button>
+}
+```
+
+### Server Actions for Mutations
+
+All data mutations go through Server Actions. Never mutate from client.
+
+```tsx
+// lib/actions/items.ts
+'use server'
+
+import { revalidatePath } from 'next/cache'
+import { z } from 'zod'
+
+const schema = z.object({
+  name: z.string().min(1),
+})
+
+export async function createItem(formData: FormData) {
+  const parsed = schema.safeParse({
+    name: formData.get('name'),
+  })
+
+  if (!parsed.success) {
+    return { success: false, error: 'Invalid input' }
+  }
+
+  // Database operation here
+
+  revalidatePath('/items')
+  return { success: true }
+}
+```
+
+### Route Groups for Layout Control
+
+Use `(groupName)` folders to share layouts without affecting URLs.
+
+```
+app/
+├── (marketing)/          # Marketing layout
+│   ├── layout.tsx
+│   ├── page.tsx          # → /
+│   └── pricing/page.tsx  # → /pricing
+└── (dashboard)/          # Dashboard layout
+    ├── layout.tsx
+    └── dashboard/page.tsx # → /dashboard
+```
+
+### Loading and Error States
+
+Every route group should have loading and error handling.
+
+```
+app/
+└── dashboard/
+    ├── page.tsx
+    ├── loading.tsx       # Shows while page loads
+    └── error.tsx         # Shows on error (must be 'use client')
+```
+
+---
+
+## Common Commands
+
+```bash
+# Development
+npm run dev
+
+# Build (always run before deploying)
+npm run build
+
+# Type check
+npx tsc --noEmit
+
+# Lint
+npm run lint
+```
+
+---
+
+## Pitfalls to Avoid
+
+### 1. Importing Server-Only Code in Client Components
+
+```tsx
+// BAD - will break
+'use client'
+import { db } from '@/lib/db'  // Server-only!
+
+// GOOD - use Server Actions
+'use client'
+import { getData } from '@/lib/actions/data'
+```
+
+### 2. Not Using revalidatePath After Mutations
+
+```tsx
+// BAD - UI won't update
+export async function createItem() {
+  await db.insert(...)
+  return { success: true }
+}
+
+// GOOD - UI updates
+export async function createItem() {
+  await db.insert(...)
+  revalidatePath('/items')
+  return { success: true }
+}
+```
+
+### 3. Using useEffect for Data Fetching
+
+```tsx
+// BAD - unnecessary client-side fetch
+'use client'
+export function Items() {
+  const [items, setItems] = useState([])
+  useEffect(() => {
+    fetch('/api/items').then(...)
+  }, [])
+}
+
+// GOOD - fetch in Server Component
+export default async function Items() {
+  const items = await getItems()
+  return <ItemsList items={items} />
+}
+```
+
+### 4. Forgetting 'use client' for Interactive Components
+
+If you use useState, useEffect, onClick, onChange — you need 'use client'.
+
+---
+
+## Recommended Libraries
+
+| Need | Library | Why |
+|------|---------|-----|
+| UI Components | shadcn/ui | Customizable, accessible, copy-paste |
+| Forms | react-hook-form + zod | Type-safe validation |
+| Styling | Tailwind CSS | Utility-first, fast |
+| Icons | Lucide React | Clean, consistent |
+| Date handling | date-fns | Lightweight, tree-shakeable |
+| Animation | Framer Motion | Powerful, declarative |
+
+---
+
+## Environment Variables
+
+```bash
+# .env.local (never commit)
+DATABASE_URL=
+NEXT_PUBLIC_SUPABASE_URL=      # NEXT_PUBLIC_ = exposed to client
+NEXT_PUBLIC_SUPABASE_ANON_KEY=
+SUPABASE_SERVICE_ROLE_KEY=      # No prefix = server-only
+```
+
+**Rule:** Never put sensitive keys in NEXT_PUBLIC_ variables.
+
+---
+
+*Last updated: Baton Protocol v3.1*