wicked-garden 12.27.0

package/skills/engineering/frontend/refs/checklists.md

@@ -0,0 +1,96 @@
+---
+phase_relevance: ["design", "build"]
+archetype_relevance: ["*"]
+---
+# Frontend Review Checklists
+
+## Component Quality Checklist
+- [ ] Single responsibility
+- [ ] Clear prop interface
+- [ ] Proper TypeScript/PropTypes
+- [ ] Reusable and composable
+- [ ] Handles edge cases
+
+## React Best Practices Checklist
+- [ ] Hook dependencies correct
+- [ ] Effects have cleanup
+- [ ] No unnecessary re-renders
+- [ ] Keys used correctly in lists
+- [ ] No mutating state directly
+
+## Styling Checklist
+- [ ] Responsive design
+- [ ] Accessibility (contrast, sizing)
+- [ ] Consistent with design system
+- [ ] Performant animations
+
+## Accessibility Checklist
+- [ ] Semantic HTML
+- [ ] Keyboard navigation
+- [ ] Screen reader friendly
+- [ ] ARIA where needed
+- [ ] Focus indicators visible
+
+## Common Anti-Patterns
+
+### React Anti-Patterns
+- Missing hook dependencies (stale closures)
+- Using index as key in dynamic lists
+- Not cleaning up effects (memory leaks)
+- Inline function creation in render
+- Direct state mutation
+
+### CSS Anti-Patterns
+- Fixed pixel widths for layouts
+- Excessive !important
+- Non-semantic class names
+- Animations not GPU-accelerated
+
+### Accessibility Anti-Patterns
+- Using div instead of button
+- Missing alt text on images
+- Poor color contrast
+- No keyboard navigation
+- Missing focus indicators
+
+### Performance Anti-Patterns
+- Large bundles without code splitting
+- Not using lazy loading
+- Unnecessary re-renders
+- Unoptimized images
+- No debouncing on input handlers
+
+## Output Template
+
+```markdown
+## Frontend Review: {Component/Feature}
+
+### Component Design
+{Assessment of structure and patterns}
+
+### React Implementation
+{Hook usage, state management, performance}
+
+### Styling
+{CSS quality, responsiveness}
+
+### Accessibility
+{A11y compliance and recommendations}
+
+### Issues
+| Severity | Issue | Location | Fix |
+|----------|-------|----------|-----|
+| {Level} | {Problem} | {File:line} | {Solution} |
+
+### Recommendations
+1. {Priority item}
+2. {Secondary item}
+```
+
+## Tools
+
+- React DevTools for profiling
+- Browser DevTools for CSS/performance
+- Lighthouse for a11y and performance
+- React Testing Library for testing
+- axe DevTools for accessibility

package/skills/engineering/frontend/refs/patterns.md

@@ -0,0 +1,167 @@
+---
+phase_relevance: ["design", "build"]
+archetype_relevance: ["*"]
+---
+# Frontend Code Patterns
+
+## Component Structure Pattern
+
+```jsx
+interface Props {
+  title: string;
+  items: Item[];
+  onSelect: (item: Item) => void;
+}
+
+export const ItemList = ({ title, items, onSelect }: Props) => {
+  return (
+    <section aria-labelledby="list-title">
+      <h2 id="list-title">{title}</h2>
+      <ul role="list">
+        {items.map(item => (
+          <li key={item.id}>
+            <button onClick={() => onSelect(item)}>
+              {item.name}
+            </button>
+          </li>
+        ))}
+      </ul>
+    </section>
+  );
+};
+```
+
+## Custom Hook Pattern
+
+```jsx
+function useDebounce(value, delay) {
+  const [debouncedValue, setDebouncedValue] = useState(value);
+
+  useEffect(() => {
+    const timer = setTimeout(() => setDebouncedValue(value), delay);
+    return () => clearTimeout(timer);
+  }, [value, delay]);
+
+  return debouncedValue;
+}
+```
+
+## React Best Practices
+
+### Hook Dependencies
+- Always include all dependencies in useEffect/useMemo/useCallback
+- Avoid stale closures
+
+### Effect Cleanup
+```jsx
+useEffect(() => {
+  const subscription = api.subscribe(data => {
+    setData(data);
+  });
+
+  // Cleanup to prevent memory leaks
+  return () => subscription.unsubscribe();
+}, []);
+```
+
+### Keys in Lists
+- Use stable unique IDs, not array indexes
+- Index as key only for static lists
+
+### Performance Optimization
+```jsx
+// Memoize expensive computations
+const sorted = useMemo(() =>
+  items.sort((a, b) => a.name.localeCompare(b.name)),
+  [items]
+);
+
+// Memoize callbacks to prevent re-renders
+const handleClick = useCallback(() => {
+  doSomething(id);
+}, [id]);
+```
+
+## CSS Patterns
+
+### Responsive Design
+```css
+/* Mobile-first approach */
+.container {
+  padding: 1rem;
+  display: flex;
+  flex-direction: column;
+}
+
+/* Tablet and up */
+@media (min-width: 768px) {
+  .container {
+    flex-direction: row;
+    padding: 2rem;
+  }
+}
+```
+
+### Modern CSS Features
+```css
+/* Custom properties for theming */
+:root {
+  --color-primary: #007bff;
+  --spacing-unit: 8px;
+}
+
+/* Container queries */
+@container (min-width: 400px) {
+  .card {
+    display: grid;
+    grid-template-columns: 1fr 2fr;
+  }
+}
+```
+
+### GPU-Accelerated Animations
+```css
+/* Use transform and opacity for smooth animations */
+.fade-in {
+  animation: fadeIn 0.3s ease-in;
+}
+
+@keyframes fadeIn {
+  from {
+    opacity: 0;
+    transform: translateY(10px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+```
+
+## Accessibility Patterns
+
+### Semantic HTML
+```jsx
+// Good
+<button onClick={handleClick}>Submit</button>
+
+// Bad
+<div onClick={handleClick}>Submit</div>
+```
+
+### ARIA Labels
+```jsx
+<button aria-label="Close dialog" onClick={onClose}>
+  <CloseIcon />
+</button>
+```
+
+### Keyboard Navigation
+```jsx
+const handleKeyDown = (e: React.KeyboardEvent) => {
+  if (e.key === 'Enter' || e.key === ' ') {
+    e.preventDefault();
+    handleClick();
+  }
+};
+```

package/skills/engineering/integration/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: integration
+description: |
+  Design API contracts, service boundaries, and integration patterns.
+  Define how components and services communicate and interoperate.
+
+  Use when: "API design", "service integration", "how do these communicate",
+  "API contract", "integration pattern", "REST API", "GraphQL", "event schema"
+portability: portable
+phase_relevance: ["design", "build"]
+archetype_relevance: ["*"]
+---
+
+# Integration Skill
+
+Design robust, well-documented integration points between components and services.
+
+## Purpose
+
+Define communication contracts:
+- API design (REST, GraphQL, gRPC)
+- Event schema definition
+- Integration pattern selection
+- Error handling and resilience
+
+## Process
+
+### 1. Identify Integration Points
+
+Map communication:
+- Component-to-component
+- Service-to-service
+- Client-to-server
+- External integrations
+- Event flows
+
+### 2. Choose Pattern
+
+Select approach:
+- **Request/Response** - Sync, immediate result
+- **Publish/Subscribe** - Async, one-to-many
+- **Event Sourcing** - Audit trail, replay
+- **API Gateway** - Unified entry point
+
+### 3. Design Contracts
+
+Define specifications:
+- OpenAPI for REST
+- GraphQL schemas
+- Protocol Buffers for gRPC
+- Event schemas (JSON Schema)
+
+### 4. Plan Resilience
+
+Handle failures:
+- Retry strategies
+- Circuit breakers
+- Timeouts
+- Fallback behaviors
+
+## Output
+
+Creates in `phases/design/`:
+```
+design/
+├── integration/
+│   ├── overview.md
+│   ├── api-specs/
+│   │   ├── openapi.yaml
+│   │   └── events.json
+│   └── patterns.md
+```
+
+## Integration Patterns
+
+### REST API
+Resource-oriented, stateless, HTTP verbs.
+See [REST API Fundamentals](refs/rest-api-fundamentals.md) and [Responses & Security](refs/rest-api-responses-security.md).
+
+### GraphQL
+Flexible queries, strong typing.
+See GraphQL guides in refs/ (graphql-graphql-basics.md, graphql-schema-design-patterns.md).
+
+### gRPC
+High performance, service-to-service.
+See gRPC guides in refs/ (grpc-grpc-overview.md, grpc-implementation-examples.md).
+
+### Event-Driven
+Async messaging, pub/sub.
+See event schema guides in refs/ (event-schemas-event-structure.md, event-schemas-best-practices.md).
+
+## Error Handling
+
+Standard HTTP status codes:
+- 2xx: Success (200 OK, 201 Created, 204 No Content)
+- 4xx: Client errors (400, 401, 404, 409)
+- 5xx: Server errors (500, 503)
+
+See error handling guides in refs/ (error-handling-error-response-format.md, error-handling-best-practices.md).
+
+## Resilience Patterns
+
+- **Circuit Breaker** - Prevent cascading failures
+- **Retry with Backoff** - Exponential retry delays
+- **Timeouts** - Fail fast on slow responses
+- **Fallbacks** - Graceful degradation
+
+See resilience guides in refs/ (resilience-circuit-breaker-pattern.md, resilience-best-practices.md).
+
+## Versioning
+
+Common strategies:
+- URL versioning: `/api/v1/resources`
+- Header versioning: `Accept: application/vnd.api+json; version=1`
+
+See versioning guides in refs/ (versioning-versioning-strategies.md, versioning-migration-strategies.md).
+
+## Integration
+
+### With System Design
+
+Takes component boundaries and defines:
+- Interfaces between components
+- Data contracts
+- Communication patterns
+
+### With Data Architecture
+
+Coordinates on:
+- API data models
+- Event payloads
+- Serialization formats
+
+## Events
+
+- `[arch:contract:defined:success]` - API contract created
+- `[arch:api:validated:success]` - API spec validated
+- `[arch:event:schema:defined:success]` - Event schema documented
+
+## Tips
+
+1. **API-First Design** - Design before implementation
+2. **Version from Start** - Plan for evolution
+3. **Document Well** - Specs are executable docs
+4. **Error Handling** - Comprehensive error responses
+5. **Idempotency** - Make operations repeatable safely
+6. **Security** - Auth/authz from the beginning
+
+## Reference Materials
+
+- REST API:
+  - [Fundamentals](refs/rest-api-fundamentals.md)
+  - [Responses & Security](refs/rest-api-responses-security.md)
+- GraphQL:
+  - [Basics](refs/graphql-graphql-basics.md)
+  - [Query Examples](refs/graphql-query-examples.md)
+  - [Schema Design](refs/graphql-schema-design-patterns.md)
+  - [Error Handling](refs/graphql-error-handling.md)
+  - [Best Practices](refs/graphql-best-practices.md)
+- gRPC:
+  - [Overview](refs/grpc-grpc-overview.md)
+  - [Implementation](refs/grpc-implementation-examples.md)
+  - [Metadata & Headers](refs/grpc-metadata-headers.md)
+  - [Testing](refs/grpc-testing.md)
+- Event Schemas:
+  - [Event Structure](refs/event-schemas-event-structure.md)
+  - [Naming Conventions](refs/event-schemas-event-naming-conventions.md)
+  - [Best Practices](refs/event-schemas-best-practices.md)
+- Error Handling:
+  - [Response Format](refs/error-handling-error-response-format.md)
+  - [Error Classes (TS)](refs/error-handling-error-classes-typescript.md)
+  - [Retry Strategies](refs/error-handling-retry-strategies.md)
+  - [Best Practices](refs/error-handling-best-practices.md)
+- Resilience:
+  - [Circuit Breaker](refs/resilience-circuit-breaker-pattern.md)
+  - [Timeout & Bulkhead](refs/resilience-timeout-pattern.md)
+  - [Rate Limiting](refs/resilience-rate-limiting.md)
+  - [Best Practices](refs/resilience-best-practices.md)
+- Versioning:
+  - [Strategies](refs/versioning-versioning-strategies.md)
+  - [Migration](refs/versioning-migration-strategies.md)
+  - [Breaking Changes](refs/versioning-breaking-changes.md)
+- [OpenAPI Template](refs/openapi-template.yaml)

package/skills/engineering/integration/refs/error-handling-best-practices.md

@@ -0,0 +1,139 @@
+---
+phase_relevance: ["design", "build"]
+archetype_relevance: ["*"]
+---
+# Error Handling Guide: Best Practices
+
+## Best Practices
+
+### 1. Use Specific Error Codes
+
+```typescript
+// Good
+throw new ValidationError([
+  { field: 'email', code: 'INVALID_FORMAT', message: '...' }
+]);
+
+// Bad
+throw new Error('Validation failed');
+```
+
+### 2. Include Request ID
+
+Always include request ID for tracing:
+```typescript
+res.status(500).json({
+  error: {
+    message: 'Internal error',
+    request_id: req.id  // Client can provide this to support
+  }
+});
+```
+
+### 3. Don't Expose Sensitive Details
+
+```typescript
+// Bad - exposes database structure
+{
+  "error": "ER_DUP_ENTRY: Duplicate entry 'user@example.com' for key 'users.email_unique'"
+}
+
+// Good - sanitized message
+{
+  "error": {
+    "code": "CONFLICT",
+    "message": "User with this email already exists"
+  }
+}
+```
+
+### 4. Distinguish Client vs Server Errors
+
+```typescript
+if (error.status >= 400 && error.status < 500) {
+  // Client error - safe to show details
+  return error.message;
+} else {
+  // Server error - hide details
+  return 'An unexpected error occurred';
+}
+```
+
+### 5. Provide Actionable Messages
+
+```typescript
+// Bad
+{ "error": "Invalid input" }
+
+// Good
+{
+  "error": {
+    "message": "Email address is required and must be in valid format",
+    "field": "email",
+    "example": "user@example.com"
+  }
+}
+```
+
+### 6. Handle Async Errors
+
+Always catch async errors:
+```typescript
+// Good
+app.get('/users', asyncHandler(async (req, res) => {
+  const users = await userService.findAll();
+  res.json({ users });
+}));
+
+// Bad - unhandled promise rejection
+app.get('/users', async (req, res) => {
+  const users = await userService.findAll();
+  res.json({ users });
+});
+```
+
+### 7. Centralized Error Handling
+
+Use middleware for consistent error responses:
+```typescript
+app.use(errorHandler);
+```
+
+### 8. Log Appropriately
+
+```typescript
+// Error severity levels
+logger.error('Critical error', error);  // Requires immediate attention
+logger.warn('Recoverable error', error); // Should be monitored
+logger.info('Expected error', error);    // Part of normal flow
+```
+
+### 9. Graceful Degradation
+
+```typescript
+try {
+  const recommendations = await recommendationService.get(userId);
+  return recommendations;
+} catch (error) {
+  // Log error but don't fail the request
+  logger.warn('Recommendations unavailable', error);
+  return []; // Return empty array as fallback
+}
+```
+
+### 10. Test Error Scenarios
+
+```typescript
+describe('User creation', () => {
+  it('should return 409 for duplicate email', async () => {
+    await createUser({ email: 'test@example.com' });
+
+    const response = await request(app)
+      .post('/users')
+      .send({ email: 'test@example.com' });
+
+    expect(response.status).toBe(409);
+    expect(response.body.error.code).toBe('CONFLICT');
+  });
+});
+```