contextos-agents 1.5.0

package/.agents/generated/gemini/skills/microservices/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: Microservices
+description: >
+  ContextOS skill for Microservices
+---
+# Microservices
+
+## Overview
+
+Distributed systems architecture standard. Enforces bounded context isolation, asynchronous event-driven messaging (Kafka, RabbitMQ), Saga distributed transactions, API gateways, and outbox patterns.
+
+## When to Use
+
+Activate when decomposing monoliths into independent services, designing inter-service communications, or building scalable distributed systems.
+
+## Rules & Patterns
+<!-- Source: microservices.md -->
+
+## Microservices — Architecture Guide
+
+## When to Use Microservices
+
+**Use when:**
+
+- Team > 10 engineers working on the same product
+- Independent deployment of components is critical
+- Different components have different scaling needs
+- Different components need different tech stacks
+
+**Don't use when:**
+
+- Small team (< 5 engineers)
+- MVP or prototype
+- No operational expertise (monitoring, tracing, deployment)
+- Tight coupling between components
+
+## Core Principles
+
+### 1. Single Responsibility
+
+Each service does ONE thing well.
+
+### 2. Own Your Data
+
+Each service has its own database. No shared databases.
+
+### 3. API Contracts
+
+Services communicate through well-defined APIs. Internal implementation is hidden.
+
+### 4. Autonomous Deployment
+
+Each service can be deployed independently.
+
+## Communication Patterns
+
+### Synchronous (REST/gRPC)
+
+- **When**: Request needs immediate response
+- **Tools**: REST (HTTP), gRPC (high-performance)
+- **Risk**: Cascading failures, latency accumulation
+
+### Asynchronous (Events/Messages)
+
+- **When**: Eventual consistency is acceptable
+- **Tools**: Kafka, RabbitMQ, Redis Streams, AWS SQS
+- **Benefit**: Loose coupling, resilience
+
+### Saga Pattern (Distributed Transactions)
+
+```
+Order Service → Payment Service → Inventory Service → Shipping Service
+      ↓ (failure)
+Compensating transactions reverse each step
+```
+
+1. **Choreography (Event-Driven)**: Each service emits events, downstream services listen and react. Best for simple flows (≤ 3 steps) where a central coordinator adds unnecessary coupling.
+2. **Orchestration (State Machine)**: A dedicated Saga Orchestrator controls the flow and explicitly triggers compensating transactions on failure (e.g., `RefundPayment`, `ReleaseInventoryReservation`). Mandatory for complex multi-step workflows.
+
+### Dead Letter Queues (DLQ) & Poison Pill Handling
+
+- **Never retry infinitely**: Set max retries (e.g. 3) with exponential backoff and jitter.
+- After max retries, route failed messages to a **Dead Letter Queue (DLQ)** with error metadata.
+- Provide alerting on DLQ depth and an admin CLI/script to replay DLQ messages.
+
+## CQRS (Command Query Responsibility Segregation)
+
+Separate read and write models:
+
+```
+Command (Write) → Write Model → Event Store → Projections → Read Model → Query (Read)
+```
+
+**When**: Read patterns differ significantly from write patterns.
+
+## Event Sourcing
+
+Store events, not state:
+
+```
+UserCreated → EmailUpdated → RoleChanged → PasswordReset
+```
+
+Current state = replay all events. Full audit trail.
+
+## Service Boundaries
+
+### Bounded Contexts (from DDD)
+
+- Identify domain boundaries
+- Each service maps to a bounded context
+- Shared language within the context, translation at boundaries
+
+### Anti-Corruption Layer
+
+When integrating with legacy or external systems, create an adapter that translates between models.
+
+## Operational Concerns
+
+### Observability (The Three Pillars)
+
+1. **Logs** — structured JSON, correlated by request ID
+2. **Metrics** — latency, error rate, throughput (RED)
+3. **Traces** — distributed tracing across services (Jaeger, Zipkin)
+
+### Resilience
+
+- **Circuit Breaker** — stop calling failing services
+- **Retry with Backoff** — exponential backoff + jitter
+- **Timeout** — every call has a timeout
+- **Bulkhead** — isolate failures
+
+### Deployment
+
+- **Containers** — Docker for consistency
+- **Orchestration** — Kubernetes for production
+- **CI/CD** — independent pipelines per service
+- **Blue-Green / Canary** — safe rollouts
+
+## Anti-Patterns
+
+- [FAIL] Distributed monolith — services that can't deploy independently
+- [FAIL] Shared database — defeats the purpose
+- [FAIL] Synchronous chains — A calls B calls C calls D
+- [FAIL] No versioning — breaking API changes
+- [FAIL] Premature microservices — start with a modular monolith
+
+
+## Code Examples
+
+See `EXAMPLES.md` for detailed code examples.
+
+## Validation Checklist
+
+What to verify during the review phase before completing the task.
+
+## Common Mistakes
+
+Anti-patterns and things to explicitly avoid. See `TROUBLESHOOTING.md`.
+
+## Integration Notes
+
+How this skill interacts with other skills.
+
+
+<!-- Source: EXAMPLES.md -->
+
+# microservices Examples — Anti-patterns vs ContextOS Standard
+
+## Example 1: Inter-service Communication
+
+### Anti-pattern: Synchronous HTTP Call Chains (The Distributed Monolith)
+
+```text
+User -> OrderService (HTTP) -> InventoryService (HTTP) -> PaymentService (HTTP) -> EmailService (HTTP)
+Problem: High latency, 99.9% availability compounding to 96% overall availability, cascading failure.
+```
+
+### Best practice: ContextOS Standard (Asynchronous Event Choreography)
+
+```text
+User -> OrderService (creates order with status 'PENDING')
+OrderService publishes 'OrderPlaced' event to Event Broker (Kafka/RabbitMQ)
+  ├── InventoryService consumes 'OrderPlaced' -> Reserves stock
+  ├── PaymentService consumes 'OrderPlaced' -> Charges customer
+  └── NotificationService consumes 'PaymentProcessed' -> Sends confirmation email
+```
+
+---
+
+## Example 2: Database Architecture
+
+### Anti-pattern: Shared Database Across Multiple Microservices
+
+```text
+BAD: OrderService and UserService both directly read and write to the same 'users' table.
+Schema migrations in UserService immediately break OrderService.
+```
+
+### Best practice: ContextOS Standard (Database-per-Service)
+
+```text
+GOOD: UserService owns user data. OrderService maintains a local read-model (denormalized user info)
+synchronized via 'UserUpdated' events. Each service can migrate and scale independently.
+```
+
+<!-- Source: TROUBLESHOOTING.md -->
+
+# microservices Troubleshooting & Common Mistakes
+
+## 1. Missing Consumer Idempotency
+
+- **Symptom**: Users charged twice or duplicate records created when events are re-delivered.
+- **Root Cause**: Message brokers guarantee at-least-once delivery; network retries re-send events.
+- **Fix**: Store processed message/event IDs in a deduplication table with unique constraint.
+
+## 2. Circular Service Dependencies
+
+- **Symptom**: Service A cannot boot or operate without Service B, and Service B depends on Service A.
+- **Root Cause**: Improper domain boundaries and coupled synchronous dependencies.
+- **Fix**: Invert dependency using domain events or introduce a composite BFF/Orchestrator.
+
+## 3. Distributed Tracing Blindness
+
+- **Symptom**: Impossible to diagnose which downstream microservice caused a 500 error or latency spike.
+- **Root Cause**: HTTP headers and event messages do not propagate correlation IDs.
+- **Fix**: Propagate X-Correlation-ID / traceparent across all HTTP requests and event headers.

package/.agents/generated/gemini/skills/minimalist-design/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: minimalist-design
+description: >
+  Clean editorial-style interfaces with warm monochrome palettes and flat bento grids.
+---
+# Protocol: Premium Utilitarian Minimalism UI Architect
+
+## Overview
+
+An advanced frontend engineering directive for generating highly refined, ultra-minimalist, "document-style" web interfaces analogous to top-tier workspace platforms. This protocol strictly enforces a high-contrast warm monochrome palette, bespoke typographic hierarchies, meticulous structural macro-whitespace, bento-grid layouts, and an ultra-flat component architecture with deliberate muted pastel accents. It actively rejects standard generic SaaS design trends.
+
+## When to Use
+
+- When designing clean, editorial, or Notion-like document interfaces, workspaces, or notes apps.
+- When creating minimalist SaaS dashboards, personal essays, portfolios, or agency landing pages.
+- When asked for a "clean", "minimalist", "warm monochrome", or "flat bento-box" layout.
+
+## Rules & Patterns
+
+### 1. Absolute Negative Constraints (Banned Elements)
+
+The AI must strictly avoid the following generic web development defaults:
+
+- DO NOT use the "Inter", "Roboto", or "Open Sans" typefaces.
+- DO NOT use generic, thin-line icon libraries like "Lucide", "Feather", or standard "Heroicons".
+- DO NOT use Tailwind's default heavy drop shadows (e.g., `shadow-md`, `shadow-lg`, `shadow-xl`). Shadows must be practically non-existent or heavily customized to be ultra-diffuse and low opacity (< 0.05).
+- DO NOT use primary colored backgrounds for large elements or sections (e.g., no bright blue, green, or red hero sections).
+- DO NOT use gradients, neon colors, or 3D glassmorphism (beyond subtle navbar blurs).
+- DO NOT use `rounded-full` (pill shapes) for large containers, cards, or primary buttons.
+- DO NOT use emojis anywhere in code, markup, text content, headings, or alt text. Replace with proper icons or clean SVG primitives.
+- DO NOT use generic placeholder names like "John Doe", "Acme Corp", or "Lorem Ipsum". Use realistic, contextual content.
+- DO NOT use AI copywriting clichés: "Elevate", "Seamless", "Unleash", "Next-Gen", "Game-changer", "Delve". Write plain, specific language.
+
+### 2. Typographic Architecture
+
+The interface must rely on extreme typographic contrast and premium font selection to establish an editorial feel.
+
+- **Primary Sans-Serif (Body, UI, Buttons):** Use clean, geometric, or system-native fonts with character (`'SF Pro Display', 'Geist Sans', 'Helvetica Neue', 'Switzer', sans-serif`).
+- **Editorial Serif (Hero Headings & Quotes):** (`'Lyon Text', 'Newsreader', 'Playfair Display', 'Instrument Serif', serif`). Apply tight tracking (`-0.02em` to `-0.04em`) and tight line-height (`1.1`).
+- **Monospace (Code, Keystrokes, Meta-data):** (`'Geist Mono', 'SF Mono', 'JetBrains Mono', monospace`).
+- **Text Colors:** Body text must never be absolute black (`#000000`). Use off-black/charcoal (`#111111` or `#2F3437`) with a generous line-height of `1.6` for legibility. Secondary text should be muted gray (`#787774`).
+
+### 3. Color Palette (Warm Monochrome + Spot Pastels)
+
+Color is a scarce resource, utilized only for semantic meaning or subtle accents.
+
+- **Canvas / Background:** Pure White `#FFFFFF` or Warm Bone/Off-White `#F7F6F3` / `#FBFBFA`.
+- **Primary Surface (Cards):** `#FFFFFF` or `#F9F9F8`.
+- **Structural Borders / Dividers:** Ultra-light gray `#EAEAEA` or `rgba(0,0,0,0.06)`.
+- **Accent Colors:** Exclusively use highly desaturated, washed-out pastels for tags, inline code backgrounds, or subtle icon backgrounds:
+  - Pale Red: `#FDEBEC` (Text: `#9F2F2D`)
+  - Pale Blue: `#E1F3FE` (Text: `#1F6C9F`)
+  - Pale Green: `#EDF3EC` (Text: `#346538`)
+  - Pale Yellow: `#FBF3DB` (Text: `#956400`)
+
+### 4. Component Specifications
+
+- **Bento Box Feature Grids:** Asymmetrical CSS Grid layouts. Cards have `border: 1px solid #EAEAEA`, crisp border-radius (`8px` to `12px` max), and generous internal padding (`24px` to `40px`).
+- **Primary Call-To-Action (Buttons):** Solid `#111111`, text `#FFFFFF`, radius `4px` to `6px`, no box-shadow. Micro-scale `transform: scale(0.98)` on active.
+- **Tags & Status Badges:** Pill-shaped (`rounded-full`), small typography (`text-xs`), uppercase with wide tracking (`0.05em`), pastel background.
+- **Accordions (FAQ):** Separated by `border-bottom: 1px solid #EAEAEA` without card boxes. Crisp `+` / `-` toggle icons.
+- **Keystroke Micro-UIs:** `<kbd className="border border-[#EAEAEA] rounded bg-[#F7F6F3] font-mono px-1.5 py-0.5 text-xs">`.
+
+### 5. Iconography & Imagery
+
+- **System Icons:** Phosphor Icons (Bold/Fill) or Radix UI Icons for crisp, technical strokes.
+- **Photography:** Desaturated images with warm tint and subtle grain overlay (`opacity: 0.04`).
+- **Depth:** Subtle ambient gradients (`radial-gradient` with warm tones at `opacity: 0.03`) or minimal geometric line patterns.
+
+### 6. Subtle Motion & Micro-Animations
+
+- **Scroll Entry:** Fade-in + `translateY(12px)` over 600ms via `IntersectionObserver`.
+- **Hover States:** Subtle card lift with ultra-diffuse shadow (`0 2px 8px rgba(0,0,0,0.04)`).
+- **Staggered Reveals:** Cascading delay (`calc(var(--index) * 80ms)`).
+
+## Code Examples
+
+```tsx
+export function BentoFeatureCard({ title, description, badge, tagColor = "blue" }: { title: string; description: string; badge: string; tagColor?: string }) {
+  return (
+    <div className="bg-[#FFFFFF] border border-[#EAEAEA] rounded-xl p-8 hover:shadow-[0_2px_8px_rgba(0,0,0,0.04)] transition-all duration-200">
+      <div className="flex items-center justify-between mb-4">
+        <span className="text-xs uppercase tracking-wider font-mono font-medium px-2.5 py-0.5 rounded-full bg-[#E1F3FE] text-[#1F6C9F]">
+          {badge}
+        </span>
+      </div>
+      <h3 className="font-serif text-2xl tracking-tight text-[#111111] mb-2">{title}</h3>
+      <p className="text-sm text-[#787774] leading-relaxed">{description}</p>
+    </div>
+  );
+}
+```
+
+## Validation Checklist
+
+- [ ] Macro-whitespace established with generous vertical section padding (`py-24` to `py-32`).
+- [ ] No pure black (`#000000`) for text or backgrounds.
+- [ ] Borders use crisp `1px solid #EAEAEA` or `rgba(0,0,0,0.06)`.
+- [ ] No generic AI buzzwords or emojis used in copy.
+- [ ] Typography uses editorial serif headers paired with clean sans-serif body.
+- [ ] Card corners constrained to crisp 8px-12px radius; no pill containers.
+
+## Common Mistakes
+
+- Using heavy saturated primary colors for hero backgrounds.
+- Adding default Tailwind drop-shadows (`shadow-lg`).
+- Cluttering interfaces with emojis instead of clean SVG icons.
+- Using default Inter or Roboto fonts without editorial contrast.
+
+## Integration Notes
+
+- Complements `ui-ux-pro` for color tokens and accessibility.
+- Integrates with `impeccable-design` for QA and anti-pattern enforcement.
+

package/.agents/generated/gemini/skills/nestjs/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: NestJS
+description: >
+  ContextOS skill for NestJS
+---
+# NestJS
+
+## Overview
+
+Enterprise Node.js architecture standard using NestJS, TypeScript, and RxJS. Enforces strict modularity, dependency injection, repository pattern, DTO validation via class-validator, and clean layered architecture.
+
+## When to Use
+
+Activate when building enterprise Node.js microservices, complex REST/GraphQL APIs, or scalable backends requiring strict architectural structure.
+
+## Rules & Patterns
+<!-- Source: nestjs.md -->
+
+## NestJS — Best Practices
+
+## Module Architecture
+
+- **One module per domain** — `UsersModule`, `AuthModule`, `OrdersModule`
+- **Feature modules** — encapsulate related controllers, services, repositories
+- **Shared module** — for cross-cutting concerns (logging, config, utils)
+- **Core module** — singleton services (database, auth guards)
+
+```
+src/
+├── modules/
+│   ├── users/
+│   │   ├── users.module.ts
+│   │   ├── users.controller.ts
+│   │   ├── users.service.ts
+│   │   ├── users.repository.ts
+│   │   ├── dto/
+│   │   │   ├── create-user.dto.ts
+│   │   │   └── update-user.dto.ts
+│   │   ├── entities/
+│   │   │   └── user.entity.ts
+│   │   └── users.spec.ts
+│   └── auth/
+├── shared/
+│   ├── guards/
+│   ├── interceptors/
+│   ├── pipes/
+│   └── filters/
+├── config/
+└── app.module.ts
+```
+
+## Dependency Injection
+
+```typescript
+@Injectable()
+export class UsersService {
+  constructor(
+    @InjectRepository(User) private readonly usersRepo: Repository<User>,
+    private readonly configService: ConfigService,
+  ) {}
+}
+```
+
+- Prefer constructor injection
+- Use custom providers for complex setup
+- Scope: default is Singleton, use REQUEST scope only when needed
+
+## DTOs and Validation
+
+```typescript
+import { IsEmail, IsString, MinLength } from 'class-validator';
+
+export class CreateUserDto {
+  @IsEmail()
+  email: string;
+
+  @IsString()
+  @MinLength(2)
+  name: string;
+}
+```
+
+- Always use DTOs for request validation
+- Use `ValidationPipe` globally
+- Separate Create/Update/Response DTOs
+
+## Guards, Interceptors, Pipes
+
+| Type | Purpose |
+| --- | --- |
+| **Guards** | Authentication, authorization |
+| **Interceptors** | Logging, transformation, caching |
+| **Pipes** | Validation, transformation |
+| **Filters** | Exception handling |
+
+Execution order: Guards → Interceptors → Pipes → Handler → Interceptors → Filters
+
+## Error Handling
+
+```typescript
+@Catch()
+export class AllExceptionsFilter implements ExceptionFilter {
+  catch(exception: unknown, host: ArgumentsHost) {
+    // Transform to standard error format
+  }
+}
+```
+
+## Testing
+
+- **Unit tests** — mock dependencies with `Test.createTestingModule()`
+- **E2E tests** — use `supertest` with a test module
+- **Mock everything** — services should be testable in isolation
+
+## Anti-Patterns
+
+- [FAIL] Business logic in controllers — use services
+- [FAIL] Direct database access in controllers — use repositories
+- [FAIL] Circular dependencies — refactor module structure
+- [FAIL] God modules — split large modules by domain
+- [FAIL] Not using DTOs — always validate input
+
+
+## Code Examples
+
+See `EXAMPLES.md` for detailed code examples.
+
+## Validation Checklist
+
+What to verify during the review phase before completing the task.
+
+## Common Mistakes
+
+Anti-patterns and things to explicitly avoid. See `TROUBLESHOOTING.md`.
+
+## Integration Notes
+
+How this skill interacts with other skills.
+
+
+<!-- Source: EXAMPLES.md -->
+
+# nestjs Examples — Anti-patterns vs ContextOS Standard
+
+## Example 1: Input Validation and DTOs
+
+### Anti-pattern: Untyped Body or Manual Validation in Controller
+
+```typescript
+// BAD: No runtime validation, controller stuffed with business rules
+@Post('users')
+async create(@Body() body: any) {
+  if (!body.email || !body.email.includes('@')) {
+    throw new BadRequestException('Invalid email');
+  }
+  return this.usersService.create(body);
+}
+```
+
+### Best practice: ContextOS Standard (Class-Validator DTO + ValidationPipe)
+
+```typescript
+// GOOD: Declarative runtime validation with clean separation
+export class CreateUserDto {
+  @IsEmail({}, { message: 'A valid email is required' })
+  email: string;
+
+  @IsString()
+  @MinLength(8, { message: 'Password must be at least 8 characters long' })
+  password: string;
+}
+
+@Controller('users')
+export class UsersController {
+  constructor(private readonly usersService: UsersService) {}
+
+  @Post()
+  async create(@Body() dto: CreateUserDto) {
+    return this.usersService.create(dto);
+  }
+}
+```
+
+<!-- Source: TROUBLESHOOTING.md -->
+
+# nestjs Troubleshooting & Common Mistakes
+
+## 1. Circular Dependency Between Modules
+
+- **Symptom**: "Nest cannot create the module instance. Often, this is caused by circular dependencies".
+- **Root Cause**: Module A imports Module B, and Module B imports Module A.
+- **Fix**: Use `forwardRef(() => ModuleB)` in imports and `@Inject(forwardRef(() => ServiceB))` in constructors, or refactor shared logic into a separate CommonModule.
+
+## 2. Memory Leaks from REQUEST Scope
+
+- **Symptom**: High memory usage and slow performance under load.
+- **Root Cause**: Providers declared with Scope.REQUEST recreate instances on every HTTP request.
+- **Fix**: Keep services as default Singletons whenever possible. Pass request-scoped parameters directly through method arguments.
+
+## 3. Uncaught Domain Exceptions
+
+- **Symptom**: Custom domain exceptions bypass formatting and return generic 500 errors.
+- **Root Cause**: Missing custom Global Exception Filter.
+- **Fix**: Implement an AllExceptionsFilter implementing ExceptionFilter and bind it globally in main.ts.