sinapse-ai 7.0.5 → 7.2.0

package/squads/claude-code-mastery/templates/claude-md-library.md

@@ -0,0 +1,175 @@
+# CLAUDE.md — Library / Package Project
+
+## Project Overview
+
+- **Name:** [PACKAGE_NAME]
+- **Description:** [What this library does]
+- **Type:** Reusable library / npm package
+- **Registry:** npm (public / private)
+- **Status:** [Alpha / Beta / Stable]
+- **Current Version:** [X.Y.Z]
+
+## Tech Stack
+
+| Layer | Technology | Notes |
+|-------|-----------|-------|
+| Language | TypeScript | Strict mode enabled |
+| Bundler | tsup / Rollup / Vite | Dual ESM + CJS output |
+| Testing | Vitest / Jest | Unit + integration |
+| Linting | ESLint + Prettier | Strict rules for library code |
+| Docs | TypeDoc / TSDoc | Auto-generated API docs |
+
+## API Surface
+
+### Public Exports (src/index.ts)
+
+All public API is exported from the package entry point. Every export is part of the
+public contract and subject to semver guarantees.
+
+```typescript
+// src/index.ts — the single source of truth for public API
+export { createClient } from './client';
+export { validate } from './validators';
+export type { ClientOptions, ValidationResult } from './types';
+```
+
+### Internal vs Public
+
+| Directory | Visibility | Semver Contract |
+|-----------|-----------|----------------|
+| `src/index.ts` | PUBLIC | Breaking changes = major bump |
+| `src/` (non-exported) | INTERNAL | Can change freely |
+| `src/internal/` | INTERNAL | Never import from outside |
+| `src/__tests__/` | INTERNAL | Test utilities, not shipped |
+
+### Rules
+- Never export from subdirectories directly; always re-export through `src/index.ts`
+- Prefix internal utilities with `_` or place in `src/internal/`
+- Every public function must have TSDoc comments with `@example` blocks
+- Every public type must be explicitly exported (no implicit exports via inference)
+
+## Backward Compatibility
+
+### Semver Rules
+- **MAJOR (X.0.0):** Removing exports, changing function signatures, renaming types
+- **MINOR (0.X.0):** Adding new exports, adding optional parameters, new features
+- **PATCH (0.0.X):** Bug fixes, performance improvements, documentation
+
+### Breaking Change Checklist
+Before any major version bump:
+- [ ] Document all breaking changes in CHANGELOG.md
+- [ ] Provide migration guide
+- [ ] Update all examples and documentation
+- [ ] Consider deprecation period (mark deprecated in minor, remove in next major)
+
+### Deprecation Pattern
+```typescript
+/**
+ * @deprecated Use `createClientV2()` instead. Will be removed in v3.0.0.
+ */
+export function createClient(options: OldOptions): Client {
+  console.warn('createClient is deprecated. Use createClientV2 instead.');
+  return createClientV2(migrateOptions(options));
+}
+```
+
+## Versioning
+
+- Follow [Semantic Versioning 2.0.0](https://semver.org/)
+- Use `npm version patch|minor|major` to bump
+- Tag releases: `git tag v1.2.3`
+- Maintain CHANGELOG.md with [Keep a Changelog](https://keepachangelog.com/) format
+
+## Testing Strategy
+
+### Test Categories
+- **Unit tests:** Every public function, edge cases, error conditions
+- **Integration tests:** Module interactions, real-world usage patterns
+- **Type tests:** Verify TypeScript types with `tsd` or `expect-type`
+- **Snapshot tests:** For serializable outputs (optional)
+
+### Coverage Requirements
+- Public API: 100% branch coverage
+- Internal utilities: 80% coverage minimum
+- Type inference: Tested with `expectTypeOf` assertions
+
+### Commands
+```bash
+npm test                  # Run all tests
+npm test -- --coverage    # With coverage report
+npm test -- --watch       # Watch mode during development
+npm run test:types        # Type-level tests
+```
+
+## Documentation Requirements
+
+### TSDoc on Every Public Export
+```typescript
+/**
+ * Creates a new client instance with the given options.
+ *
+ * @param options - Configuration options for the client
+ * @returns A configured client instance
+ * @throws {ValidationError} If options are invalid
+ *
+ * @example
+ * ```typescript
+ * const client = createClient({ apiKey: 'xxx', timeout: 5000 });
+ * const result = await client.query('hello');
+ * ```
+ */
+export function createClient(options: ClientOptions): Client {
+  // ...
+}
+```
+
+### README Sections
+- Installation instructions
+- Quick start example
+- API reference (link to generated docs)
+- Configuration options table
+- Error handling guide
+- Migration guides (for major versions)
+
+## Build Commands
+
+```bash
+npm run build             # Build for distribution (ESM + CJS)
+npm run dev               # Watch mode for development
+npm run lint              # Lint source code
+npm run lint:fix          # Auto-fix lint issues
+npm run typecheck         # TypeScript type checking
+npm run docs              # Generate API documentation
+npm run prepublishOnly    # Pre-publish checks (lint + test + build)
+```
+
+## Package.json Fields
+
+```jsonc
+{
+  "name": "@scope/package-name",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist", "README.md", "CHANGELOG.md"],
+  "sideEffects": false
+}
+```
+
+## Important Notes
+
+- Always run the full test suite before publishing
+- Never publish with `--force` or `--no-git-checks`
+- Keep `files` field in package.json minimal (only ship dist/)
+- Test the package locally with `npm link` before publishing
+- Peer dependencies should use wide version ranges (`>=17.0.0`)
+- Bundle size matters: use `bundlephobia` to check before release

package/squads/claude-code-mastery/templates/claude-md-microservices.md

@@ -0,0 +1,186 @@
+# CLAUDE.md — Microservices Project
+
+## Project Overview
+
+- **Name:** [PROJECT_NAME]
+- **Description:** [System description]
+- **Type:** Microservices architecture
+- **Deployment:** [Docker / Kubernetes / Cloud Run / ECS]
+- **Status:** [Development / Staging / Production]
+
+## Service Architecture
+
+```
+services/
+  api-gateway/            # Entry point, routing, auth validation
+  user-service/           # User management and authentication
+  order-service/          # Order processing and management
+  payment-service/        # Payment processing
+  notification-service/   # Email, SMS, push notifications
+  shared/
+    proto/                # Protocol Buffer definitions (if gRPC)
+    types/                # Shared TypeScript types
+    events/               # Event schema definitions
+infrastructure/
+  docker/                 # Docker Compose files
+  k8s/                    # Kubernetes manifests
+  terraform/              # Infrastructure as Code
+```
+
+## Tech Stack
+
+| Layer | Technology | Notes |
+|-------|-----------|-------|
+| Language | TypeScript / Node.js | All services |
+| Framework | Express / Fastify | HTTP handlers |
+| Communication | REST + Event-driven | Sync + async |
+| Message Broker | RabbitMQ / Kafka | Async events |
+| Database | PostgreSQL | Per-service DB |
+| Cache | Redis | Session, rate limiting |
+| Container | Docker | All services containerized |
+| Orchestration | Docker Compose / K8s | Local / Production |
+| API Docs | OpenAPI 3.0 | Per-service spec |
+
+## Service Boundaries
+
+### Ownership Rules
+- Each service owns its data (database, cache, files)
+- No direct database access between services
+- All communication via defined APIs or events
+- Each service has its own repository or workspace package
+
+### Service Template
+Every service follows this structure:
+```
+service-name/
+  src/
+    routes/               # HTTP route handlers
+    services/             # Business logic
+    repositories/         # Data access layer
+    events/
+      publishers/         # Event publishing
+      subscribers/        # Event consumption
+    middleware/            # Auth, validation, logging
+    types/                # Service-specific types
+  tests/
+    unit/                 # Unit tests
+    integration/          # Integration tests (with DB)
+  Dockerfile              # Container definition
+  openapi.yaml            # API specification
+  package.json
+  tsconfig.json
+```
+
+## API Contracts
+
+### REST Conventions
+- Base URL: `/{service-name}/api/v{version}/`
+- Use plural nouns: `/users`, `/orders`, `/payments`
+- HTTP methods: GET (read), POST (create), PUT (full update), PATCH (partial), DELETE
+- Response envelope: `{ "data": ..., "error": null, "meta": { "page": 1, "total": 100 } }`
+- Error format: `{ "error": { "code": "USER_NOT_FOUND", "message": "...", "details": [] } }`
+
+### API Versioning
+- URL-based versioning: `/api/v1/`, `/api/v2/`
+- Support N-1 versions (current + previous)
+- Deprecation headers: `Sunset: <date>`, `Deprecation: true`
+
+### OpenAPI Specification
+- Every service must have an `openapi.yaml` at the root
+- Auto-generate TypeScript types from OpenAPI spec
+- Validate requests against schema in middleware
+
+## Inter-Service Communication
+
+### Synchronous (HTTP/gRPC)
+- Used for: Real-time queries, user-facing requests
+- Circuit breaker: Required on all external calls (3 failures = open)
+- Timeout: 5 seconds default, 30 seconds for long operations
+- Retry: 3 attempts with exponential backoff (100ms, 200ms, 400ms)
+
+### Asynchronous (Events)
+- Used for: State changes, notifications, data sync
+- Event naming: `{service}.{entity}.{action}` (e.g., `order.payment.completed`)
+- Event schema: JSON Schema with version field
+- Idempotency: All event handlers must be idempotent
+- Dead letter queue: Required for all consumers
+
+### Event Schema
+```typescript
+interface DomainEvent<T> {
+  id: string;              // UUID v4
+  type: string;            // order.payment.completed
+  source: string;          // payment-service
+  version: string;         // 1.0.0
+  timestamp: string;       // ISO 8601
+  correlationId: string;   // Request trace ID
+  data: T;                 // Event-specific payload
+}
+```
+
+## Deployment Patterns
+
+### Local Development
+```bash
+docker-compose up -d       # Start all services
+docker-compose up api      # Start specific service
+docker-compose logs -f     # Follow logs
+docker-compose down        # Stop all
+```
+
+### Environment Configuration
+- `.env.local` per service for local development
+- Environment variables injected at runtime (never baked into images)
+- Required vars defined in each service's `.env.example`
+
+### Health Checks
+Every service exposes:
+- `GET /health` — Basic liveness (returns 200)
+- `GET /health/ready` — Readiness (checks DB, cache, dependencies)
+- `GET /health/detailed` — Full status with dependency health
+
+## Testing Strategy
+
+```bash
+# Per-service commands
+npm test                    # Unit tests
+npm run test:integration    # Integration (requires Docker)
+npm run test:contract       # Consumer-driven contract tests
+npm run test:e2e            # End-to-end (full system)
+```
+
+### Testing Levels
+| Level | Scope | Dependencies |
+|-------|-------|-------------|
+| Unit | Single function/class | All mocked |
+| Integration | Service + DB | Real DB, mocked services |
+| Contract | Service API shape | Pact or similar |
+| E2E | Full request flow | All services running |
+
+## Common Commands
+
+```bash
+# Development
+docker-compose up -d                    # Start infrastructure
+npm run dev --workspace=user-service    # Dev mode for one service
+
+# Testing
+npm test --workspaces                   # Test all services
+npm run test:integration --workspace=order-service
+
+# Building
+docker build -t user-service:latest ./services/user-service
+
+# Database
+npm run migrate --workspace=user-service     # Run migrations
+npm run seed --workspace=user-service        # Seed data
+```
+
+## Important Notes
+
+- Never share databases between services — each service owns its data
+- Use correlation IDs for distributed tracing across services
+- Log in structured JSON format for aggregation (ELK/Datadog)
+- Keep services small and focused — if a service grows too large, split it
+- Use feature flags for gradual rollouts across services
+- Always test backward compatibility when changing event schemas

package/squads/claude-code-mastery/templates/claude-md-mobile.md

@@ -0,0 +1,198 @@
+# CLAUDE.md — Mobile Project (React Native)
+
+## Project Overview
+
+- **Name:** [APP_NAME]
+- **Description:** [What the app does]
+- **Type:** Mobile application
+- **Framework:** React Native / Expo
+- **Platforms:** iOS + Android
+- **Status:** [Development / Beta / Production]
+
+## Tech Stack
+
+| Layer | Technology | Version |
+|-------|-----------|---------|
+| Framework | React Native | 0.76.x |
+| Tooling | Expo SDK | 52.x |
+| Language | TypeScript | 5.x |
+| Navigation | React Navigation | 7.x |
+| State (client) | Zustand | 5.x |
+| Data Fetching | TanStack Query | 5.x |
+| Styling | NativeWind / StyleSheet | — |
+| Forms | React Hook Form + Zod | — |
+| Auth | Supabase Auth | — |
+| Testing | Jest + React Native Testing Library | — |
+| E2E Testing | Detox / Maestro | — |
+
+## Directory Structure
+
+```
+src/
+  app/                    # Expo Router screens (file-based routing)
+    (tabs)/               # Tab navigator group
+    (auth)/               # Auth flow screens
+    _layout.tsx           # Root layout
+  components/
+    ui/                   # Base UI components (Button, Input, Card)
+    shared/               # Shared composite components
+    features/             # Feature-specific components
+  hooks/                  # Custom hooks
+  stores/                 # Zustand stores
+  services/               # API services and external integrations
+  lib/                    # Utility libraries
+  types/                  # TypeScript type definitions
+  constants/              # App constants (colors, spacing, config)
+  assets/                 # Images, fonts, animations
+    images/
+    fonts/
+    animations/           # Lottie files
+ios/                      # iOS native project
+android/                  # Android native project
+```
+
+## Platform-Specific Considerations
+
+### iOS
+- Minimum deployment target: iOS 15.0
+- Test on both iPhone and iPad if universal
+- Handle safe area insets with `SafeAreaView` or `useSafeAreaInsets()`
+- Request permissions gracefully (camera, location, notifications)
+- Handle keyboard avoidance for forms
+
+### Android
+- Minimum SDK: 24 (Android 7.0)
+- Handle back button behavior with navigation
+- Test on various screen densities (mdpi, hdpi, xhdpi, xxhdpi)
+- Handle Android-specific permissions in `AndroidManifest.xml`
+- Test gesture navigation vs button navigation
+
+### Platform-Specific Files
+```
+Component.tsx             # Shared (default)
+Component.ios.tsx         # iOS-only override
+Component.android.tsx     # Android-only override
+```
+
+Use `Platform.select()` for minor differences:
+```typescript
+import { Platform, StyleSheet } from 'react-native';
+
+const styles = StyleSheet.create({
+  shadow: Platform.select({
+    ios: { shadowColor: '#000', shadowOffset: { width: 0, height: 2 } },
+    android: { elevation: 4 },
+  }),
+});
+```
+
+## Navigation Patterns
+
+### Stack Navigation
+```typescript
+// Use typed navigation
+type RootStackParamList = {
+  Home: undefined;
+  Profile: { userId: string };
+  Settings: undefined;
+};
+```
+
+### Tab Navigation
+- Maximum 5 tabs
+- Use icons + labels for accessibility
+- Badge for notification counts
+
+### Deep Linking
+- Configure URL scheme: `myapp://`
+- Handle universal links (iOS) and App Links (Android)
+- Test with `npx uri-scheme open myapp://profile/123`
+
+## State Management
+
+### Local State
+- `useState` for component-scoped state
+- `useReducer` for complex component logic
+
+### Global State (Zustand)
+- Persist with `zustand/middleware` + AsyncStorage
+- Wait for hydration before rendering protected screens
+- Separate stores by domain (auth, preferences, cart)
+
+### Server State (TanStack Query)
+- Configure offline support with `onlineManager`
+- Use optimistic updates for responsive UX
+- Set `staleTime` appropriately (longer for mobile to reduce data usage)
+
+## Common Commands
+
+```bash
+# Development
+npx expo start             # Start Expo dev server
+npx expo start --ios       # Open in iOS Simulator
+npx expo start --android   # Open in Android Emulator
+npx expo start --web       # Open in web browser
+
+# Building
+eas build --platform ios                 # iOS build
+eas build --platform android             # Android build
+eas build --platform all                 # Both platforms
+
+# Testing
+npm test                   # Run Jest tests
+npm run test:e2e:ios       # E2E tests on iOS
+npm run test:e2e:android   # E2E tests on Android
+
+# Code Quality
+npm run lint               # ESLint check
+npm run typecheck          # TypeScript check
+npm run format             # Prettier formatting
+
+# Native
+npx pod-install            # Install iOS CocoaPods
+npx react-native link      # Link native modules (legacy)
+```
+
+## Build and Deploy
+
+### EAS Build
+```bash
+eas build:configure                      # Initial setup
+eas build --profile development          # Development build
+eas build --profile preview              # Internal testing
+eas build --profile production           # Store submission
+```
+
+### Over-the-Air Updates
+```bash
+eas update --branch production           # Push OTA update
+eas update --branch preview              # Preview update
+```
+
+## Testing Strategy
+
+| Level | Tool | Target |
+|-------|------|--------|
+| Unit | Jest | Hooks, utilities, stores |
+| Component | RNTL | UI components (render, interaction) |
+| Integration | Jest + RNTL | Screen-level flows |
+| E2E | Detox/Maestro | Full user journeys |
+| Visual | Storybook RN | Component catalog |
+
+### Testing Tips
+- Use `@testing-library/react-native` over Enzyme
+- Mock `react-native` modules: `Animated`, `Platform`, etc.
+- Test both platforms when using `Platform.select()`
+- Use `jest.useFakeTimers()` for animation tests
+- Mock `AsyncStorage` for store tests
+
+## Important Notes
+
+- Always test on real devices before release (simulators miss performance issues)
+- Keep bundle size small: lazy-load screens, optimize images
+- Handle offline state gracefully — queue actions for sync
+- Follow Apple HIG and Material Design guidelines
+- Never hardcode dimensions — use responsive layouts with Dimensions/useWindowDimensions
+- Test accessibility with screen readers (VoiceOver on iOS, TalkBack on Android)
+- Use `react-native-reanimated` for 60fps animations (avoid Animated API for complex cases)
+- Handle app state changes (background, foreground) for data refresh

package/squads/claude-code-mastery/templates/claude-md-monorepo.md

@@ -0,0 +1,139 @@
+# CLAUDE.md — Monorepo Project
+
+## Project Overview
+
+- **Name:** [PROJECT_NAME]
+- **Description:** [Brief description]
+- **Type:** Monorepo
+- **Manager:** [Turborepo / Nx / Lerna / pnpm workspaces]
+- **Status:** [Development / Staging / Production]
+
+## Package Structure
+
+```
+packages/
+  core/                   # Shared business logic and types
+  ui/                     # Shared UI component library
+  config/                 # Shared config (ESLint, TypeScript, Tailwind)
+  utils/                  # Shared utility functions
+apps/
+  web/                    # Main web application (Next.js)
+  api/                    # Backend API service
+  docs/                   # Documentation site
+  admin/                  # Admin dashboard
+tooling/
+  eslint-config/          # Shared ESLint configuration
+  tsconfig/               # Shared TypeScript configuration
+  jest-config/            # Shared Jest configuration
+```
+
+## Tech Stack
+
+| Layer | Technology | Notes |
+|-------|-----------|-------|
+| Build | Turborepo | Task orchestration and caching |
+| Package Manager | pnpm | Workspace support, strict hoisting |
+| Language | TypeScript | Shared tsconfig in tooling/ |
+| Linting | ESLint | Shared config across packages |
+| Testing | Jest | Shared config, per-package execution |
+
+## Shared Dependencies
+
+### Internal Packages (workspace:*)
+- `@[scope]/core` — Business logic, types, constants
+- `@[scope]/ui` — React components, design tokens
+- `@[scope]/utils` — Utility functions (date, string, validation)
+- `@[scope]/config` — Shared configuration files
+
+### Dependency Rules
+- **Root dependencies:** Only dev tools (turbo, prettier, husky)
+- **Shared deps:** Declared in the package that owns them
+- **Version alignment:** Use `syncpack` or `manypkg` to keep versions consistent
+- **Peer dependencies:** UI components declare React as peer dep
+- Never install the same dependency at different versions across packages
+
+## Per-Package Conventions
+
+### apps/web (Next.js)
+```bash
+pnpm --filter web dev        # Dev server
+pnpm --filter web build      # Production build
+pnpm --filter web test       # Tests
+```
+- Imports from `@[scope]/ui` and `@[scope]/core`
+- Uses App Router, follows fullstack patterns
+
+### apps/api (Express/Fastify)
+```bash
+pnpm --filter api dev        # Dev server
+pnpm --filter api build      # Compile TypeScript
+pnpm --filter api test       # Tests
+```
+- Imports from `@[scope]/core` for shared types
+- Never imports from `@[scope]/ui`
+
+### packages/ui (Component Library)
+```bash
+pnpm --filter ui dev         # Storybook
+pnpm --filter ui build       # Build for consumption
+pnpm --filter ui test        # Component tests
+```
+- Exports via package.json `exports` field
+- Uses `tsup` or `unbuild` for compilation
+
+### packages/core (Business Logic)
+```bash
+pnpm --filter core build     # Compile
+pnpm --filter core test      # Unit tests
+```
+- Pure TypeScript, no framework dependencies
+- Exports types, validators, constants
+
+## Cross-Package Imports
+
+```typescript
+// Correct: use workspace package name
+import { Button } from '@[scope]/ui';
+import { formatDate } from '@[scope]/utils';
+import type { User } from '@[scope]/core';
+
+// Wrong: never use relative paths across packages
+import { Button } from '../../packages/ui/src/Button';
+```
+
+## Build and Test Commands
+
+```bash
+# Root commands (run across all packages)
+pnpm build                   # Build all packages (respects dependency order)
+pnpm test                    # Test all packages
+pnpm lint                    # Lint all packages
+pnpm typecheck               # Type-check all packages
+pnpm dev                     # Dev mode for all apps
+
+# Single package
+pnpm --filter [package] [command]
+
+# With dependencies
+pnpm --filter [package]... build   # Build package and its deps
+
+# Turbo-specific
+turbo run build --filter=web       # Build web and dependencies
+turbo run test --affected          # Test only affected packages
+```
+
+## Naming Conventions
+
+- Package names: `@[scope]/package-name` (kebab-case)
+- Internal imports: Always use the package name, never relative paths
+- Shared types: Define in `@[scope]/core/types/`
+- Shared hooks: Define in `@[scope]/ui/hooks/` if UI-related, `@[scope]/core/hooks/` otherwise
+
+## Important Notes
+
+- Always run `pnpm install` from the root (never inside a package)
+- Changes to shared packages may affect multiple apps — test broadly
+- Turbo caches builds; run `turbo run build --force` to bypass cache
+- When adding a new package, update `pnpm-workspace.yaml`
+- CI should use `turbo run test --affected` for faster builds
+- Never put secrets in shared packages; keep them in app-level `.env`