@codihaus/claude-skills 1.5.0 → 1.6.0

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: