@codihaus/claude-skills 1.0.0 → 1.2.0

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

@@ -1,118 +1,101 @@
 ---
 name: dev-coding-backend
 description: Backend implementation patterns and workflows
-version: 1.2.0
+version: 2.0.0
 ---
 
 # /dev-coding-backend - Backend Implementation
 
-> **Skill Awareness**: See `skills/_registry.md` for all available skills.
-> - **Loaded by**: `/dev-coding` when API/schema work needed
-> - **References**: Load tech-specific from `references/` (directus.md, prisma.md, etc.)
-> - **After**: Frontend uses API contract documented here
-> - **After**: `/dev-test` auto-runs to verify API via network requests
+> **Loaded by**: `/dev-coding` when API/schema work needed
+> **After**: Frontend uses API contract documented here
 
-Backend-specific patterns for API, schema, and data layer implementation.
+Backend-specific workflow for API, schema, and data layer implementation.
 
-## When Loaded
+## Knowledge Loading (CRITICAL)
 
-This skill is loaded by `/dev-coding` when:
-- Spec requires API endpoints
-- Spec requires schema/database changes
-- Spec requires backend logic
+Before implementing, load relevant knowledge:
 
-## Workflow
+```
+1. Read stack.md → plans/scout/stack.md
+   → Identify: API layer, SDK, data access method
 
-### Step 1: Understand Backend Requirements
+2. Load stack knowledge based on detected tech:
+   | If using...  | Read...                           | Section           |
+   |--------------|-----------------------------------|-------------------|
+   | Directus     | knowledge/stacks/directus/_index.md  | "For /dev-coding" |
+   | Nuxt server  | knowledge/stacks/nuxt/_index.md      | "Server Routes"   |
+   | Next.js API  | knowledge/stacks/nextjs/_index.md    | "API Routes"      |
 
-From the UC spec, extract:
+3. Load domain knowledge (if applicable):
+   | If domain... | Read...                            | Section           |
+   |--------------|-----------------------------------|-------------------|
+   | SaaS         | knowledge/domains/saas/_index.md      | Billing, Multi-tenant |
+   | E-commerce   | knowledge/domains/ecommerce/_index.md | Orders, Payments  |
 
-```markdown
-## Backend Requirements Checklist
+4. Use loaded knowledge for:
+   → Correct SDK usage (not raw fetch)
+   → Domain-specific validation rules
+   → Stack-specific error handling
+```
 
-[ ] Schema changes needed?
-    - New collections/tables
-    - New fields on existing
-    - Relations to add
+## Workflow
+
+### Step 1: Extract Backend Requirements
+
+From UC spec, identify:
+
+```
+[ ] Schema changes?
+    → New collections/tables
+    → New fields
+    → Relations
 
-[ ] API endpoints needed?
-    - Method + Path
-    - Request body
-    - Response shape
-    - Auth required?
+[ ] API endpoints?
+    → Method + Path
+    → Request/Response shape
+    → Auth required?
 
 [ ] Business logic?
-    - Validation rules
-    - Calculations
-    - Side effects (emails, notifications)
+    → Validation rules
+    → Side effects (emails, webhooks)
 
 [ ] External integrations?
-    - Third-party APIs
-    - Webhooks
-    - File storage
+    → Third-party APIs
+    → File storage
 ```
 
-### Step 2: Schema First (if needed)
+### Step 2: Schema First
 
-**Order matters:** Schema before API
+**Order:** Schema → API → Logic
 
 ```
 1. Design schema based on spec
 2. Create/modify collections or tables
 3. Set up relations
-4. Configure permissions/roles
-5. Verify schema is correct
-```
-
-**Verification:**
-```bash
-# For Directus - check collection exists
-curl "$DIRECTUS_URL/items/{collection}?limit=1" \
-  -H "Authorization: Bearer $TOKEN"
-
-# For Prisma - run migration
-npx prisma migrate dev
-
-# For SQL - verify table
-psql -c "\\d {table_name}"
+4. Configure permissions
+5. Verify schema works
 ```
 
 ### Step 3: API Implementation
 
-**For each endpoint in spec:**
+For each endpoint:
 
 ```
-1. Create route/handler file
-2. Implement request parsing
-3. Add validation
-4. Implement business logic
+1. Create route/handler
+2. Parse request
+3. Validate input
+4. Implement logic
 5. Handle errors
 6. Return response
 ```
 
-**Follow project patterns** (from scout):
-- File location (routes/, api/, controllers/)
-- Naming convention
-- Error handling pattern
-- Response format
-
-### Step 4: API Patterns
+**Follow project patterns** from scout (file locations, naming, error format).
 
-#### REST Conventions
+### Step 4: Essential Patterns
 
-```
-GET    /api/{resource}        → List
-GET    /api/{resource}/:id    → Get one
-POST   /api/{resource}        → Create
-PUT    /api/{resource}/:id    → Update (full)
-PATCH  /api/{resource}/:id    → Update (partial)
-DELETE /api/{resource}/:id    → Delete
-```
-
-#### Request Validation
+#### Request Validation (always do this)
 
 ```typescript
-// Always validate input
 const schema = z.object({
   email: z.string().email(),
   password: z.string().min(8),
@@ -127,235 +110,117 @@ if (!result.success) {
 }
 ```
 
-#### Error Handling
+#### Error Response Format
 
 ```typescript
-// Consistent error format
-{
-  "error": "Error message for client",
-  "code": "ERROR_CODE",
-  "details": {} // Optional additional info
-}
+// Consistent format
+{ "error": "Message", "code": "ERROR_CODE" }
 
-// HTTP status codes
-200 - Success
-201 - Created
-400 - Bad request (validation)
-401 - Unauthorized
-403 - Forbidden
-404 - Not found
-409 - Conflict
-500 - Server error
+// Status codes
+200 - Success       400 - Bad request
+201 - Created       401 - Unauthorized
+                    403 - Forbidden
+                    404 - Not found
+                    500 - Server error
 ```
 
-#### Authentication Check
+#### Auth Check
 
 ```typescript
-// Verify auth before processing
 if (!req.user) {
   return res.status(401).json({ error: 'Unauthorized' });
 }
-
-// Check permissions
-if (!req.user.permissions.includes('create:posts')) {
+if (!hasPermission(req.user, 'create:posts')) {
   return res.status(403).json({ error: 'Forbidden' });
 }
 ```
 
-### Step 5: Verification
-
-**Test each endpoint:**
+### Step 5: Verify
 
 ```bash
-# Test with curl
+# Test endpoint
 curl -X POST http://localhost:3000/api/auth/login \
   -H "Content-Type: application/json" \
   -d '{"email":"test@test.com","password":"password123"}'
-
-# Expected: 200 with token
-# Or: 401 with error message
 ```
 
-**Verification checklist:**
+Checklist:
 ```
 [ ] Endpoint responds
 [ ] Correct status codes
-[ ] Response matches spec
 [ ] Validation rejects bad input
-[ ] Auth required endpoints reject anonymous
-[ ] Error messages are helpful but not leaky
+[ ] Auth works correctly
+[ ] Response matches spec
 ```
 
 ### Step 6: Document for Frontend
 
-After backend complete, document what frontend needs:
-
 ```markdown
-## API Ready for Frontend
+## API Ready
 
 ### POST /api/auth/login
-- **Auth**: None (public)
-- **Request**: `{ email: string, password: string }`
-- **Success (200)**: `{ token: string, user: { id, email, name } }`
-- **Errors**:
-  - 400: Invalid input
-  - 401: Invalid credentials
-
-### GET /api/users/me
-- **Auth**: Bearer token required
-- **Request**: None
-- **Success (200)**: `{ id, email, name, role }`
-- **Errors**:
-  - 401: No/invalid token
-```
-
-### Step 7: Hand Off to Testing
-
-After full implementation (backend + frontend), `/dev-coding` auto-triggers `/dev-test` which:
-
-```
-1. Navigate to UI (triggers API calls)
-2. Capture network requests
-3. Check for 4xx/5xx responses
-4. Report API failures
-```
-
-**What /dev-test catches for backend:**
-- 400 Bad Request (validation failures)
-- 401 Unauthorized (auth issues)
-- 403 Forbidden (permission issues)
-- 404 Not Found (wrong endpoints)
-- 500 Server Error (backend bugs)
-- CORS errors (misconfigured)
-- Timeout errors (slow queries)
-
-**Example test failure:**
-```markdown
-[Network] POST /api/auth/login returned 500
-Response: {"error":"Internal server error"}
-Likely cause: Database connection or missing env var
-```
-
-## Common Patterns
-
-### Database Query Patterns
-
-```typescript
-// Pagination
-const page = parseInt(req.query.page) || 1;
-const limit = parseInt(req.query.limit) || 10;
-const offset = (page - 1) * limit;
-
-const items = await db.items.findMany({
-  skip: offset,
-  take: limit,
-  orderBy: { createdAt: 'desc' }
-});
-
-// Filtering
-const where = {};
-if (req.query.status) {
-  where.status = req.query.status;
-}
-
-// Include relations
-const post = await db.posts.findUnique({
-  where: { id },
-  include: { author: true, comments: true }
-});
-```
-
-### Transaction Pattern
-
-```typescript
-// When multiple operations must succeed together
-await db.$transaction(async (tx) => {
-  const user = await tx.users.create({ data: userData });
-  await tx.profiles.create({ data: { userId: user.id } });
-  await tx.settings.create({ data: { userId: user.id } });
-  return user;
-});
-```
-
-### Soft Delete Pattern
-
-```typescript
-// Don't actually delete, mark as deleted
-await db.posts.update({
-  where: { id },
-  data: {
-    deletedAt: new Date(),
-    status: 'deleted'
-  }
-});
-
-// Query excludes deleted
-const posts = await db.posts.findMany({
-  where: { deletedAt: null }
-});
+- **Auth**: None
+- **Request**: `{ email, password }`
+- **Success (200)**: `{ token, user }`
+- **Errors**: 400 (invalid), 401 (wrong creds)
 ```
 
 ## Security Checklist
 
 ```
-[ ] Input validated before use
-[ ] SQL/NoSQL injection prevented (use parameterized queries)
-[ ] Auth checked on protected routes
-[ ] Permissions verified for actions
-[ ] Sensitive data not logged
-[ ] Passwords hashed (never plain text)
-[ ] Rate limiting on auth endpoints
-[ ] CORS configured correctly
-[ ] No secrets in code (use env vars)
+[ ] Input validated (Zod/Yup)
+[ ] Parameterized queries (no SQL injection)
+[ ] Auth on protected routes
+[ ] Permissions verified
+[ ] Passwords hashed
+[ ] Secrets in env vars
+[ ] No sensitive data in logs
 ```
 
-## Debugging
-
-### API Not Responding
+## Quick Debugging
 
 ```bash
-# Check if server running
+# Server running?
 curl http://localhost:3000/health
 
-# Check logs
-tail -f logs/server.log
+# Database connected?
+npx prisma db pull  # or check logs
 
-# Check port in use
-lsof -i :3000
+# Token valid?
+curl http://localhost:3000/api/me -H "Authorization: Bearer $TOKEN"
 ```
 
-### Database Issues
+## Stack-Specific Patterns
 
-```bash
-# Check connection
-npx prisma db pull  # Prisma
-psql -c "SELECT 1"  # PostgreSQL
-
-# Check migrations
-npx prisma migrate status
-```
-
-### Auth Issues
+**Do not implement generic patterns. Load from stacks/:**
 
-```bash
-# Test token validity
-curl http://localhost:3000/api/users/me \
-  -H "Authorization: Bearer $TOKEN"
+| Stack | What to load | Key patterns |
+|-------|--------------|--------------|
+| Directus | `stacks/directus/` | SDK queries, permissions, hooks |
+| Prisma | `stacks/prisma/` (future) | ORM patterns, migrations |
+| Supabase | `stacks/supabase/` (future) | RLS, auth, realtime |
 
-# Decode JWT (for debugging only)
-echo $TOKEN | cut -d. -f2 | base64 -d
+**Example - if using Directus:**
+```
+1. Read knowledge/stacks/directus/_index.md
+2. Use ItemsService (not raw SQL)
+3. Follow permission patterns
+4. Use SDK for queries
 ```
 
-## Tech-Specific References
+## Domain-Specific Logic
 
-Load additional patterns based on detected tech:
+**Load from domains/ when applicable:**
 
-| Tech | Reference File |
-|------|---------------|
-| Directus | `references/directus.md` |
-| Node/Express | `references/node.md` |
-| Prisma | `references/prisma.md` |
-| PostgreSQL | `references/postgresql.md` |
-| Supabase | `references/supabase.md` |
+| Domain | What to load | Key patterns |
+|--------|--------------|--------------|
+| SaaS | `domains/saas/_index.md` | Subscription states, billing |
+| E-commerce | `domains/ecommerce/_index.md` | Order lifecycle, inventory |
 
-These files contain tech-specific patterns, gotchas, and best practices. Add them as your projects use different stacks.
+**Example - SaaS billing endpoint:**
+```
+1. Read knowledge/domains/saas/_index.md
+2. Follow subscription state machine
+3. Handle trial → paid → cancelled states
+4. Validate against billing rules
+```