start-vibing-stacks 1.5.1 → 1.7.0

package/dist/setup.js

@@ -176,7 +176,7 @@ export async function setupProject(projectDir, config, options = {}) {
                         hooks: [
                             {
                                 type: 'command',
-                                command: 'npx tsx .claude/hooks/run-hook.ts user-prompt-submit',
+                                command: 'bash .claude/hooks/run-hook.sh user-prompt-submit',
                                 timeout: 10,
                             },
                         ],
@@ -187,7 +187,7 @@ export async function setupProject(projectDir, config, options = {}) {
                         hooks: [
                             {
                                 type: 'command',
-                                command: 'npx tsx .claude/hooks/run-hook.ts stop-validator',
+                                command: 'bash .claude/hooks/run-hook.sh stop-validator',
                                 timeout: 30,
                             },
                         ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-vibing-stacks",
-  "version": "1.5.1",
+  "version": "1.7.0",
   "description": "AI-powered multi-stack dev workflow for Claude Code. Supports PHP, Node.js, Python and more.",
   "type": "module",
   "bin": {

package/stacks/_shared/skills/hook-development/SKILL.md

@@ -0,0 +1,88 @@
+# Hook Development — Claude Code Hooks
+
+**ALWAYS invoke when creating or modifying Claude Code hooks.**
+
+## Hook Types
+
+| Event | When | Use Case |
+|-------|------|----------|
+| `UserPromptSubmit` | Before prompt is sent | Inject workflow, validate input |
+| `Stop` | Before task completion | Validate state, block if dirty |
+| `PreToolUse` | Before tool execution | Approve/block dangerous tools |
+| `PostToolUse` | After tool execution | Log, validate output |
+
+## File Structure
+
+```
+.claude/hooks/
+├── run-hook.sh              # Entry point (bash → bun/tsx fallback)
+├── user-prompt-submit.ts    # Prompt injection
+└── stop-validator.ts        # Task completion gate
+```
+
+## Hook Input (stdin JSON)
+
+```typescript
+// UserPromptSubmit
+interface PromptInput {
+  user_prompt: string;
+  session_id: string;
+}
+
+// Stop
+interface StopInput {
+  stop_hook_active?: boolean;  // Cycle detection
+  transcript?: string;
+}
+```
+
+## Hook Output (stdout JSON)
+
+```typescript
+// UserPromptSubmit — inject system message
+{ "continue": true, "systemMessage": "WORKFLOW: ..." }
+
+// Stop — approve or block
+{ "continue": false, "decision": "approve", "reason": "All checks passed" }
+{ "continue": true, "decision": "block", "reason": "Uncommitted files" }
+```
+
+## Template: Stop Validator
+
+```typescript
+#!/usr/bin/env node
+import { execSync } from 'child_process';
+
+function cmd(c: string): string {
+  try { return execSync(c, { encoding: 'utf8' }).trim(); } catch { return ''; }
+}
+
+const branch = cmd('git rev-parse --abbrev-ref HEAD');
+const dirty = cmd('git status --porcelain');
+
+const result = (!dirty && (branch === 'main' || branch === 'master'))
+  ? { continue: false, decision: 'approve', reason: 'Clean main branch' }
+  : { continue: true, decision: 'block', reason: `Branch: ${branch}, dirty: ${!!dirty}` };
+
+console.log(JSON.stringify(result));
+```
+
+## settings.json Registration
+
+```json
+{
+  "hooks": {
+    "Stop": [{ "hooks": [{ "type": "command", "command": "bash .claude/hooks/run-hook.sh stop-validator", "timeout": 30 }] }],
+    "UserPromptSubmit": [{ "matcher": "", "hooks": [{ "type": "command", "command": "bash .claude/hooks/run-hook.sh user-prompt-submit", "timeout": 10 }] }]
+  }
+}
+```
+
+## Rules
+
+1. **Always use `run-hook.sh` as entry** — handles bun/tsx fallback
+2. **Read stdin with timeout** — hooks must not hang
+3. **Exit 0 always** — non-zero kills the session
+4. **Output valid JSON to stdout** — Claude Code parses it
+5. **Cycle detection** — check `stop_hook_active` flag in Stop hooks
+6. **Keep hooks fast** — timeout applies (10s for prompt, 30s for stop)

package/stacks/_shared/skills/playwright-automation/SKILL.md

@@ -0,0 +1,90 @@
+# Playwright Automation — E2E Testing
+
+**ALWAYS invoke when writing E2E tests or browser automation.**
+
+## Structure
+
+```
+tests/e2e/
+├── fixtures/          # Auth, DB cleanup, custom fixtures
+├── pages/             # Page Object Model
+├── flows/             # User journey tests
+├── api/               # API-only tests
+└── playwright.config.ts
+```
+
+## Page Object Model
+
+```typescript
+// tests/e2e/pages/base.page.ts
+import { type Page, type Locator, expect } from '@playwright/test';
+
+export abstract class BasePage {
+  protected readonly page: Page;
+  constructor(page: Page) { this.page = page; }
+
+  get loadingSpinner(): Locator { return this.page.getByTestId('loading-spinner'); }
+  get errorMessage(): Locator { return this.page.getByTestId('error-message'); }
+
+  async waitForLoad(): Promise<void> {
+    await this.loadingSpinner.waitFor({ state: 'hidden' });
+  }
+
+  async goto(path: string): Promise<void> {
+    await this.page.goto(path);
+    await this.waitForLoad();
+  }
+}
+```
+
+## Auth Fixture
+
+```typescript
+export function generateTestUser(): TestUser {
+  const ts = Date.now();
+  const rand = Math.random().toString(36).substring(7);
+  return {
+    name: `Test User ${ts}`,
+    email: `testuser_${ts}_${rand}@test.com`,
+    password: 'TestPassword123!',
+  };
+}
+```
+
+## Multi-Viewport Testing
+
+```typescript
+const viewports = [
+  { name: 'mobile', width: 375, height: 667 },
+  { name: 'tablet', width: 768, height: 1024 },
+  { name: 'desktop', width: 1280, height: 800 },
+] as const;
+
+for (const viewport of viewports) {
+  test.describe(`Responsive - ${viewport.name}`, () => {
+    test.use({ viewport: { width: viewport.width, height: viewport.height } });
+    test('navigation adapts', async ({ page }) => { /* ... */ });
+  });
+}
+```
+
+## Required data-testid
+
+```html
+<input data-testid="email-input" />
+<input data-testid="password-input" />
+<button data-testid="submit-button" />
+<div data-testid="error-message" />
+<div data-testid="success-message" />
+<div data-testid="loading-spinner" />
+<nav data-testid="sidebar" />
+<button data-testid="hamburger-menu" />
+```
+
+## FORBIDDEN
+
+1. **Hardcoded test data** — generate unique data with timestamps
+2. **`.skip()` or `.only()`** — never in committed code
+3. **No cleanup** — always track + clean created data
+4. **Mocked auth** — use real authentication flows
+5. **Single viewport** — test mobile + tablet + desktop

package/stacks/_shared/skills/test-coverage/SKILL.md

@@ -0,0 +1,67 @@
+# Test Coverage — Testing Management
+
+**ALWAYS invoke AFTER implementing any feature. Do NOT skip.**
+
+## Critical Rules
+
+1. **CLEANUP ALL TEST DATA** — fixture-based tracking
+2. **VERIFY IN DATABASE** — check DB state after UI actions
+3. **TEST ALL VIEWPORTS** — desktop, tablet, mobile minimum
+4. **REAL AUTH ONLY** — never mock authentication
+5. **UNIQUE DATA** — timestamps in emails/names
+6. **NO `.skip()`** — never in committed code
+
+## Files That NEED Tests
+
+| Type | Test Expected | Required |
+|------|--------------|----------|
+| API Route | Unit + E2E | **YES** |
+| Model/Entity | Unit | **YES** |
+| Page/View | E2E flow | **YES** |
+| Component (interactive) | E2E | YES |
+| Hook/Service | Unit | YES |
+| Utility (exported) | Unit | YES |
+
+## Required E2E Flows
+
+- [ ] Registration — create user, verify in DB
+- [ ] Login/Logout — auth state changes
+- [ ] CRUD Create — item created, visible, in DB
+- [ ] CRUD Read — item displayed correctly
+- [ ] CRUD Update — changes reflected in DB
+- [ ] CRUD Delete — removed from DB
+- [ ] Permissions — forbidden requests blocked
+- [ ] Responsive — works on all viewports
+
+## Stack-Specific Commands
+
+### PHP (PHPUnit + Pest)
+```bash
+./vendor/bin/phpunit
+./vendor/bin/pest --coverage --min=70
+```
+
+### Node.js (Vitest + Playwright)
+```bash
+npx vitest run --coverage
+npx playwright test
+npx playwright test --ui
+```
+
+## Before Commit Checklist
+
+- [ ] All new features have tests?
+- [ ] Tests use fixtures for cleanup?
+- [ ] Database state verified after UI actions?
+- [ ] Tests run on all viewports?
+- [ ] Coverage threshold met (≥70%)?
+- [ ] No `.skip()` in tests?
+- [ ] All tests passing?
+
+## FORBIDDEN
+
+1. **Skipping tests** — `test.skip()`, `.only()`
+2. **Mocking auth** — use real authentication
+3. **Fixed test users** — `test@test.com` → generate unique
+4. **No cleanup** — orphaned test data
+5. **No DB validation** — trusting UI without checking DB

package/stacks/frontend/react/skills/react-patterns/SKILL.md

@@ -0,0 +1,113 @@
+# React Patterns — Modern Component Architecture
+
+**ALWAYS invoke when writing React components, hooks, or state management.**
+
+## Component Patterns
+
+### Compound Components
+```tsx
+const TabsContext = createContext<TabsContextValue | null>(null);
+
+function Tabs({ children, defaultTab }: { children: ReactNode; defaultTab: string }) {
+  const [activeTab, setActiveTab] = useState(defaultTab);
+  return (
+    <TabsContext.Provider value={{ activeTab, setActiveTab }}>
+      <div className="tabs">{children}</div>
+    </TabsContext.Provider>
+  );
+}
+// + TabList, Tab, TabPanel components using useContext(TabsContext)
+```
+
+### Generic List Component
+```tsx
+interface ListProps<T> {
+  items: T[];
+  renderItem: (item: T) => ReactNode;
+  keyExtractor: (item: T) => string;
+}
+
+function List<T>({ items, renderItem, keyExtractor }: ListProps<T>) {
+  return <ul>{items.map(item => <li key={keyExtractor(item)}>{renderItem(item)}</li>)}</ul>;
+}
+```
+
+## Custom Hooks
+
+```tsx
+// useLocalStorage
+function useLocalStorage<T>(key: string, initial: T) {
+  const [value, setValue] = useState<T>(() => {
+    if (typeof window === 'undefined') return initial;
+    try { return JSON.parse(window.localStorage.getItem(key) ?? '') } catch { return initial }
+  });
+  const set = useCallback((v: T | ((val: T) => T)) => {
+    setValue(prev => {
+      const next = v instanceof Function ? v(prev) : v;
+      window.localStorage.setItem(key, JSON.stringify(next));
+      return next;
+    });
+  }, [key]);
+  return [value, set] as const;
+}
+
+// useDebounce
+function useDebounce<T>(value: T, delay: number): T {
+  const [debounced, setDebounced] = useState(value);
+  useEffect(() => { const t = setTimeout(() => setDebounced(value), delay); return () => clearTimeout(t); }, [value, delay]);
+  return debounced;
+}
+```
+
+## State Management
+
+### useReducer for Complex State
+```tsx
+type Action =
+  | { type: 'FETCH_START' }
+  | { type: 'FETCH_SUCCESS'; payload: Item[] }
+  | { type: 'FETCH_ERROR'; payload: string };
+
+function reducer(state: State, action: Action): State {
+  switch (action.type) {
+    case 'FETCH_START': return { ...state, loading: true, error: null };
+    case 'FETCH_SUCCESS': return { ...state, loading: false, items: action.payload };
+    case 'FETCH_ERROR': return { ...state, loading: false, error: action.payload };
+  }
+}
+```
+
+### Context (avoid prop drilling)
+```tsx
+const AppContext = createContext<AppContextValue | undefined>(undefined);
+export function useApp() {
+  const ctx = useContext(AppContext);
+  if (!ctx) throw new Error('useApp must be used within AppProvider');
+  return ctx;
+}
+```
+
+## Performance
+
+```tsx
+// memo — prevent re-renders
+const ExpensiveList = memo(function ExpensiveList({ items }: { items: Item[] }) { ... });
+
+// useMemo — expensive calculations
+const processed = useMemo(() => data.map(d => expensiveCalc(d)), [data]);
+
+// useCallback — stable refs
+const handleClick = useCallback(() => setCount(c => c + 1), []);
+
+// Code splitting
+const Heavy = lazy(() => import('./HeavyComponent'));
+<Suspense fallback={<Loading />}><Heavy /></Suspense>
+```
+
+## FORBIDDEN
+
+1. **Class components** — function components only
+2. **Prop drilling** — use context or composition
+3. **Inline objects/functions in JSX** — causes re-renders
+4. **useEffect for derived state** — use useMemo
+5. **Mutating state directly** — always setState/dispatch

package/stacks/frontend/react/skills/shadcn-ui/SKILL.md

@@ -0,0 +1,92 @@
+# shadcn/ui — Component Library Patterns
+
+**ALWAYS invoke when adding or modifying shadcn/ui components.**
+
+## Installation
+
+```bash
+npx shadcn@latest init
+npx shadcn@latest add button card dialog input
+```
+
+## Theming
+
+```css
+/* globals.css — CSS variables for theming */
+@layer base {
+  :root {
+    --background: 0 0% 100%;
+    --foreground: 222.2 84% 4.9%;
+    --primary: 222.2 47.4% 11.2%;
+    --primary-foreground: 210 40% 98%;
+    --muted: 210 40% 96.1%;
+    --muted-foreground: 215.4 16.3% 46.9%;
+    --border: 214.3 31.8% 91.4%;
+    --ring: 222.2 84% 4.9%;
+    --radius: 0.5rem;
+  }
+  .dark {
+    --background: 222.2 84% 4.9%;
+    --foreground: 210 40% 98%;
+    --primary: 210 40% 98%;
+    --primary-foreground: 222.2 47.4% 11.2%;
+  }
+}
+```
+
+## Component Customization
+
+```tsx
+// CORRECT — extend via className + variants
+import { Button } from '@/components/ui/button';
+<Button variant="outline" size="lg" className="rounded-full">Custom</Button>
+
+// WRONG — modify component source for one-off styles
+```
+
+## Composition Pattern
+
+```tsx
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
+import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogTrigger } from '@/components/ui/dialog';
+
+// Compose primitives, don't create monolithic components
+<Dialog>
+  <DialogTrigger asChild>
+    <Button variant="outline">Open</Button>
+  </DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Title</DialogTitle>
+    </DialogHeader>
+    <Card><CardContent>...</CardContent></Card>
+  </DialogContent>
+</Dialog>
+```
+
+## Form Pattern (with Zod)
+
+```tsx
+import { Form, FormControl, FormField, FormItem, FormLabel, FormMessage } from '@/components/ui/form';
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+
+const form = useForm<z.infer<typeof schema>>({ resolver: zodResolver(schema) });
+
+<Form {...form}>
+  <FormField control={form.control} name="email" render={({ field }) => (
+    <FormItem>
+      <FormLabel>Email</FormLabel>
+      <FormControl><Input {...field} /></FormControl>
+      <FormMessage />
+    </FormItem>
+  )} />
+</Form>
+```
+
+## FORBIDDEN
+
+1. **Modifying component source for one-off needs** — use className/variants
+2. **Installing without init** — always `npx shadcn@latest init` first
+3. **Ignoring dark mode** — all components must work in both themes
+4. **Skipping accessibility** — shadcn components have built-in a11y, don't break it

package/stacks/frontend/react/skills/tailwind-patterns/SKILL.md

@@ -0,0 +1,94 @@
+# Tailwind Patterns — Utility-First CSS
+
+**ALWAYS invoke when writing Tailwind CSS classes.**
+
+## Mobile-First Breakpoints
+
+```
+sm: 640px → md: 768px → lg: 1024px → xl: 1280px → 2xl: 1536px
+```
+
+```tsx
+<div className="w-full md:w-1/2 lg:w-1/3 xl:w-1/4">
+  {/* Mobile: full → Tablet: half → Desktop: third → Large: quarter */}
+</div>
+```
+
+## Layout Patterns
+
+### Flexbox
+```tsx
+// Center
+<div className="flex items-center justify-center h-screen" />
+
+// Responsive direction
+<div className="flex flex-col md:flex-row gap-4" />
+```
+
+### Grid
+```tsx
+// Responsive grid
+<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4" />
+
+// Auto-fit
+<div className="grid grid-cols-[repeat(auto-fit,minmax(300px,1fr))] gap-4" />
+```
+
+## Dark Mode
+
+```tsx
+<div className="bg-white dark:bg-gray-900 text-gray-900 dark:text-white">
+  <p className="text-gray-600 dark:text-gray-300">Adapts to theme</p>
+</div>
+```
+
+## Component Patterns
+
+### Card
+```tsx
+<div className="bg-white dark:bg-gray-800 rounded-lg shadow-md p-6 border border-gray-200 dark:border-gray-700 hover:shadow-lg transition-shadow">
+```
+
+### Button
+```tsx
+<button className="bg-primary text-primary-foreground px-4 py-2 rounded-md font-medium hover:bg-primary/90 focus:outline-none focus:ring-2 focus:ring-primary focus:ring-offset-2 disabled:opacity-50 disabled:cursor-not-allowed transition-colors">
+```
+
+### Input
+```tsx
+<input className="w-full px-3 py-2 bg-white dark:bg-gray-900 border border-gray-300 dark:border-gray-700 rounded-md text-gray-900 dark:text-white placeholder:text-gray-400 focus:outline-none focus:ring-2 focus:ring-primary focus:border-transparent" />
+```
+
+## Animations
+
+```tsx
+<Loader className="h-5 w-5 animate-spin" />           // Spinner
+<div className="h-4 w-24 bg-gray-200 animate-pulse" /> // Skeleton
+```
+
+### Custom (tailwind.config.js)
+```js
+animation: {
+  'fade-in': 'fadeIn 0.3s ease-in-out',
+  'slide-up': 'slideUp 0.3s ease-out',
+},
+keyframes: {
+  fadeIn: { '0%': { opacity: '0' }, '100%': { opacity: '1' } },
+  slideUp: { '0%': { transform: 'translateY(10px)', opacity: '0' }, '100%': { transform: 'translateY(0)', opacity: '1' } },
+}
+```
+
+## Show/Hide Responsive
+
+```tsx
+<div className="hidden lg:block">Desktop only</div>
+<div className="block lg:hidden">Mobile only</div>
+<span className="sr-only">Screen reader only</span>
+```
+
+## FORBIDDEN
+
+1. **`!important`** — fix specificity properly
+2. **Arbitrary values when utilities exist** — use the scale
+3. **Mixing raw CSS with Tailwind** — stick to utilities
+4. **Inconsistent spacing** — follow the 4px scale (p-1=4px, p-2=8px, p-4=16px)

package/stacks/nodejs/skills/bun-runtime/SKILL.md

@@ -0,0 +1,86 @@
+# Bun Runtime — Fast JavaScript Runtime
+
+**ALWAYS invoke when using Bun for scripts, packages, bundling, or testing.**
+
+## Package Management
+
+```bash
+bun install               # Install deps (replaces npm install)
+bun add zod               # Add dependency
+bun add -D vitest         # Add dev dependency
+bun remove lodash         # Remove
+bun update                # Update all
+```
+
+## Scripts
+
+```bash
+bun run dev               # Run script from package.json
+bun run build
+bun --watch src/index.ts  # Watch mode
+```
+
+## TypeScript (native, no config needed)
+
+```typescript
+// Bun runs .ts files directly — no tsc/tsx needed
+// bun src/index.ts
+
+import { serve } from 'bun';
+
+serve({
+  port: 3000,
+  fetch(req) {
+    const url = new URL(req.url);
+    if (url.pathname === '/api/health') {
+      return Response.json({ status: 'ok' });
+    }
+    return new Response('Not Found', { status: 404 });
+  },
+});
+```
+
+## File I/O (Bun APIs)
+
+```typescript
+// Fast file operations
+const content = await Bun.file('data.json').text();
+const parsed = await Bun.file('data.json').json();
+await Bun.write('output.txt', 'Hello');
+
+// Glob
+const glob = new Bun.Glob('**/*.ts');
+for await (const file of glob.scan('.')) { console.log(file); }
+```
+
+## Testing (built-in)
+
+```typescript
+// *.test.ts — bun test
+import { describe, it, expect } from 'bun:test';
+
+describe('math', () => {
+  it('adds', () => expect(1 + 1).toBe(2));
+});
+```
+
+```bash
+bun test                  # Run all tests
+bun test --coverage       # With coverage
+bun test --watch          # Watch mode
+```
+
+## Environment Variables
+
+```typescript
+// .env loaded automatically
+const apiKey = Bun.env['API_KEY'];      // Bun.env (recommended)
+const dbUrl = process.env['DATABASE_URL']; // Also works
+```
+
+## FORBIDDEN
+
+1. **`node` command when `bun` works** — prefer bun for speed
+2. **`npx` when `bunx` works** — `bunx` is faster
+3. **Manual .env loading** — Bun loads `.env` automatically
+4. **CommonJS `require()`** — use ESM `import`

package/stacks/nodejs/skills/mongoose-patterns/SKILL.md

@@ -0,0 +1,77 @@
+# Mongoose Patterns — MongoDB ODM
+
+**ALWAYS invoke when writing Mongoose schemas, queries, or aggregations.**
+
+## Schema Pattern
+
+```typescript
+import { Schema, model, type InferSchemaType } from 'mongoose';
+
+const userSchema = new Schema({
+  name: { type: String, required: true, trim: true, minlength: 2 },
+  email: { type: String, required: true, unique: true, lowercase: true, index: true },
+  role: { type: String, enum: ['admin', 'user', 'moderator'] as const, default: 'user' },
+  profile: {
+    avatar: String,
+    bio: { type: String, maxlength: 500 },
+  },
+  tags: [{ type: String, index: true }],
+  isActive: { type: Boolean, default: true, index: true },
+}, {
+  timestamps: true,         // createdAt, updatedAt
+  toJSON: { virtuals: true, transform: (_, ret) => { delete ret.__v; return ret; } },
+});
+
+// Compound index
+userSchema.index({ email: 1, isActive: 1 });
+// Text index for search
+userSchema.index({ name: 'text', 'profile.bio': 'text' });
+
+type IUser = InferSchemaType<typeof userSchema>;
+export const User = model('User', userSchema);
+```
+
+## Query Patterns
+
+```typescript
+// Pagination
+async function paginate(page: number, limit: number) {
+  const [items, total] = await Promise.all([
+    User.find({ isActive: true }).skip((page - 1) * limit).limit(limit).lean(),
+    User.countDocuments({ isActive: true }),
+  ]);
+  return { items, total, pages: Math.ceil(total / limit) };
+}
+
+// Aggregation
+const stats = await User.aggregate([
+  { $match: { isActive: true } },
+  { $group: { _id: '$role', count: { $sum: 1 }, avgAge: { $avg: '$age' } } },
+  { $sort: { count: -1 } },
+]);
+```
+
+## Middleware
+
+```typescript
+// Pre-save: hash password
+userSchema.pre('save', async function (next) {
+  if (!this.isModified('password')) return next();
+  this.password = await bcrypt.hash(this.password, 12);
+  next();
+});
+
+// Pre-find: exclude inactive by default
+userSchema.pre(/^find/, function (next) {
+  this.where({ isActive: { $ne: false } });
+  next();
+});
+```
+
+## FORBIDDEN
+
+1. **No indexes on queried fields** — always index filter/sort fields
+2. **`find()` without `.lean()`** for read-only — wastes memory
+3. **Unbounded queries** — always `.limit()`
+4. **N+1 queries** — use `.populate()` or aggregation `$lookup`
+5. **String IDs without casting** — use `new Types.ObjectId(id)`

package/stacks/nodejs/skills/nextjs-app-router/SKILL.md

@@ -0,0 +1,123 @@
+# Next.js App Router — Modern Patterns
+
+**ALWAYS invoke when writing Next.js pages, layouts, or server components.**
+
+## File Conventions
+
+```
+app/
+├── layout.tsx          # Root layout (required)
+├── page.tsx            # Home page
+├── loading.tsx         # Loading UI (Suspense boundary)
+├── error.tsx           # Error boundary ('use client')
+├── not-found.tsx       # 404 page
+├── (auth)/             # Route group (no URL segment)
+│   ├── login/page.tsx
+│   └── register/page.tsx
+├── dashboard/
+│   ├── layout.tsx      # Nested layout
+│   ├── page.tsx
+│   └── [id]/page.tsx   # Dynamic route
+└── api/
+    └── route.ts        # API route handler
+```
+
+## Server vs Client Components
+
+```tsx
+// DEFAULT: Server Component (no directive needed)
+async function UserList() {
+  const users = await db.user.findMany(); // Direct DB access
+  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
+}
+
+// CLIENT: Only when needed (interactivity, hooks, browser APIs)
+'use client';
+function Counter() {
+  const [count, setCount] = useState(0);
+  return <button onClick={() => setCount(c + 1)}>{count}</button>;
+}
+```
+
+## Data Fetching
+
+```tsx
+// Server Component — fetch with caching
+async function Page() {
+  const data = await fetch('https://api.example.com/data', {
+    next: { revalidate: 3600 }, // ISR: revalidate every hour
+  });
+  return <div>{data}</div>;
+}
+
+// Dynamic data (no cache)
+async function Page() {
+  const data = await fetch('https://api.example.com/data', {
+    cache: 'no-store',
+  });
+}
+```
+
+## Server Actions
+
+```tsx
+// app/actions.ts
+'use server';
+
+import { revalidatePath } from 'next/cache';
+
+export async function createUser(formData: FormData) {
+  const name = formData.get('name') as string;
+  await db.user.create({ data: { name } });
+  revalidatePath('/users');
+}
+
+// In component
+<form action={createUser}>
+  <input name="name" />
+  <button type="submit">Create</button>
+</form>
+```
+
+## Route Handlers (API)
+
+```tsx
+// app/api/users/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+
+export async function GET(request: NextRequest) {
+  const { searchParams } = new URL(request.url);
+  const page = Number(searchParams.get('page') ?? '1');
+  const users = await db.user.findMany({ skip: (page - 1) * 20, take: 20 });
+  return NextResponse.json(users);
+}
+
+export async function POST(request: NextRequest) {
+  const body = await request.json();
+  const result = schema.safeParse(body);
+  if (!result.success) return NextResponse.json(result.error, { status: 400 });
+  const user = await db.user.create({ data: result.data });
+  return NextResponse.json(user, { status: 201 });
+}
+```
+
+## Metadata
+
+```tsx
+// Static
+export const metadata = { title: 'Dashboard', description: 'User dashboard' };
+
+// Dynamic
+export async function generateMetadata({ params }: { params: { id: string } }) {
+  const user = await getUser(params.id);
+  return { title: user.name };
+}
+```
+
+## FORBIDDEN
+
+1. **`'use client'` on server-capable components** — default to server
+2. **Fetching in client when server fetch works** — use server components
+3. **`getServerSideProps` / `getStaticProps`** — App Router uses async components
+4. **API routes for server-only data** — use server components directly
+5. **Prop drilling through layouts** — use parallel routes or context

package/stacks/nodejs/skills/trpc-api/SKILL.md

@@ -0,0 +1,87 @@
+# tRPC API — End-to-End Type Safety
+
+**ALWAYS invoke when building type-safe API routes with tRPC.**
+
+## Structure
+
+```
+server/
+├── trpc.ts              # tRPC init + context
+├── routers/
+│   ├── _app.ts          # Root router (merges all)
+│   ├── user.router.ts
+│   └── post.router.ts
+└── middleware/
+    └── auth.ts          # Auth middleware
+```
+
+## Setup
+
+```typescript
+// server/trpc.ts
+import { initTRPC, TRPCError } from '@trpc/server';
+import superjson from 'superjson';
+
+const t = initTRPC.context<Context>().create({ transformer: superjson });
+
+export const router = t.router;
+export const publicProcedure = t.procedure;
+
+export const protectedProcedure = t.procedure.use(async ({ ctx, next }) => {
+  if (!ctx.session?.user) throw new TRPCError({ code: 'UNAUTHORIZED' });
+  return next({ ctx: { ...ctx, user: ctx.session.user } });
+});
+```
+
+## Router Pattern
+
+```typescript
+// server/routers/user.router.ts
+import { z } from 'zod';
+import { router, protectedProcedure } from '../trpc';
+
+export const userRouter = router({
+  me: protectedProcedure.query(async ({ ctx }) => {
+    return ctx.db.user.findUnique({ where: { id: ctx.user.id } });
+  }),
+
+  update: protectedProcedure
+    .input(z.object({ name: z.string().min(2) }))
+    .mutation(async ({ ctx, input }) => {
+      return ctx.db.user.update({
+        where: { id: ctx.user.id },
+        data: input,
+      });
+    }),
+
+  list: protectedProcedure
+    .input(z.object({ page: z.number().min(1).default(1), limit: z.number().max(100).default(20) }))
+    .query(async ({ ctx, input }) => {
+      const { page, limit } = input;
+      return ctx.db.user.findMany({ skip: (page - 1) * limit, take: limit });
+    }),
+});
+```
+
+## Client Usage (React)
+
+```tsx
+import { trpc } from '@/utils/trpc';
+
+function Profile() {
+  const { data: user, isLoading } = trpc.user.me.useQuery();
+  const updateMutation = trpc.user.update.useMutation({
+    onSuccess: () => utils.user.me.invalidate(),
+  });
+
+  if (isLoading) return <Skeleton />;
+  return <div>{user?.name}</div>;
+}
+```
+
+## FORBIDDEN
+
+1. **REST endpoints when tRPC covers it** — use tRPC procedures
+2. **Unvalidated input** — always use Zod `.input()`
+3. **Public procedures for auth-required data** — use `protectedProcedure`
+4. **Direct DB access in client** — always through tRPC procedures

package/stacks/nodejs/skills/typescript-strict/SKILL.md

@@ -0,0 +1,90 @@
+# TypeScript Strict — Type Safety Patterns
+
+**ALWAYS invoke when writing .ts/.tsx files.**
+
+## Required tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "exactOptionalPropertyTypes": true
+  }
+}
+```
+
+## Index Access
+
+```typescript
+// WRONG
+const port = process.env.PORT;
+
+// CORRECT — bracket notation
+const port = process.env['PORT'];
+const host = process.env['HOST'] ?? 'localhost';
+```
+
+## Null Handling
+
+```typescript
+// Optional chaining + nullish coalescing
+const avatar = user.profile?.avatar ?? '/default.png';
+
+// WRONG — || treats 0, '', false as falsy
+const count = input || 10;
+// CORRECT — ?? only null/undefined
+const count = input ?? 10;
+```
+
+## Type Guards
+
+```typescript
+function isUser(value: unknown): value is User {
+  return typeof value === 'object' && value !== null && 'id' in value && 'email' in value;
+}
+
+// Assertion function
+function assertDefined<T>(value: T | undefined | null, msg: string): asserts value is T {
+  if (value == null) throw new Error(msg);
+}
+```
+
+## Const Assertions
+
+```typescript
+// Exact types (not widened)
+const endpoints = {
+  users: '/api/users',
+  posts: '/api/posts',
+} as const;
+
+// Discriminated unions
+type Result<T> =
+  | { success: true; data: T }
+  | { success: false; error: string };
+```
+
+## Generic Patterns
+
+```typescript
+// Constrained
+function findById<T extends { id: string }>(items: T[], id: string): T | undefined {
+  return items.find(item => item.id === id);
+}
+
+// RequireFields utility
+type RequireFields<T, K extends keyof T> = T & Required<Pick<T, K>>;
+```
+
+## FORBIDDEN
+
+1. **`any`** — use `unknown` instead
+2. **Non-null assertion without certainty** — check first
+3. **Type assertion to hide errors** — fix the actual issue
+4. **`@ts-ignore`** — use `@ts-expect-error` with comment
+5. **Ignoring strict errors** — always fix properly