@codihaus/claude-skills 1.6.6 → 1.6.7

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

@@ -0,0 +1,130 @@
+# Backend Principles
+
+Universal backend engineering principles. Combine with tech-context.md for project-specific implementation.
+
+## API Design
+
+### Request/Response
+- Clear endpoint naming (resource-based, action verbs for non-CRUD)
+- Consistent response structure
+- Appropriate HTTP methods (GET, POST, PUT, DELETE, PATCH)
+- Meaningful status codes (200, 201, 400, 401, 403, 404, 500)
+
+### Validation
+- Validate all inputs at API boundary
+- Fail fast with clear error messages
+- Type checking for strong-typed languages
+- Sanitize inputs to prevent injection
+
+### Error Handling
+- Never expose internal errors to clients
+- Consistent error response format
+- Log errors with context (not just message)
+- Distinguish client errors (4xx) from server errors (5xx)
+
+### Authentication & Authorization
+- Authenticate at entry point (middleware/guard)
+- Separate authentication (who you are) from authorization (what you can do)
+- Never trust client-provided identity
+- Token expiration and refresh strategy
+
+## Data Access
+
+### Queries
+- Fetch only what you need (select specific fields)
+- Use indexes for frequently queried fields
+- Pagination for list endpoints (don't return unlimited results)
+- Avoid N+1 queries (use joins or batch loading)
+
+### Transactions
+- Use transactions for multi-step operations
+- Keep transactions short (acquire late, release early)
+- Handle rollback on failure
+- Idempotency for critical operations
+
+### Data Integrity
+- Validate at database level (constraints, foreign keys)
+- Handle concurrent updates (optimistic/pessimistic locking)
+- Soft deletes for critical data (deletedAt, not DELETE)
+- Audit trails for sensitive operations
+
+## Security
+
+### Input Validation
+- Whitelist valid inputs (not blacklist)
+- Validate type, format, range, length
+- Escape/sanitize for context (SQL, HTML, shell)
+- Rate limiting for public endpoints
+
+### Secrets Management
+- Never commit secrets to code
+- Use environment variables or secret managers
+- Rotate secrets regularly
+- Different secrets per environment
+
+### Data Protection
+- Encrypt sensitive data at rest
+- Hash passwords (bcrypt, argon2 - never plain text)
+- Use HTTPS for data in transit
+- Minimize PII collection and storage
+
+## Performance
+
+### Caching
+- Cache expensive computations
+- Cache at appropriate level (CDN, app, database)
+- Invalidation strategy (TTL, event-based)
+- Don't cache sensitive/user-specific data without care
+
+### Async Operations
+- Long-running tasks → background jobs
+- Don't block request/response for slow operations
+- Use queues for reliability
+- Status endpoints for async tasks
+
+### Resource Management
+- Connection pooling for databases
+- Timeouts on external calls
+- Graceful degradation on external service failure
+- Circuit breakers for cascading failures
+
+## Code Organization
+
+### Structure
+- Separate concerns (routes, business logic, data access)
+- Thin controllers/handlers (orchestration only)
+- Business logic in service layer
+- Data access in repository/DAO layer
+
+### Modularity
+- Single responsibility per module/function
+- Dependencies injected (not hard-coded)
+- Testable units (pure functions where possible)
+- Clear interfaces/contracts
+
+### Error Propagation
+- Let errors bubble up with context
+- Handle at appropriate level (not everywhere)
+- Distinguish recoverable vs fatal errors
+- Structured logging for debugging
+
+## Testing
+
+### What to Test
+- Business logic (unit tests)
+- API contracts (integration tests)
+- Error paths (especially edge cases)
+- Security constraints (auth, validation)
+
+### Test Strategy
+- Fast tests in inner layers (business logic)
+- Slower tests at boundaries (API, database)
+- Mock external dependencies
+- Test data isolation (no shared state)
+
+## Remember
+
+These are universal principles. Your project implements them specifically:
+- Check tech-context.md for HOW your project does these
+- Example: "API validation" → project uses Zod schemas in schemas/
+- Example: "Data access" → project uses Directus SDK, not raw SQL

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

@@ -0,0 +1,212 @@
+# Frontend Principles
+
+Universal frontend engineering principles. Combine with tech-context.md for project-specific implementation.
+
+## Component Design
+
+### Structure
+- Single responsibility (one job per component)
+- Composition over inheritance
+- Props for configuration, not implementation details
+- Clear component boundaries
+
+### Reusability
+- Generic components (Button, Input) for reuse
+- Feature components (LoginForm) for specific use cases
+- Avoid premature abstraction (3 uses before extracting)
+- Props API for flexibility
+
+### State
+- Local state for UI-only concerns
+- Shared state for cross-component data
+- Lift state up when needed, not preemptively
+- Derive computed values (don't duplicate state)
+
+## Data Fetching
+
+### Loading States
+- Show loading indicators for async operations
+- Skeleton loaders for expected content
+- Don't block UI while fetching
+- Handle slow networks gracefully
+
+### Error Handling
+- Display errors to users (don't fail silently)
+- Retry strategies for transient failures
+- Fallback UI for critical errors
+- Clear error messages (not technical jargon)
+
+### Caching
+- Cache fetched data (avoid re-fetching)
+- Invalidate on mutations
+- Stale-while-revalidate pattern
+- Consider server state libraries
+
+## Forms & Validation
+
+### Validation Timing
+- Validate on blur (not on every keystroke)
+- Show errors after user interaction
+- Re-validate on change after first error
+- Block submit if invalid
+
+### User Experience
+- Clear labels and placeholders
+- Inline validation messages
+- Disable submit during submission
+- Show success feedback
+- Preserve form data on error
+
+### Data Flow
+- Controlled components (single source of truth)
+- Schema-based validation (define once, use everywhere)
+- Handle server-side validation errors
+- Optimistic updates with rollback
+
+## Performance
+
+### Rendering
+- Avoid unnecessary re-renders
+- Memoize expensive computations
+- Virtualize long lists
+- Lazy load below-the-fold content
+
+### Bundle Size
+- Code splitting for routes
+- Lazy load heavy components
+- Tree-shake unused code
+- Optimize images and assets
+
+### User Perception
+- Perceived performance > actual performance
+- Instant feedback on interaction
+- Optimistic UI updates
+- Progressive enhancement
+
+## Accessibility
+
+### Semantics
+- Use semantic HTML (button, nav, main, etc.)
+- Proper heading hierarchy (h1 → h6)
+- Label form inputs (for/id association)
+- Alt text for images
+
+### Keyboard Navigation
+- All interactive elements keyboard accessible
+- Logical tab order
+- Visible focus indicators
+- Keyboard shortcuts for power users
+
+### Screen Readers
+- ARIA labels when semantic HTML insufficient
+- Announce dynamic content changes
+- Skip links for navigation
+- Test with actual screen readers
+
+## State Management
+
+### When to Use
+- Cross-component data → shared state
+- UI-only state → local state
+- Server data → server state library
+- URL state → query parameters
+
+### Patterns
+- Single source of truth (no duplication)
+- Unidirectional data flow
+- Immutable updates
+- Clear action/mutation names
+
+### Avoid
+- Global state for everything (over-engineering)
+- Prop drilling (use context or state library)
+- Mixing server and client state
+- State synchronization bugs
+
+## Security
+
+### XSS Prevention
+- Never use dangerouslySetInnerHTML without sanitization
+- Escape user content before rendering
+- Use framework's built-in escaping
+- Content Security Policy headers
+
+### Sensitive Data
+- Don't store secrets in frontend code
+- Don't expose tokens in URLs
+- Clear sensitive data on logout
+- HTTPS only for auth
+
+### Authentication
+- Check auth state before sensitive operations
+- Handle token expiration gracefully
+- Redirect to login on 401
+- Secure token storage (httpOnly cookies preferred)
+
+## Code Organization
+
+### File Structure
+- Colocate related files (component + styles + tests)
+- Feature-based or type-based folders (pick one)
+- Index files for clean imports
+- Clear naming conventions
+
+### Separation of Concerns
+- Presentation components (dumb, UI only)
+- Container components (smart, data fetching)
+- Utility functions (pure, testable)
+- Business logic separate from UI
+
+### Dependencies
+- Minimize external dependencies
+- Use established libraries for complex problems
+- Avoid deprecated/unmaintained packages
+- Regular dependency updates
+
+## Testing
+
+### What to Test
+- User interactions (click, type, submit)
+- Component rendering with props
+- Error states
+- Accessibility (ARIA, keyboard navigation)
+
+### Test Strategy
+- Unit tests for utility functions
+- Component tests for behavior
+- Integration tests for user flows
+- Visual regression for styling
+
+### Avoid
+- Testing implementation details
+- Brittle selectors (use test IDs or ARIA labels)
+- Testing library code
+- Slow E2E tests for everything
+
+## User Experience
+
+### Feedback
+- Instant response to user actions
+- Progress indicators for long operations
+- Success/error notifications
+- Undo for destructive actions
+
+### Consistency
+- Consistent patterns across app
+- Familiar UI paradigms
+- Predictable navigation
+- Reusable components for consistency
+
+### Responsiveness
+- Mobile-first or desktop-first (pick one)
+- Touch targets minimum 44x44px
+- Readable text size (16px minimum)
+- Works on slow connections
+
+## Remember
+
+These are universal principles. Your project implements them specifically:
+- Check tech-context.md for HOW your project does these
+- Example: "Data fetching" → project uses composables in composables/
+- Example: "Validation" → project uses Zod schemas + react-hook-form
+- Example: "State" → project uses Pinia stores in stores/