@codihaus/claude-skills 1.6.6 → 1.6.8

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/

package/skills/dev-review/SKILL.md

@@ -69,250 +69,75 @@ Reviews can be based on:
 - Clean separation of concerns
 ```
 
-## Workflow
+## Expected Outcome
+
+Review report with verdict and categorized issues.
+
+**Report includes:**
+- Verdict (Approve/Request Changes/Needs Discussion)
+- Issues found (by severity: critical/important/suggestion)
+- Issues by file
+- Positives (acknowledge good work)
+- Spec compliance (if UC provided)
+
+## Success Criteria
+
+- Security risks identified
+- Quality issues found
+- Spec compliance verified
+- Conventions checked
+- Constructive feedback with suggested fixes
+- Clear verdict given
+
+## Review Focus Areas
+
+### Security
+- Input validation (sanitized, injection prevented, XSS prevented)
+- Authentication (required where needed, tokens validated, sessions secure)
+- Authorization (permissions checked, data access restricted, admin protected)
+- Data protection (passwords hashed, sensitive data not logged, no secrets in code)
+- API security (rate limiting, CORS, no sensitive data in URLs)
+
+### Quality
+- Error handling (caught, user-friendly messages, logged, not swallowed)
+- Performance (no N+1 queries, pagination on lists, async heavy ops, no memory leaks)
+- Maintainability (readable, functions not too long, no magic values, DRY)
+- Testing (new code tested, edge cases covered, meaningful tests)
+
+### Conventions
+- Naming (variables, files, components per scout)
+- Structure (correct location, follows patterns, organized imports)
+- Style (matches configs, consistent, no linting errors)
+- Git (proper commit format, no unrelated changes, no debug code)
 
-### Phase 1: Gather Context
-
-```
-1. Get changes to review
-   → git diff (uncommitted)
-   → git diff --staged (staged only)
-   → Read specific files
-
-2. Read project conventions
-   → plans/scout/README.md (Conventions section)
-   → CLAUDE.md
-   → .eslintrc, tsconfig.json
-
-3. Read stack.md and stack knowledge
-   → plans/scout/stack.md
-   → Check "Stack Knowledge References" section
-   → Read each referenced knowledge/stacks/*.md file
-   → Use "For /dev-review" sections for review checklists
-
-   Examples:
-   - Directus project → Read knowledge/stacks/directus/_index.md
-   - Nuxt project → Read knowledge/stacks/nuxt/_index.md
-   - Next.js project → Read knowledge/stacks/nextjs/_index.md
-
-4. Read related spec (if UC provided)
-   → plans/features/{feature}/specs/{UC}/README.md
-```
-
-### Phase 1.5: Load Quality Attributes
-
-Load ALL levels from `_quality-attributes.md` for comprehensive verification:
-
-```
-1. Architecture Level
-   → Were architecture decisions followed?
-   → Any deviations from architecture.md?
-
-2. Specification Level
-   → Does implementation match spec?
-   → API patterns correct?
-
-3. Implementation Level
-   → Code quality checks
-   → Security, performance, reliability
-
-4. Review Level (meta)
-   → Can a new developer understand this?
-   → Would you want to maintain this?
-```
-
-### Phase 2: Analyze Changes
-
-For each changed file:
-
-```
-1. Understand the change
-   - What was added/modified/removed?
-   - What is the intent?
-
-2. Check against spec (if available)
-   - Does implementation match spec?
-   - Any missing requirements?
-
-3. Check against architecture (if exists)
-   - Does it follow architecture.md patterns?
-   - Any undocumented architecture decisions?
-
-4. Run through quality attribute checklists
-   - Scalability
-   - Maintainability
-   - Performance
-   - Security
-   - Reliability
-   - Testability
-```
-
-### Phase 3: Security Review
-
-```markdown
-## Security Checklist
-
-[ ] **Input Validation**
-    - User input sanitized?
-    - SQL/NoSQL injection prevented?
-    - XSS prevented (HTML escaped)?
-
-[ ] **Authentication**
-    - Auth required where needed?
-    - Token validated correctly?
-    - Session handled securely?
-
-[ ] **Authorization**
-    - Permissions checked?
-    - Can't access others' data?
-    - Admin functions protected?
-
-[ ] **Data Protection**
-    - Passwords hashed?
-    - Sensitive data not logged?
-    - No secrets in code?
-
-[ ] **API Security**
-    - Rate limiting present?
-    - CORS configured?
-    - No sensitive data in URLs?
-```
-
-**Common Security Issues:**
-
-```typescript
-// BAD: SQL injection
-const query = `SELECT * FROM users WHERE id = ${userId}`;
-
-// GOOD: Parameterized
-const query = `SELECT * FROM users WHERE id = $1`;
-await db.query(query, [userId]);
-
-// BAD: XSS vulnerable
-element.innerHTML = userInput;
-
-// GOOD: Escaped
-element.textContent = userInput;
-
-// BAD: Hardcoded secret
-const apiKey = "sk-1234567890";
-
-// GOOD: Environment variable
-const apiKey = process.env.API_KEY;
-```
-
-### Phase 4: Quality Review
-
-```markdown
-## Quality Checklist
-
-[ ] **Error Handling**
-    - Errors caught and handled?
-    - User-friendly error messages?
-    - Errors logged for debugging?
-    - No swallowed errors?
-
-[ ] **Performance**
-    - No N+1 queries?
-    - Large lists paginated?
-    - Heavy operations async?
-    - No memory leaks?
-
-[ ] **Maintainability**
-    - Code readable?
-    - Functions not too long?
-    - No magic numbers/strings?
-    - DRY (no unnecessary duplication)?
-
-[ ] **Testing**
-    - New code has tests?
-    - Edge cases covered?
-    - Tests actually test something?
-```
-
-**Common Quality Issues:**
-
-```typescript
-// BAD: N+1 query
-const posts = await getPosts();
-for (const post of posts) {
-  post.author = await getUser(post.authorId); // Query per post!
-}
-
-// GOOD: Batch query
-const posts = await getPosts({ include: { author: true } });
-
-// BAD: Swallowed error
-try {
-  await doSomething();
-} catch (e) {
-  // Nothing - error disappears!
-}
-
-// GOOD: Handle or rethrow
-try {
-  await doSomething();
-} catch (e) {
-  logger.error('Failed to do something', e);
-  throw new AppError('Operation failed', e);
-}
-
-// BAD: Magic number
-if (retries > 3) { ... }
-
-// GOOD: Named constant
-const MAX_RETRIES = 3;
-if (retries > MAX_RETRIES) { ... }
-```
-
-### Phase 5: Convention Review
-
-```markdown
-## Convention Checklist (from scout)
-
-[ ] **Naming**
-    - Variables: {convention from scout}
-    - Files: {convention from scout}
-    - Components: {convention from scout}
-
-[ ] **Structure**
-    - File in correct location?
-    - Follows project patterns?
-    - Imports organized?
-
-[ ] **Style**
-    - Matches .prettierrc / .eslintrc?
-    - Consistent with codebase?
-    - No linting errors?
-
-[ ] **Git**
-    - Commit message format correct?
-    - No unrelated changes?
-    - No debug code / console.log?
-```
-
-### Phase 6: Spec Compliance (if UC provided)
-
-```markdown
-## Spec Compliance
+### Spec Compliance
+- Requirements met (all implemented)
+- Requirements not met (missing items)
+- Not in spec (unauthorized additions)
 
-### Requirements Met
-- [x] Login endpoint created
-- [x] Returns token on success
-- [x] Returns error on invalid credentials
+### Stack-Specific
+Read stack knowledge files (knowledge/stacks/) for stack-specific review checklists.
 
-### Requirements Not Met
-- [ ] Rate limiting not implemented (spec said 5 attempts/min)
+Examples:
+- Directus: Check for proper collection usage, field types, permissions
+- Nuxt: Check for composables, server routes, nitro patterns
+- Next.js: Check for App Router patterns, server components, actions
 
-### Not in Spec
-- Added "remember me" checkbox (is this approved?)
-```
+## Context Sources
 
-### Phase 7: Generate Review
+**Read to understand what was changed:**
+- git diff (uncommitted or staged)
+- Specific files (if provided)
 
-Compile findings into review output format.
+**Read to understand standards:**
+- tech-context.md - Project conventions
+- stack knowledge files - Stack-specific patterns
+- architecture.md - Architecture decisions
+- spec - Requirements (if UC provided)
+- _quality-attributes.md - ALL levels (Architecture, Specification, Implementation, Review)
+- Config files (.eslintrc, tsconfig.json)
 
-**Severity Levels:**
+## Severity Levels
 
 | Level | Icon | Meaning | Action |
 |-------|------|---------|--------|
@@ -321,7 +146,7 @@ Compile findings into review output format.
 | Suggestion | 🔵 | Style, improvements | Nice to have |
 | Positive | ✅ | Good practice noted | Encouragement |
 
-**Review Verdicts:**
+## Verdicts
 
 | Verdict | When |
 |---------|------|