@codihaus/claude-skills 1.5.0 → 1.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codihaus/claude-skills",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "Claude Code skills for software development workflow",
   "main": "src/index.js",
   "bin": {
@@ -8,7 +8,10 @@
   },
   "scripts": {
     "build": "node scripts/build.js",
-    "prepublishOnly": "npm run build",
+    "release": "node scripts/publish.js",
+    "release:patch": "node scripts/publish.js patch",
+    "release:minor": "node scripts/publish.js minor",
+    "release:major": "node scripts/publish.js major",
     "test": "node bin/cli.js --help"
   },
   "type": "module",

package/skills/dev-coding-backend/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: dev-coding-backend
 description: Backend implementation patterns and workflows
-version: 2.0.0
+version: 2.1.0
 ---
 
 # /dev-coding-backend - Backend Implementation
@@ -11,6 +11,20 @@ version: 2.0.0
 
 Backend-specific workflow for API, schema, and data layer implementation.
 
+## Fundamentals (MUST READ FIRST)
+
+**Before implementing, understand the principles:**
+
+→ Read `references/fundamentals.md`
+
+This covers:
+- **Core Mindset**: "Guardian of truth, trust nothing, enforce rules"
+- **7 Principles**: Separation of Concerns, Single Source of Truth, Don't Repeat Work, Don't Make Users Wait, Don't Trust Anyone, Plan for Failure, Stateless Design
+- **Pattern Recognition**: When to use Service Layer, Repository, Queue, Cache, Circuit Breaker, etc.
+- **Architecture Layers**: Route → Service → Domain → Repository → Infrastructure
+
+**Key Decision**: For each piece of code, ask "which principle applies?" Then choose the pattern that principle suggests.
+
 ## Knowledge Loading (CRITICAL)
 
 Before implementing, load relevant knowledge:

package/skills/dev-coding-backend/references/fundamentals.md

@@ -0,0 +1,428 @@
+# Backend Fundamentals
+
+The principles and patterns that enable scalable, maintainable backend systems.
+
+## Core Mindset
+
+**"I am the guardian of truth. I trust nothing. I enforce rules. I must be reliable."**
+
+The backend is the last line of defense. It:
+- Protects data integrity
+- Enforces business rules
+- Handles failures gracefully
+- Scales under load
+
+---
+
+## The Principles
+
+Principles are the fundamental laws. Patterns are solutions derived from them.
+
+### 1. Separation of Concerns
+
+**Law**: Each piece of code should have ONE responsibility.
+
+**Why**: When things are mixed, changing one breaks another. Testing becomes impossible. New developers get lost.
+
+**Patterns derived**:
+
+| Pattern | What it Separates |
+|---------|-------------------|
+| Service Layer | Business logic FROM HTTP handling |
+| Repository | Data access FROM business logic |
+| Controller/Route | Request parsing FROM processing |
+| Middleware | Cross-cutting concerns FROM main logic |
+| Event-Driven | "What happened" FROM "What to do about it" |
+
+**Recognition signals**:
+- Function does more than one thing
+- Can't test without real database/HTTP
+- Changing one feature breaks another
+- File is > 300 lines
+
+**Structure example**:
+```
+# BAD: Mixed concerns
+route('/orders', async (req) => {
+  validate(req.body)           # validation
+  const user = await db.users.find(req.userId)  # data access
+  if (user.balance < req.body.total) throw Error  # business rule
+  await db.orders.create(...)  # data access
+  await sendEmail(user.email)  # side effect
+  return order
+})
+
+# GOOD: Separated concerns
+route('/orders', OrderController.create)
+
+OrderController.create(req) {
+  const dto = OrderValidator.validate(req.body)  # validation layer
+  const order = await OrderService.create(dto, req.userId)  # service layer
+  return OrderPresenter.format(order)  # presentation layer
+}
+
+OrderService.create(dto, userId) {
+  const user = await UserRepository.findById(userId)  # repository
+  OrderRules.validateCanOrder(user, dto)  # business rules
+  const order = await OrderRepository.create(dto)
+  await EventBus.emit('order.created', order)  # events for side effects
+  return order
+}
+```
+
+---
+
+### 2. Single Source of Truth
+
+**Law**: Each piece of data or rule should exist in ONE place only.
+
+**Why**: Duplicated data gets out of sync. Duplicated rules diverge over time.
+
+**Patterns derived**:
+
+| Pattern | What it Centralizes |
+|---------|---------------------|
+| Repository | All access to a data type |
+| Domain Model | Business rules for an entity |
+| Configuration | Environment-specific values |
+| Constants/Enums | Magic values and statuses |
+| Event Store | Historical record of changes |
+
+**Recognition signals**:
+- Same validation in multiple places
+- Same query written twice
+- Hardcoded values scattered around
+- "Which one is correct?" questions
+
+**Structure example**:
+```
+# BAD: Rules in multiple places
+# In controller:
+if (order.status !== 'pending') throw Error
+
+# In service:
+if (order.status !== 'pending') throw Error
+
+# In another service:
+if (order.status != 'pending' && order.status != 'draft') throw Error  # diverged!
+
+# GOOD: Single source
+class Order {
+  canBeModified() {
+    return ['pending', 'draft'].includes(this.status)
+  }
+}
+
+# Everywhere else:
+if (!order.canBeModified()) throw Error
+```
+
+---
+
+### 3. Don't Repeat Work
+
+**Law**: If the same work is done repeatedly with the same result, do it once and remember.
+
+**Why**: Wasted resources, slower response, higher costs, database overload.
+
+**Patterns derived**:
+
+| Pattern | What it Remembers |
+|---------|-------------------|
+| Caching (Redis/Memory) | Expensive query results |
+| Memoization | Function computation |
+| Database Indexes | Query paths |
+| CDN | Static assets |
+| Materialized Views | Pre-computed aggregations |
+
+**Recognition signals**:
+- Same query runs multiple times per request
+- Same computation on same input
+- Dashboard aggregations are slow
+- Database CPU is high
+
+**Decision guide**:
+```
+How often does data change?
+├── Never (static) → CDN, aggressive cache
+├── Rarely (config) → Long TTL cache (hours)
+├── Sometimes (user profile) → Medium TTL (minutes)
+├── Often (feed) → Short TTL (seconds) or real-time
+└── Always (balance) → No cache, or cache with invalidation
+```
+
+---
+
+### 4. Don't Make Users Wait
+
+**Law**: If something takes long and user doesn't need immediate result, do it later.
+
+**Why**: Users leave, connections timeout, server resources blocked.
+
+**Patterns derived**:
+
+| Pattern | Use When |
+|---------|----------|
+| Message Queue | Task takes > 1-2 seconds |
+| Background Jobs | Scheduled or deferred work |
+| Webhooks | Notify instead of poll |
+| Streaming | Large data transfer |
+| Pagination | Large result sets |
+
+**Recognition signals**:
+- API timeout errors
+- User waits > 3 seconds
+- Sending emails in request
+- Processing files in request
+- Generating reports in request
+
+**Structure example**:
+```
+# BAD: User waits for everything
+route('/orders', async (req) => {
+  const order = await createOrder(req.body)
+  await generateInvoicePDF(order)      # 3 seconds
+  await sendEmail(order)                # 2 seconds
+  await notifyWarehouse(order)          # 1 second
+  await updateAnalytics(order)          # 500ms
+  return order  # User waited 6.5 seconds!
+})
+
+# GOOD: Return fast, process later
+route('/orders', async (req) => {
+  const order = await createOrder(req.body)
+  await queue.add('order.process', { orderId: order.id })
+  return order  # User waited 200ms
+})
+
+# Background worker handles the rest
+worker.process('order.process', async (job) => {
+  const order = await OrderRepository.find(job.orderId)
+  await generateInvoicePDF(order)
+  await sendEmail(order)
+  await notifyWarehouse(order)
+  await updateAnalytics(order)
+})
+```
+
+---
+
+### 5. Don't Trust Anyone
+
+**Law**: Every input is potentially malicious or malformed. Validate at boundaries.
+
+**Why**: Security breaches, data corruption, system crashes.
+
+**Patterns derived**:
+
+| Pattern | What it Protects |
+|---------|------------------|
+| Input Validation | Data integrity |
+| Authentication | Identity verification |
+| Authorization | Access control |
+| Rate Limiting | Resource protection |
+| Sanitization | Injection prevention |
+
+**Recognition signals**:
+- User input used directly in queries
+- No authentication on endpoints
+- Missing role checks
+- No request size limits
+- Error messages expose internals
+
+**Validation layers**:
+```
+Request arrives
+    ↓
+[1. Rate Limit] → Too many? Reject 429
+    ↓
+[2. Authentication] → Who is this? Reject 401 if unknown
+    ↓
+[3. Authorization] → Can they do this? Reject 403 if not
+    ↓
+[4. Input Validation] → Is data valid? Reject 400 if not
+    ↓
+[5. Business Rules] → Is action allowed? Reject 422 if not
+    ↓
+Process request
+```
+
+---
+
+### 6. Plan for Failure
+
+**Law**: Everything will fail eventually. Design for it.
+
+**Why**: Network fails, services go down, databases crash, disks fill up.
+
+**Patterns derived**:
+
+| Pattern | Failure it Handles |
+|---------|-------------------|
+| Circuit Breaker | External service down |
+| Retry with Backoff | Temporary failures |
+| Timeout | Hung connections |
+| Fallback | Degraded operation |
+| Dead Letter Queue | Unprocessable messages |
+| Idempotency | Duplicate requests |
+
+**Recognition signals**:
+- No try/catch around external calls
+- No timeout on HTTP requests
+- Retrying without backoff (hammering)
+- No fallback when service unavailable
+- Duplicate orders when user clicks twice
+
+**Structure example**:
+```
+# BAD: Assumes success
+const payment = await paymentService.charge(order)
+
+# GOOD: Plans for failure
+const payment = await circuitBreaker.call(
+  () => paymentService.charge(order),
+  {
+    timeout: 5000,
+    retry: { attempts: 3, backoff: 'exponential' },
+    fallback: () => {
+      queue.add('payment.retry', { orderId: order.id })
+      return { status: 'pending', message: 'Processing...' }
+    }
+  }
+)
+```
+
+**Idempotency example**:
+```
+# Problem: User clicks "Pay" twice, charged twice
+
+# Solution: Idempotency key
+route('/payments', async (req) => {
+  const existingPayment = await PaymentRepository.findByIdempotencyKey(
+    req.headers['idempotency-key']
+  )
+
+  if (existingPayment) {
+    return existingPayment  # Return same result, don't process again
+  }
+
+  const payment = await processPayment(req.body)
+  payment.idempotencyKey = req.headers['idempotency-key']
+  await PaymentRepository.save(payment)
+  return payment
+})
+```
+
+---
+
+### 7. Stateless Design
+
+**Law**: Server should not remember anything between requests (store state externally).
+
+**Why**: Enables horizontal scaling, survives server restarts, simplifies deployment.
+
+**Patterns derived**:
+
+| Pattern | State it Externalizes |
+|---------|----------------------|
+| JWT Tokens | Session data in token |
+| External Session Store | Session data in Redis |
+| Database | All persistent data |
+| Shared Cache | Computed/temporary data |
+| Object Storage | Files and uploads |
+
+**Recognition signals**:
+- Using server memory for sessions
+- Files stored on local disk
+- In-memory caches that miss after deploy
+- "Works on one server, fails with two"
+
+**Structure example**:
+```
+# BAD: Stateful (breaks with multiple servers)
+const sessions = {}  # In memory!
+app.post('/login', (req) => {
+  sessions[userId] = { user, timestamp }
+})
+app.get('/me', (req) => {
+  return sessions[req.userId]  # Other server doesn't have this!
+})
+
+# GOOD: Stateless (works with any number of servers)
+app.post('/login', async (req) => {
+  const token = jwt.sign({ userId, role })  # State in token
+  await redis.set(`session:${userId}`, { lastLogin })  # State in Redis
+  return { token }
+})
+app.get('/me', async (req) => {
+  const payload = jwt.verify(req.token)  # State from token
+  const session = await redis.get(`session:${payload.userId}`)  # State from Redis
+  return { user: payload, session }
+})
+```
+
+---
+
+## Pattern Decision Matrix
+
+Quick reference for choosing patterns:
+
+| Situation | Apply These Patterns |
+|-----------|---------------------|
+| Code is getting messy, hard to test | Service Layer + Repository + DI |
+| Same logic in multiple places | Extract to Domain Model or Service |
+| API is slow | Caching, Queue, Pagination |
+| High database load | Caching, Indexing, Read Replicas |
+| External service unreliable | Circuit Breaker, Retry, Fallback |
+| Need audit trail | Event Sourcing or Audit Log |
+| Complex workflows | Saga, State Machine |
+| Many services communicating | Event Bus, API Gateway |
+| Users hitting API too hard | Rate Limiting, Throttling |
+| File uploads | Object Storage, Signed URLs |
+
+---
+
+## Architecture Layers
+
+Standard backend structure:
+
+```
+┌─────────────────────────────────────────────┐
+│  HTTP Layer (Routes/Controllers)            │
+│  - Parse request                            │
+│  - Call service                             │
+│  - Format response                          │
+├─────────────────────────────────────────────┤
+│  Service Layer                              │
+│  - Business logic                           │
+│  - Orchestrate operations                   │
+│  - Emit events                              │
+├─────────────────────────────────────────────┤
+│  Domain Layer (Models/Entities)             │
+│  - Business rules                           │
+│  - Validation                               │
+│  - State transitions                        │
+├─────────────────────────────────────────────┤
+│  Repository Layer                           │
+│  - Data access                              │
+│  - Query building                           │
+│  - Caching                                  │
+├─────────────────────────────────────────────┤
+│  Infrastructure (Database, Queue, Cache)    │
+└─────────────────────────────────────────────┘
+```
+
+**Rule**: Upper layers can call lower layers. Never the reverse.
+
+---
+
+## Checklist Before Implementation
+
+- [ ] Which principle applies to this feature?
+- [ ] What patterns does that principle suggest?
+- [ ] Is there existing similar code to follow?
+- [ ] Where does validation happen?
+- [ ] What if this fails?
+- [ ] What if 1000 users do this at once?
+- [ ] Does this need to be synchronous?
+- [ ] What state needs to be stored?

package/skills/dev-coding-frontend/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: dev-coding-frontend
 description: Frontend implementation patterns and workflows
-version: 2.0.0
+version: 2.1.0
 ---
 
 # /dev-coding-frontend - Frontend Implementation
@@ -12,6 +12,22 @@ version: 2.0.0
 
 Frontend-specific workflow for UI components, pages, and client-side logic.
 
+## Fundamentals (MUST READ FIRST)
+
+**Before implementing, understand the principles:**
+
+→ Read `references/fundamentals.md`
+
+This covers:
+- **Core Mindset**: "Communicator with humans - clear, responsive, consistent"
+- **6 Principles**: Always Communicate, Feel Instant, Stay Consistent, Work for Everyone, Single Source of Truth, Minimize Complexity
+- **Pattern Recognition**: When to use Loading States, Optimistic UI, State Management, Lazy Loading, etc.
+- **UI States**: Every component must handle loading, error, empty, success
+
+**Key Decision**: For each piece of code, ask "which principle applies?" Then choose the pattern that principle suggests.
+
+**CRITICAL - Consistency**: Before writing ANY code, check existing codebase for naming conventions, file structure, component patterns, and styling approach. Match them exactly.
+
 ## Knowledge Loading (CRITICAL)
 
 Before implementing, load relevant knowledge:

package/skills/dev-coding-frontend/references/fundamentals.md

@@ -0,0 +1,577 @@
+# Frontend Fundamentals
+
+The principles and patterns that create excellent user experiences.
+
+## Core Mindset
+
+**"I am the communicator with humans. I must be clear, responsive, and consistent."**
+
+The frontend is the interface between humans and the system. It:
+- Communicates what's happening
+- Responds instantly (or appears to)
+- Behaves consistently
+- Works for everyone
+
+---
+
+## The Principles
+
+Principles are the fundamental laws. Patterns are solutions derived from them.
+
+### 1. Always Communicate
+
+**Law**: The user should NEVER wonder what's happening.
+
+**Why**: Uncertainty creates anxiety. Users abandon apps that feel "broken" or "stuck."
+
+**Patterns derived**:
+
+| Pattern | What it Communicates |
+|---------|---------------------|
+| Loading State | "I'm working on it" |
+| Error State | "Something went wrong, here's what" |
+| Empty State | "Nothing here yet, here's why" |
+| Success Feedback | "Done! Here's the result" |
+| Progress Indicator | "X% complete" |
+| Skeleton UI | "Content is coming, here's the shape" |
+
+**Recognition signals**:
+- Blank screen while loading
+- Click button, nothing visible happens
+- Error occurs, user sees nothing
+- Form submits, no confirmation
+- List might be empty, just shows nothing
+
+**State matrix for EVERY data-fetching component**:
+```
+STATE        WHAT USER SEES
+─────────────────────────────────────
+idle         Initial state, maybe CTA
+loading      Spinner, skeleton, or shimmer
+success      The actual content
+empty        Helpful message + action
+error        What went wrong + retry option
+```
+
+**Structure example**:
+```vue
+<!-- BAD: No communication -->
+<template>
+  <div v-for="item in items">{{ item.name }}</div>
+</template>
+
+<!-- GOOD: Always communicating -->
+<template>
+  <!-- Loading: Show skeleton -->
+  <div v-if="pending">
+    <Skeleton v-for="i in 3" :key="i" />
+  </div>
+
+  <!-- Error: Explain and offer action -->
+  <div v-else-if="error">
+    <ErrorMessage :error="error" />
+    <Button @click="refresh">Try Again</Button>
+  </div>
+
+  <!-- Empty: Guide the user -->
+  <div v-else-if="items.length === 0">
+    <EmptyState
+      title="No items yet"
+      description="Create your first item to get started"
+      action="Create Item"
+      @action="openCreateModal"
+    />
+  </div>
+
+  <!-- Success: Show content -->
+  <div v-else>
+    <Item v-for="item in items" :key="item.id" :item="item" />
+  </div>
+</template>
+```
+
+---
+
+### 2. Feel Instant
+
+**Law**: Perception matters more than reality. Make it FEEL fast.
+
+**Why**: Users perceive 100ms as instant. After 1s they notice delay. After 3s they leave.
+
+**Patterns derived**:
+
+| Pattern | How it Feels Faster |
+|---------|---------------------|
+| Optimistic UI | Show result before server confirms |
+| Skeleton Loading | Show shape, brain fills in details |
+| Lazy Loading | Load what's visible first |
+| Prefetching | Load before user needs it |
+| Debouncing | Don't overwork on rapid input |
+| Code Splitting | Smaller initial bundle |
+| Instant Navigation | Client-side routing |
+
+**Recognition signals**:
+- User clicks, waits, then sees change
+- Full page reload on navigation
+- Large bundle size, slow initial load
+- Images load all at once, page jumps
+- Search triggers on every keystroke
+
+**Optimistic UI example**:
+```javascript
+// BAD: Wait for server
+async function toggleLike(post) {
+  const result = await api.likePost(post.id)  // User waits 500ms
+  post.liked = result.liked
+  post.likeCount = result.likeCount
+}
+
+// GOOD: Optimistic update
+async function toggleLike(post) {
+  // Immediately update UI (feels instant)
+  const previousState = { liked: post.liked, count: post.likeCount }
+  post.liked = !post.liked
+  post.likeCount += post.liked ? 1 : -1
+
+  try {
+    await api.likePost(post.id)
+  } catch (error) {
+    // Rollback if server fails
+    post.liked = previousState.liked
+    post.likeCount = previousState.count
+    toast.error('Could not update like')
+  }
+}
+```
+
+**Loading priority**:
+```
+1. Critical content (above fold)     → Load immediately
+2. Interactive elements              → Load immediately
+3. Below-fold content                → Lazy load on scroll
+4. Images                            → Lazy load + placeholder
+5. Analytics, tracking               → Load after page ready
+6. Non-essential features            → Load on interaction
+```
+
+---
+
+### 3. Stay Consistent
+
+**Law**: Same action should always produce same result. Match existing patterns.
+
+**Why**: Consistency builds trust. Inconsistency confuses and frustrates.
+
+**Patterns derived**:
+
+| Pattern | What it Standardizes |
+|---------|---------------------|
+| Design System | Visual appearance |
+| Component Library | UI behavior |
+| Naming Conventions | Code readability |
+| Layout Templates | Page structure |
+| Form Patterns | Input behavior |
+| Navigation Patterns | Movement through app |
+
+**Recognition signals**:
+- Buttons look different on different pages
+- Same action has different animations
+- Forms behave differently
+- Different naming styles in codebase
+- New code doesn't match existing patterns
+
+**Consistency checklist**:
+```
+Before writing new code, check existing codebase for:
+
+NAMING:
+□ How are components named? (PascalCase, kebab-case?)
+□ How are files named? (index.vue, ComponentName.vue?)
+□ How are props named? (isOpen, open, opened?)
+□ How are events named? (onClose, handleClose, close?)
+□ How are functions named? (getData, fetchData, loadData?)
+
+STRUCTURE:
+□ Where do components live? (components/, shared/?)
+□ How is state managed? (Pinia, composables, local?)
+□ How are forms handled? (controlled, libraries?)
+□ How is API data fetched? (useFetch, custom hooks?)
+
+STYLE:
+□ What CSS approach? (Tailwind, modules, styled?)
+□ What design tokens exist? (colors, spacing, shadows?)
+□ How are responsive breakpoints handled?
+
+BEHAVIOR:
+□ How do modals open/close?
+□ How is form validation shown?
+□ How are notifications displayed?
+□ How do lists handle empty/loading states?
+```
+
+**Match existing pattern example**:
+```javascript
+// EXISTING CODE uses this pattern:
+const { data: users, pending, error } = await useFetch('/api/users')
+
+// NEW CODE should match:
+// GOOD - matches existing
+const { data: products, pending, error } = await useFetch('/api/products')
+
+// BAD - different pattern
+const products = ref([])
+const loading = ref(true)
+onMounted(async () => {
+  loading.value = true
+  products.value = await fetch('/api/products').then(r => r.json())
+  loading.value = false
+})
+```
+
+---
+
+### 4. Work for Everyone
+
+**Law**: The interface must work for all users, not just ideal conditions.
+
+**Why**: Users have disabilities, slow connections, old devices, different languages.
+
+**Patterns derived**:
+
+| Pattern | Who it Helps |
+|---------|-------------|
+| Semantic HTML | Screen readers, SEO |
+| Keyboard Navigation | Motor disabilities, power users |
+| Color Contrast | Visual impairments |
+| Responsive Design | Mobile users |
+| Offline Support | Poor connections |
+| Error Recovery | All users |
+| Internationalization | Non-English speakers |
+
+**Recognition signals**:
+- Can't use with keyboard only
+- No alt text on images
+- Low color contrast
+- Breaks on mobile
+- Crashes on slow connection
+- No error recovery
+
+**Accessibility minimum**:
+```html
+<!-- Semantic HTML first -->
+<nav> not <div class="nav">
+<button> not <div onclick>
+<main> not <div class="main">
+<h1>, <h2>, <h3> in order
+
+<!-- Images -->
+<img src="..." alt="Description of what image shows" />
+<img src="decorative.png" alt="" />  <!-- Empty alt for decorative -->
+
+<!-- Interactive elements -->
+<button aria-label="Close dialog">×</button>
+<input aria-describedby="help-text" />
+<div id="help-text">Password must be 8+ characters</div>
+
+<!-- Focus management -->
+<!-- When modal opens: focus first element -->
+<!-- When modal closes: focus trigger element -->
+
+<!-- Keyboard -->
+<!-- All interactive elements reachable via Tab -->
+<!-- Enter/Space activates buttons -->
+<!-- Escape closes modals/dropdowns -->
+```
+
+**Responsive approach**:
+```
+MOBILE FIRST:
+1. Design for smallest screen first
+2. Add complexity for larger screens
+3. Test at: 320px, 768px, 1024px, 1440px
+
+CSS ORDER:
+.component {
+  /* Mobile styles (default) */
+  padding: 1rem;
+}
+
+@media (min-width: 768px) {
+  /* Tablet and up */
+  padding: 2rem;
+}
+
+@media (min-width: 1024px) {
+  /* Desktop and up */
+  padding: 3rem;
+}
+```
+
+---
+
+### 5. Single Source of Truth
+
+**Law**: Each piece of state should live in ONE place.
+
+**Why**: Duplicate state gets out of sync. Bugs appear. Debugging is nightmare.
+
+**Patterns derived**:
+
+| Pattern | What it Centralizes |
+|---------|---------------------|
+| State Management (Pinia) | Global app state |
+| Composables | Shared logic |
+| Controlled Components | Form input values |
+| URL as State | Navigation/filter state |
+| Props Down, Events Up | Component communication |
+
+**Recognition signals**:
+- Same data stored in multiple places
+- Prop drilling through many levels
+- Components directly modifying parent state
+- State out of sync after actions
+- "Why isn't this updating?"
+
+**State location guide**:
+```
+WHO NEEDS THIS STATE?
+│
+├─ Just this component → Local state (ref/reactive)
+│
+├─ Parent and children → Props down, events up
+│
+├─ Siblings → Lift state to common parent, or use composable
+│
+├─ Many unrelated components → Global store (Pinia)
+│
+└─ Should survive refresh → URL params or localStorage
+```
+
+**Example**:
+```javascript
+// BAD: Duplicate state
+// In Parent:
+const selectedUser = ref(null)
+
+// In Child (duplicating):
+const selectedUser = ref(null)  // Out of sync risk!
+
+// GOOD: Single source
+// In Parent:
+const selectedUser = ref(null)
+
+// In Child (receiving):
+const props = defineProps(['selectedUser'])
+const emit = defineEmits(['update:selectedUser'])
+
+// Or use store for global state:
+// store/user.js
+export const useUserStore = defineStore('user', () => {
+  const selectedUser = ref(null)
+  const selectUser = (user) => selectedUser.value = user
+  return { selectedUser, selectUser }
+})
+
+// Any component:
+const userStore = useUserStore()
+userStore.selectUser(user)
+```
+
+---
+
+### 6. Minimize Complexity
+
+**Law**: Simple is better than clever. Obvious is better than magical.
+
+**Why**: Others (and future you) must understand and modify this code.
+
+**Patterns derived**:
+
+| Pattern | How it Simplifies |
+|---------|-------------------|
+| Small Components | Each does one thing |
+| Composition | Combine simple pieces |
+| Explicit Props | Clear interface |
+| Flat State | Avoid deep nesting |
+| Co-location | Related code together |
+
+**Recognition signals**:
+- Component file > 300 lines
+- Props > 10 items
+- Deeply nested state (a.b.c.d.e)
+- "Magic" that's hard to trace
+- Heavy abstraction for simple tasks
+
+**Component size guide**:
+```
+IDEAL COMPONENT:
+- One clear responsibility
+- < 200 lines (template + script)
+- < 10 props
+- Can describe in one sentence
+
+TOO BIG IF:
+- Multiple responsibilities
+- Lots of conditional rendering
+- Can't understand in 30 seconds
+- Needs comments to explain
+
+SPLIT INTO:
+- Container (data/logic) + Presenter (UI)
+- Multiple smaller components
+- Composable for shared logic
+```
+
+**Composition over complexity**:
+```vue
+<!-- BAD: One complex component -->
+<template>
+  <div>
+    <div v-if="mode === 'edit'">
+      <!-- 100 lines of edit form -->
+    </div>
+    <div v-else-if="mode === 'view'">
+      <!-- 100 lines of view display -->
+    </div>
+    <div v-else-if="mode === 'loading'">
+      <!-- 50 lines of skeleton -->
+    </div>
+  </div>
+</template>
+
+<!-- GOOD: Composed simple components -->
+<template>
+  <ProductSkeleton v-if="pending" />
+  <ProductEditForm v-else-if="mode === 'edit'" :product="data" @save="save" />
+  <ProductView v-else :product="data" @edit="startEdit" />
+</template>
+```
+
+---
+
+## Pattern Decision Matrix
+
+Quick reference for choosing patterns:
+
+| Situation | Apply These Patterns |
+|-----------|---------------------|
+| Data from API | Loading + Error + Empty states |
+| User action → Server | Optimistic UI or Loading feedback |
+| Form with many fields | Form library + Validation schema |
+| Large list (100+ items) | Virtualization |
+| Heavy component rarely used | Lazy loading |
+| Multiple components need same data | State management (Pinia) |
+| Complex UI with many states | State machine |
+| Need to match existing code | Study patterns first, match exactly |
+| Reusable UI element | Extract to component |
+| Reusable logic | Extract to composable |
+
+---
+
+## Component Structure
+
+Standard component organization:
+
+```vue
+<script setup lang="ts">
+// 1. Imports
+import { ref, computed, watch } from 'vue'
+import { useUserStore } from '@/stores/user'
+import ChildComponent from './ChildComponent.vue'
+
+// 2. Props & Emits
+const props = defineProps<{
+  title: string
+  items: Item[]
+}>()
+
+const emit = defineEmits<{
+  select: [item: Item]
+  close: []
+}>()
+
+// 3. Composables & Stores
+const userStore = useUserStore()
+const { data, pending, error } = await useFetch('/api/data')
+
+// 4. Local State
+const isOpen = ref(false)
+const searchQuery = ref('')
+
+// 5. Computed
+const filteredItems = computed(() =>
+  props.items.filter(item =>
+    item.name.includes(searchQuery.value)
+  )
+)
+
+// 6. Methods
+function handleSelect(item: Item) {
+  emit('select', item)
+}
+
+// 7. Lifecycle & Watchers
+watch(searchQuery, (newValue) => {
+  // React to changes
+})
+</script>
+
+<template>
+  <!-- Single root with clear structure -->
+</template>
+
+<style scoped>
+/* Component-specific styles */
+</style>
+```
+
+---
+
+## UI States Template
+
+Every data component should handle:
+
+```vue
+<script setup>
+const { data, pending, error, refresh } = await useFetch('/api/resource')
+</script>
+
+<template>
+  <div class="resource-container">
+    <!-- Loading -->
+    <ResourceSkeleton v-if="pending" />
+
+    <!-- Error -->
+    <ErrorState
+      v-else-if="error"
+      :message="error.message"
+      @retry="refresh"
+    />
+
+    <!-- Empty -->
+    <EmptyState
+      v-else-if="!data || data.length === 0"
+      title="No resources found"
+      description="Create your first resource to get started"
+    >
+      <Button @click="openCreate">Create Resource</Button>
+    </EmptyState>
+
+    <!-- Success -->
+    <ResourceList v-else :items="data" />
+  </div>
+</template>
+```
+
+---
+
+## Checklist Before Implementation
+
+- [ ] Which principle applies to this feature?
+- [ ] Does this match existing code patterns?
+- [ ] What are all the UI states? (loading, error, empty, success)
+- [ ] How can this feel instant?
+- [ ] Can it be used with keyboard only?
+- [ ] Does it work on mobile?
+- [ ] Where should state live?
+- [ ] Is this component doing too much?