code-ai-installer 3.0.0 → 4.0.0

package/domains/development/locales/en/.agents/skills/design-patterns-architectural-reference/SKILL.md

@@ -0,0 +1,332 @@
+---
+name: design-patterns-architectural-reference
+description: Canonical reference of architectural and microservice patterns — Repository / Service Layer / Dependency Injection / Event-Driven / CQRS / Saga / Circuit Breaker / Mediator. DO/DON'T pseudocode, 'when to apply' notes. Activate when selecting a service/component-level pattern.
+type: reference
+domain: development
+owners:
+  - architect
+gates:
+  - ARCH
+tech: []
+topic:
+  - architecture
+triggers:
+  - architectural pattern
+  - microservice pattern
+  - Repository pattern
+  - Service Layer
+  - Dependency Injection
+  - Event-Driven
+  - CQRS
+  - Saga
+  - Circuit Breaker
+  - Mediator
+related:
+  - design-patterns-reference
+  - design-patterns-solid-reference
+  - design-patterns-gof-reference
+  - adr-log
+  - architecture-doc
+  - api-contracts
+budget_lines: 500
+schema_version: 1
+---
+
+
+# Skill: Design Patterns — Architectural + Microservices Reference
+
+Growing canonical library of architectural and microservice patterns with DO/DON'T pseudocode. Service / component-scale.
+
+**Sections:**
+1. [Repository](#1-repository)
+2. [Service Layer](#2-service-layer)
+3. [Dependency Injection (DI)](#3-di)
+4. [Event-Driven](#4-event-driven)
+5. [CQRS](#5-cqrs)
+6. [Saga](#6-saga)
+7. [Circuit Breaker](#7-circuit-breaker)
+8. [Mediator](#8-mediator)
+9. [Growing library](#9-growing-library)
+
+> Selection rule + taxonomy → `$design-patterns-reference` (meta-index).
+> SOLID + cross-cutting principles → `$design-patterns-solid-reference`.
+> GoF patterns → `$design-patterns-gof-reference`.
+
+---
+
+## 1. Repository — storage access isolation
+```
+// ✅ DO: repository encapsulates storage operations
+interface UserRepository
+  findById(id) → User | null
+  findByEmail(email) → User | null
+  save(user) → User
+  delete(id) → void
+
+class PostgresUserRepository implements UserRepository
+  findById(id) → db.query("SELECT ... WHERE id = $1", [id])
+
+class MongoUserRepository implements UserRepository
+  findById(id) → collection.findOne({ _id: id })
+
+// Business logic doesn't know about SQL/Mongo
+class UserService
+  constructor(repo: UserRepository)
+  getUser(id) → this.repo.findById(id)
+```
+
+```
+// ❌ DON'T: SQL in business logic
+class UserService
+  getUser(id)
+    result = db.query("SELECT * FROM users WHERE id = $1", [id])
+    // Tied to PostgreSQL, can't test without DB
+```
+
+**When:** isolating business logic from storage details; ability to swap DBs; testability.
+
+---
+
+## 2. Service Layer — business logic out of controllers
+```
+// ✅ DO: controller → service → repository
+class OrderController
+  constructor(orderService)
+  handleCreateOrder(req)
+    order = this.orderService.create(req.body)
+    return Response(201, order)
+
+class OrderService
+  constructor(orderRepo, paymentGateway, inventory)
+  create(data)
+    this.inventory.reserve(data.items)
+    order = Order.create(data)
+    this.paymentGateway.charge(order.total)
+    this.orderRepo.save(order)
+    return order
+
+// ❌ DON'T: business logic in controller
+class OrderController
+  handleCreateOrder(req)
+    db.query("INSERT INTO orders ...")    // SQL in controller
+    stripe.charge(...)                     // payment in controller
+    sendEmail(...)                         // email too
+```
+
+**When:** REST API with non-trivial business logic; controller should only map HTTP into domain.
+
+---
+
+## 3. Dependency Injection (DI)
+```
+// ✅ DO: dependencies passed from outside
+class Application
+  start()
+    db = new PostgresConnection(config.db)
+    userRepo = new PostgresUserRepository(db)
+    emailService = new SmtpEmailService(config.smtp)
+    userService = new UserService(userRepo, emailService)
+    controller = new UserController(userService)
+    server.register(controller)
+
+// Each component accepts dependencies via constructor
+// Easy to test: substitute mock repository
+```
+
+```
+// ❌ DON'T: components create their own dependencies
+class UserService
+  repo = new PostgresUserRepository(new PostgresConnection("hardcoded"))
+  email = new SmtpEmailService("smtp://hardcoded")
+  // Can't test without real PostgreSQL and SMTP
+```
+
+**When:** loose coupling between components; testability; ability to swap implementations.
+
+---
+
+## 4. Event-Driven — reaction to events
+```
+// ✅ DO: loose coupling via events
+// Service creates order and publishes event
+class OrderService
+  createOrder(data)
+    order = Order.create(data)
+    orderRepo.save(order)
+    eventBus.publish("order.created", { orderId: order.id })
+
+// Independent handlers subscribe to the event
+class InventoryHandler
+  on("order.created") → reserveItems(event.orderId)
+
+class NotificationHandler
+  on("order.created") → sendConfirmation(event.orderId)
+
+class AnalyticsHandler
+  on("order.created") → trackConversion(event.orderId)
+
+// Adding a new handler → no line in OrderService changes
+```
+
+```
+// ❌ DON'T: OrderService knows about all dependent components
+class OrderService
+  createOrder(data)
+    order = Order.create(data)
+    orderRepo.save(order)
+    inventoryService.reserve(order)      // hard coupling
+    notificationService.send(order)       // hard coupling
+    analyticsService.track(order)         // hard coupling
+```
+
+**When:** reacting to business events without tight coupling; adding new handlers shouldn't break the producer.
+
+---
+
+## 5. CQRS — Command Query Responsibility Segregation
+```
+// ✅ DO: different models for write and read
+// Command side — normalized model; business rules
+class CreateOrderCommand
+  execute(data)
+    order = Order.create(data)
+    orderRepo.save(order)
+    eventBus.publish("order.created", order)
+
+// Query side — denormalized model; optimized for reads
+class OrderQueryService
+  getOrderSummary(id) →
+    readDb.query("SELECT ... FROM order_summaries WHERE id = $1", [id])
+
+  getOrdersByUser(userId, page) →
+    readDb.query("SELECT ... FROM user_orders_view WHERE user_id = $1 LIMIT ...", [userId])
+
+// Writes update read-model via events
+on("order.created") → updateOrderSummaryView(event)
+```
+
+**When:** read and write patterns differ greatly; high read load; denormalization needed for fast queries.
+
+---
+
+## 6. Saga — distributed transactions via compensations
+```
+// ✅ DO: each step has a compensation (rollback)
+class OrderSaga
+  steps = [
+    { action: reserveInventory,    compensate: releaseInventory },
+    { action: chargePayment,       compensate: refundPayment },
+    { action: createShipment,      compensate: cancelShipment },
+    { action: sendConfirmation,    compensate: sendCancellation },
+  ]
+
+  execute(orderData)
+    completed = []
+    for step in steps
+      try
+        step.action(orderData)
+        completed.push(step)
+      catch error
+        // Roll back all completed steps in reverse order
+        for s in completed.reverse()
+          s.compensate(orderData)
+        throw SagaFailedError(error)
+```
+
+**When:** transaction spans multiple services; distributed 2PC isn't available.
+
+---
+
+## 7. Circuit Breaker — cascade failure protection
+```
+// ✅ DO: Circuit Breaker in front of external service calls
+class CircuitBreaker
+  state = CLOSED        // normal operation
+  failureCount = 0
+  threshold = 5
+  resetTimeout = 30s
+
+  call(fn)
+    if state == OPEN
+      if elapsed > resetTimeout → state = HALF_OPEN
+      else → throw ServiceUnavailableError   // don't send request
+
+    try
+      result = fn()
+      if state == HALF_OPEN → state = CLOSED; failureCount = 0
+      return result
+    catch error
+      failureCount++
+      if failureCount >= threshold → state = OPEN; startTimer()
+      throw error
+
+// Usage
+breaker = new CircuitBreaker()
+userData = breaker.call(() => externalUserApi.getUser(id))
+```
+
+**When:** dependency on an external service that may fail; prevention of cascade failure.
+
+---
+
+## 8. Mediator — central coordinator for interactions
+```
+// ✅ DO: components communicate via the mediator, not directly
+class OrderMediator
+  handlers = Map<string, Handler>
+
+  register(commandType, handler)
+  send(command)
+    handler = this.handlers.get(command.type)
+    return handler.handle(command)
+
+// Registration
+mediator.register("CreateOrder", new CreateOrderHandler(orderRepo, inventory))
+mediator.register("CancelOrder", new CancelOrderHandler(orderRepo, payment))
+
+// Invocation — controller doesn't know about concrete handlers
+class OrderController
+  handleCreate(req) → mediator.send(new CreateOrderCommand(req.body))
+  handleCancel(req) → mediator.send(new CancelOrderCommand(req.params.id))
+```
+
+**When:** many interacting components; need to centralize coordination and remove direct dependencies.
+
+---
+
+## 9. Growing library
+
+This file is a **canonical library that grows**. The architect adds new architectural and microservice patterns via `update_skill` / `create_skill`:
+
+**Architectural:**
+- Hexagonal Architecture (Ports & Adapters)
+- Onion Architecture
+- Clean Architecture
+- Layered Architecture variants
+- Domain-Driven Design (DDD) building blocks
+- Event Sourcing pattern
+- Specification pattern
+- Unit of Work pattern
+
+**Microservices:**
+- API Gateway pattern
+- Service Mesh (Istio / Linkerd)
+- Bulkhead (resource isolation)
+- Strangler Fig (legacy migration)
+- Sidecar pattern
+- Saga Orchestrator vs Choreography
+- Outbox pattern
+- Backend-For-Frontend (BFF)
+- Service Registry / Discovery
+
+Each new pattern — DO/DON'T pseudocode + "when to apply" + relation to existing.
+
+---
+
+## See also
+- `$design-patterns-reference` — meta-index with selection rule
+- `$design-patterns-solid-reference` — SOLID + cross-cutting principles
+- `$design-patterns-gof-reference` — GoF class-scale patterns
+- `$adr-log` — recording selected pattern in ADRs
+- `$architecture-doc` — Architecture Document
+- `$api-contracts` — API design (Service Layer often appears at the API level)

package/domains/development/locales/en/.agents/skills/design-patterns-architectural-reference/agents/claude.json

@@ -0,0 +1,19 @@
+{
+  "name": "design-patterns-architectural-reference",
+  "display_name": "Design Patterns — Architectural + Microservices Reference",
+  "description": "Canonical reference of architectural and microservice patterns — Repository / Service Layer / Dependency Injection / Event-Driven / CQRS / Saga / Circuit Breaker / Mediator. DO/DON'T pseudocode, 'when to apply' notes. Activate when selecting a service/component-level pattern."which pattern to apply\".",
+  "default_prompt": "Use $design-patterns-architectural-reference when the task matches the \"Design Patterns — Architectural + Microservices Reference\" skill.",
+  "triggers": [
+    "design-patterns-architectural-reference",
+    "design patterns architectural reference",
+    "Design patterns reference with DO/DON'T examples — SOLID, DRY/KISS/YAGNI, GoF (Strategy, Observer, Factory, Adapter, Facade, Decorator, Command, State, Template Method), architectural (Repository, Service Layer, DI, Event-Driven, CQRS), microservices (Saga, Circuit Breaker)"
+  ],
+  "capabilities": [
+    "design",
+    "architectural",
+    "microservices",
+    "reference"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/development/locales/en/.agents/skills/design-patterns-architectural-reference/agents/copilot.json

@@ -0,0 +1,19 @@
+{
+  "name": "design-patterns-architectural-reference",
+  "display_name": "Design Patterns — Architectural + Microservices Reference",
+  "description": "Canonical reference of architectural and microservice patterns — Repository / Service Layer / Dependency Injection / Event-Driven / CQRS / Saga / Circuit Breaker / Mediator. DO/DON'T pseudocode, 'when to apply' notes. Activate when selecting a service/component-level pattern."which pattern to apply\".",
+  "default_prompt": "Use $design-patterns-architectural-reference when the task matches the \"Design Patterns — Architectural + Microservices Reference\" skill.",
+  "triggers": [
+    "design-patterns-architectural-reference",
+    "design patterns architectural reference",
+    "Design patterns reference with DO/DON'T examples — SOLID, DRY/KISS/YAGNI, GoF (Strategy, Observer, Factory, Adapter, Facade, Decorator, Command, State, Template Method), architectural (Repository, Service Layer, DI, Event-Driven, CQRS), microservices (Saga, Circuit Breaker)"
+  ],
+  "capabilities": [
+    "design",
+    "architectural",
+    "microservices",
+    "reference"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/development/locales/en/.agents/skills/design-patterns-architectural-reference/agents/gemini.json

@@ -0,0 +1,19 @@
+{
+  "name": "design-patterns-architectural-reference",
+  "display_name": "Design Patterns — Architectural + Microservices Reference",
+  "description": "Canonical reference of architectural and microservice patterns — Repository / Service Layer / Dependency Injection / Event-Driven / CQRS / Saga / Circuit Breaker / Mediator. DO/DON'T pseudocode, 'when to apply' notes. Activate when selecting a service/component-level pattern."which pattern to apply\".",
+  "default_prompt": "Use $design-patterns-architectural-reference when the task matches the \"Design Patterns — Architectural + Microservices Reference\" skill.",
+  "triggers": [
+    "design-patterns-architectural-reference",
+    "design patterns architectural reference",
+    "Design patterns reference with DO/DON'T examples — SOLID, DRY/KISS/YAGNI, GoF (Strategy, Observer, Factory, Adapter, Facade, Decorator, Command, State, Template Method), architectural (Repository, Service Layer, DI, Event-Driven, CQRS), microservices (Saga, Circuit Breaker)"
+  ],
+  "capabilities": [
+    "design",
+    "architectural",
+    "microservices",
+    "reference"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/development/locales/en/.agents/skills/design-patterns-architectural-reference/agents/kimi.yaml

@@ -0,0 +1,15 @@
+name: "design-patterns-architectural-reference"
+display_name: "Design Patterns — Architectural + Microservices Reference"
+description: "Canonical reference of architectural and microservice patterns — Repository / Service Layer / Dependency Injection / Event-Driven / CQRS / Saga / Circuit Breaker / Mediator. DO/DON'T pseudocode, 'when to apply' notes. Activate when selecting a service/component-level pattern."which pattern to apply\"."
+default_prompt: "Use $design-patterns-architectural-reference when the task matches the \"Design Patterns — Architectural + Microservices Reference\" skill."
+triggers:
+  - "design-patterns-architectural-reference"
+  - "design patterns architectural reference"
+  - "Design patterns reference with DO/DON'T examples — SOLID, DRY/KISS/YAGNI, GoF (Strategy, Observer, Factory, Adapter, Facade, Decorator, Command, State, Template Method), architectural (Repository, Service Layer, DI, Event-Driven, CQRS), microservices (Saga, Circuit Breaker)"
+capabilities:
+  - "design"
+  - "architectural"
+  - "microservices"
+  - "reference"
+tools: []
+implicit_invocation: true

package/domains/development/locales/en/.agents/skills/design-patterns-architectural-reference/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "Design Patterns — Architectural + Microservices Reference"
+  short_description: "Canonical reference of architectural and microservice patterns — Repository / Service Layer / Dependency Injection / Event-Driven / CQRS / Saga / Circuit Breaker / Mediator. DO/DON'T pseudocode, 'when to apply' notes. Activate when selecting a service/component-level pattern."
+  default_prompt: "Use $design-patterns-architectural-reference when the task matches the \"Design Patterns — Architectural + Microservices Reference\" skill."
+dependencies:
+  tools: []
+policy:
+  allow_implicit_invocation: true

package/domains/development/locales/en/.agents/skills/design-patterns-architectural-reference/agents/qwen.json

@@ -0,0 +1,19 @@
+{
+  "name": "design-patterns-architectural-reference",
+  "display_name": "Design Patterns — Architectural + Microservices Reference",
+  "description": "Canonical reference of architectural and microservice patterns — Repository / Service Layer / Dependency Injection / Event-Driven / CQRS / Saga / Circuit Breaker / Mediator. DO/DON'T pseudocode, 'when to apply' notes. Activate when selecting a service/component-level pattern."which pattern to apply\".",
+  "default_prompt": "Use $design-patterns-architectural-reference when the task matches the \"Design Patterns — Architectural + Microservices Reference\" skill.",
+  "triggers": [
+    "design-patterns-architectural-reference",
+    "design patterns architectural reference",
+    "Design patterns reference with DO/DON'T examples — SOLID, DRY/KISS/YAGNI, GoF (Strategy, Observer, Factory, Adapter, Facade, Decorator, Command, State, Template Method), architectural (Repository, Service Layer, DI, Event-Driven, CQRS), microservices (Saga, Circuit Breaker)"
+  ],
+  "capabilities": [
+    "design",
+    "architectural",
+    "microservices",
+    "reference"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/development/locales/en/.agents/skills/design-patterns-architectural-reference/agents/skill.yaml

@@ -0,0 +1,23 @@
+version: 1
+name: "design-patterns-architectural-reference"
+display_name: "Design Patterns — Architectural + Microservices Reference"
+description: "Canonical reference of architectural and microservice patterns — Repository / Service Layer / Dependency Injection / Event-Driven / CQRS / Saga / Circuit Breaker / Mediator. DO/DON'T pseudocode, 'when to apply' notes. Activate when selecting a service/component-level pattern."which pattern to apply\"."
+default_prompt: "Use $design-patterns-architectural-reference when the task matches the \"Design Patterns — Architectural + Microservices Reference\" skill."
+triggers:
+  - "design-patterns-architectural-reference"
+  - "design patterns architectural reference"
+  - "Design patterns reference with DO/DON'T examples — SOLID, DRY/KISS/YAGNI, GoF (Strategy, Observer, Factory, Adapter, Facade, Decorator, Command, State, Template Method), architectural (Repository, Service Layer, DI, Event-Driven, CQRS), microservices (Saga, Circuit Breaker)"
+capabilities:
+  - "design"
+  - "architectural"
+  - "microservices"
+  - "reference"
+tools: []
+invocation:
+  explicit: true
+  implicit: true
+localization:
+  default_locale: "en"
+  available_locales:
+    - "ru"
+    - "en"