@codihaus/claude-skills 1.6.6 → 1.6.8

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

@@ -1,428 +0,0 @@
-# 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,296 +0,0 @@
----
-name: dev-coding-frontend
-description: Frontend implementation patterns and workflows
-version: 2.1.0
----
-
-# /dev-coding-frontend - Frontend Implementation
-
-> **Loaded by**: `/dev-coding` when UI work needed
-> **Tools**: shadcn MCP, Playwright, Context7
-> **Before**: Backend API contract should be documented
-
-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:
-
-```
-1. Read stack.md → plans/scout/stack.md
-   → Identify: Framework, UI library, state management
-
-2. Load stack knowledge based on detected tech:
-   | If using...  | Read...                           | Section           |
-   |--------------|-----------------------------------|-------------------|
-   | Nuxt.js      | knowledge/stacks/nuxt/_index.md      | "For /dev-coding" |
-   | Next.js      | knowledge/stacks/nextjs/_index.md    | "For /dev-coding" |
-   | Directus     | knowledge/stacks/directus/_index.md  | "SDK Integration" |
-
-3. Load domain knowledge (if applicable):
-   | If domain... | Read...                            | Section           |
-   |--------------|-----------------------------------|-------------------|
-   | SaaS         | knowledge/domains/saas/_index.md      | UI patterns       |
-   | E-commerce   | knowledge/domains/ecommerce/_index.md | Checkout flows    |
-
-4. Use loaded knowledge for:
-   → Correct data fetching (useFetch vs useEffect vs Server Component)
-   → Framework-specific patterns (composables vs hooks)
-   → Domain-specific UI flows
-```
-
-## Workflow
-
-### Step 1: Extract Frontend Requirements
-
-From UC spec, identify:
-
-```
-[ ] Pages/Routes?
-    → Path, layout, auth required?
-
-[ ] Components?
-    → New, modify existing, shared vs feature-specific
-
-[ ] State management?
-    → Local, global, server state
-
-[ ] Forms?
-    → Fields, validation, submit handling
-
-[ ] API integration?
-    → Endpoints, loading/error states
-```
-
-### Step 2: Review API Contract
-
-From backend implementation:
-
-```markdown
-### POST /api/auth/login
-- Request: `{ email, password }`
-- Response: `{ token, user }`
-- Errors: 400 (validation), 401 (credentials)
-```
-
-Match component shapes to API.
-
-### Step 3: Component Architecture
-
-**Order:** Base components → Feature components → Pages
-
-```
-src/
-├── components/
-│   ├── ui/              # Shared (Button, Input)
-│   └── features/
-│       └── auth/        # Feature-specific (LoginForm)
-├── app/ (or pages/)
-│   └── login/page.tsx
-```
-
-**Follow project conventions** from scout.
-
-### Step 4: Build Components
-
-Essential component pattern:
-
-```tsx
-interface Props {
-  onSuccess?: (data: Data) => void;
-}
-
-export function FeatureForm({ onSuccess }: Props) {
-  const [isLoading, setIsLoading] = useState(false);
-  const [error, setError] = useState<string | null>(null);
-
-  const handleSubmit = async (e: FormEvent) => {
-    e.preventDefault();
-    setIsLoading(true);
-    setError(null);
-
-    try {
-      const result = await apiCall(formData);
-      onSuccess?.(result);
-    } catch (err) {
-      setError(err.message);
-    } finally {
-      setIsLoading(false);
-    }
-  };
-
-  return (
-    <form onSubmit={handleSubmit}>
-      {error && <Alert variant="error">{error}</Alert>}
-      {/* Form fields */}
-      <Button type="submit" disabled={isLoading}>
-        {isLoading ? 'Loading...' : 'Submit'}
-      </Button>
-    </form>
-  );
-}
-```
-
-### Step 5: Handle States
-
-```tsx
-// Loading
-{isLoading && <Spinner />}
-
-// Error
-{error && <Alert variant="error">{error}</Alert>}
-
-// Empty
-{items.length === 0 && <EmptyState />}
-
-// Success
-{items.map(item => <Card key={item.id} {...item} />)}
-```
-
-### Step 6: Verify
-
-Quick sanity check before `/dev-test`:
-
-```typescript
-// Visual snapshot
-await mcp__playwright__browser_navigate({ url: 'http://localhost:3000/page' });
-await mcp__playwright__browser_snapshot({});
-```
-
-```
-[ ] Page renders without console errors
-[ ] Components display correctly
-[ ] Forms accept input
-```
-
-## Essential Checklists
-
-### Accessibility
-```
-[ ] Images have alt text
-[ ] Form inputs have labels
-[ ] Buttons have accessible names
-[ ] Keyboard navigation works
-[ ] Focus states visible
-```
-
-### Responsive
-```
-[ ] Mobile (< 768px)
-[ ] Tablet (768px - 1024px)
-[ ] Desktop (> 1024px)
-[ ] Touch targets 44px minimum
-```
-
-## Quick Debugging
-
-```bash
-# Console errors → Browser DevTools
-# Network failures → Network tab, check CORS
-# Styling issues → Elements panel, check classes
-```
-
-```typescript
-// Playwright debugging
-await mcp__playwright__browser_console_messages({ level: 'error' });
-await mcp__playwright__browser_network_requests({});
-await mcp__playwright__browser_take_screenshot({ filename: 'debug.png' });
-```
-
-## Stack-Specific Patterns
-
-**Do not implement generic patterns. Load from stacks/:**
-
-| Stack | What to load | Key patterns |
-|-------|--------------|--------------|
-| Nuxt.js | `stacks/nuxt/` | Composables, useFetch, SSR |
-| Next.js | `stacks/nextjs/` | Server Components, Actions |
-| Vue | `stacks/vue/` (future) | Composition API, reactivity |
-| React | `stacks/react/` (future) | Hooks, state patterns |
-
-**Example - if using Nuxt:**
-```
-1. Read knowledge/stacks/nuxt/_index.md
-2. Use useFetch (not raw fetch)
-3. Use composables pattern
-4. Handle SSR hydration
-```
-
-## Domain-Specific UI
-
-**Load from domains/ when applicable:**
-
-| Domain | What to load | Key patterns |
-|--------|--------------|--------------|
-| SaaS | `domains/saas/_index.md` | Pricing tables, subscription UI |
-| E-commerce | `domains/ecommerce/_index.md` | Cart, checkout, product cards |
-
-## Tools
-
-### shadcn/ui Components
-
-```
-# List components
-mcp__shadcn__list_components
-
-# Get component source
-mcp__shadcn__get_component("button")
-
-# Get usage demo
-mcp__shadcn__get_component_demo("form")
-
-# Get pre-built blocks
-mcp__shadcn__list_blocks
-mcp__shadcn__get_block("login-01")
-mcp__shadcn__get_block("dashboard-01")
-```
-
-**Workflow:**
-1. Check if project uses shadcn (look for `components.json`)
-2. List available components
-3. Get demos for patterns
-4. Adapt to project's API
-
-### Playwright (Visual Verification)
-
-```
-mcp__playwright__browser_navigate({ url })
-mcp__playwright__browser_snapshot({})
-mcp__playwright__browser_take_screenshot({ filename })
-mcp__playwright__browser_console_messages({ level: "error" })
-mcp__playwright__browser_network_requests({})
-```
-
-### Context7 (Documentation)
-
-```typescript
-// Find library
-mcp__context7__resolve-library-id({
-  libraryName: "react-hook-form",
-  query: "form validation"
-})
-
-// Query docs
-mcp__context7__query-docs({
-  libraryId: "/react-hook-form/react-hook-form",
-  query: "validate email field"
-})
-```
-
-Use for: Framework patterns, library APIs, CSS framework docs.