code-ai-installer 2.5.0 → 4.0.0

package/domains/development/.agents/skills/api-contracts-reference/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: api-contracts-reference
+description: Канонический справочник шаблонов API контрактов — endpoint template с Zod schema, JSON-примеры error/pagination, integration contracts (webhook + external API), sample проекта. Активируй при поиске конкретного шаблона endpoint, integration pattern или JSON-формы.
+type: reference
+domain: development
+owners:
+  - architect
+gates:
+  - ARCH
+tech: []
+topic:
+  - architecture
+triggers:
+  - пример API контракта
+  - endpoint template
+  - webhook contract пример
+  - cursor pagination JSON
+  - Zod schema endpoint
+  - API sample проект
+  - integration contract пример
+related:
+  - api-contracts
+  - architecture-doc
+  - architecture-doc-reference
+  - data-model
+  - security-baseline-dev
+  - n8n-pinecone-qdrant-supabase
+  - n8n-pinecone-qdrant-supabase-reference
+  - wix-self-hosted-embedded-script
+  - wix-self-hosted-embedded-script-reference
+budget_lines: 500
+schema_version: 1
+---
+
+
+# Skill: API Contracts — Reference
+
+Растущая canonical library шаблонов API контрактов: endpoint template, Zod schema, JSON-примеры, integration patterns, sample проектов.
+
+**Разделы:**
+1. [Endpoint Definition Template](#1-endpoint-template)
+2. [Zod Schema Pattern](#2-zod)
+3. [Error JSON Example](#3-error-json)
+4. [Cursor Pagination Example](#4-pagination-json)
+5. [Integration Contract Examples](#5-integration)
+6. [Sample: SaaS Admin Panel](#6-sample)
+7. [Растущая библиотека](#7-growing-library)
+
+> Правила/conventions/Output Template → `$api-contracts` (workflow-skill).
+
+---
+
+## 1. Endpoint Definition Template
+
+Для каждого endpoint заполни:
+
+```markdown
+### POST /api/v1/products
+
+**Summary:** Create a new product for the tenant.
+
+**Auth:** Required (tenantId in path or JWT)
+
+**Request:**
+| Field | Type | Required | Constraints | Example |
+|-------|------|----------|------------|---------|
+| name | string | ✅ | 3-100 chars | "Premium Widget" |
+| price | number | ✅ | 0.01-99999 | 29.99 |
+| category | string | ✅ | enum: digital, physical, subscription | "digital" |
+| active | boolean | ⬜ | default: true | true |
+
+**Request example:**
+\`\`\`json
+{
+  "name": "Premium Widget",
+  "price": 29.99,
+  "category": "digital"
+}
+\`\`\`
+
+**Response (201):**
+\`\`\`json
+{
+  "data": {
+    "id": "p-abc123",
+    "name": "Premium Widget",
+    "price": 29.99,
+    "category": "digital",
+    "active": true,
+    "createdAt": "2026-03-13T03:00:00Z",
+    "updatedAt": "2026-03-13T03:00:00Z"
+  }
+}
+\`\`\`
+
+**Errors:**
+| Status | Code | When |
+|--------|------|------|
+| 400 | VALIDATION_ERROR | Invalid input (see details) |
+| 409 | DUPLICATE | Product name already exists for this tenant |
+| 401 | UNAUTHORIZED | Missing or invalid auth |
+
+**Perf notes:**
+- Unique index on (tenantId, name) — O(log n) lookup
+- No pagination needed (single resource create)
+```
+
+---
+
+## 2. Zod Schema Pattern
+
+```js
+import { z } from 'zod';
+
+/**
+ * Schema для создания продукта.
+ */
+export const createProductSchema = z.object({
+  name: z.string()
+    .min(3, 'Name must be at least 3 characters')
+    .max(100, 'Name must be at most 100 characters')
+    .trim(),
+  price: z.number()
+    .min(0.01, 'Price must be at least 0.01')
+    .max(99999, 'Price cannot exceed 99999'),
+  category: z.enum(['digital', 'physical', 'subscription']),
+  active: z.boolean().optional().default(true),
+});
+```
+
+---
+
+## 3. Error JSON Example
+
+Единый формат для всех endpoints:
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid input",
+    "details": [
+      { "field": "code", "message": "Must be at least 3 characters" },
+      { "field": "discount", "message": "Must be at least 1" }
+    ]
+  }
+}
+```
+
+> Полный реестр error codes (HTTP / code / description / when) → `$api-contracts` §3.
+
+---
+
+## 4. Cursor Pagination Example
+
+```markdown
+### GET /api/v1/products
+
+**Query params:**
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| limit | number | 20 | Max items per page (1-100) |
+| cursor | string | — | Cursor from previous response |
+| status | string | — | Filter: "active" or "inactive" |
+| q | string | — | Search by name (case-insensitive) |
+| sort | string | -createdAt | Sort field with direction prefix |
+
+**Response (200):**
+\`\`\`json
+{
+  "data": [...],
+  "pagination": {
+    "nextCursor": "eyJpZCI6ImMtYWJjMTIzIn0=",
+    "hasMore": true,
+    "total": 42
+  }
+}
+\`\`\`
+```
+
+> Convention table (когда cursor vs offset vs no-pagination) → `$api-contracts` §4.
+
+---
+
+## 5. Integration Contract Examples
+
+### Webhook contract
+
+```markdown
+### POST /api/webhooks/v1/install
+
+**Source:** External Platform
+**Auth:** JWT signature verification (not Bearer token)
+**Content-Type:** text/plain (JWT string)
+
+**Processing:**
+1. Decode JWT (verify signature in production)
+2. Extract tenantId from payload
+3. Upsert tenant + default settings
+4. Call Platform registration API
+5. Return 200 { success: true }
+
+**Idempotent:** Yes (upsert)
+**Retry:** Platform retries on timeout/5xx
+**Timeout:** Must respond within 10s
+```
+
+### External API call contract
+
+```markdown
+### External Platform API
+
+**Endpoint:** POST https://api.example.com/v1/register
+**Auth:** OAuth access token
+**Timeout:** 5s
+**Retry:** 2x with exponential backoff (1s, 3s)
+**Idempotent:** Yes (same registration = no-op)
+**Failure handling:** Log error, don't fail webhook (retry manually)
+```
+
+---
+
+## 6. Sample: SaaS Admin Panel
+
+Полный набор endpoints для типичного SaaS Admin проекта:
+
+```markdown
+# API Contracts: SaaS Admin Panel
+
+## Endpoints
+
+| Method | Path | Auth | Summary |
+|--------|------|------|---------|
+| GET | /api/v1/content/:tenantId | Public | Public content payload |
+| GET | /api/v1/content/resolve-tenant | Public | Resolve tenantId from origin |
+| GET | /api/v1/settings/:tenantId | Owner | Get settings |
+| PUT | /api/v1/settings/:tenantId | Owner | Update settings |
+| GET | /api/v1/products | Owner | List products (paginated) |
+| POST | /api/v1/products | Owner | Create product |
+| PUT | /api/v1/products/:id | Owner | Update product |
+| DELETE | /api/v1/products/:id | Owner | Delete product |
+| POST | /api/webhooks/v1/install | Webhook | Platform install webhook |
+| POST | /api/webhooks/v1/uninstall | Webhook | Platform uninstall webhook |
+| GET | /health/live | Public | Liveness probe |
+| GET | /health/ready | Public | Readiness probe |
+```
+
+---
+
+## 7. Растущая библиотека
+
+Этот файл — **canonical library, которая растёт**. Архитектор добавляет новые шаблоны API контрактов через `update_skill` / `create_skill` MCP-инструменты по мере накопления новых стилей и паттернов:
+
+- GraphQL contracts (schemas, resolvers, persisted queries)
+- gRPC services (proto definitions, error model)
+- WebSocket / SSE protocols (event schemas, heartbeats, reconnect)
+- BFF (Backend-For-Frontend) patterns
+- OpenAPI / Swagger spec examples
+- REST → GraphQL migration patterns
+- API versioning examples (header vs URL vs media-type)
+- Rate-limit + circuit-breaker contract patterns
+- Multi-tenant scoping conventions
+
+Каждый новый шаблон — полный пример в стиле §1-§5: complete request/response/errors/auth/idempotency notes.
+
+---
+
+## См. также
+- `$api-contracts` — правила, conventions, output template (workflow-skill)
+- `$architecture-doc` — Architecture Document (references API contracts)
+- `$data-model` — Data model (entities match request/response schemas)
+- `$security-baseline-dev` — Zod validation, auth patterns

package/domains/development/.agents/skills/api-contracts-reference/agents/claude.json

@@ -0,0 +1,19 @@
+{
+  "name": "api-contracts-reference",
+  "display_name": "API-контракты",
+  "description": "Канонический справочник шаблонов API контрактов — endpoint template с Zod schema, JSON-примеры error/pagination, integration contracts (webhook + external API), sample проекта. Активируй при поиске конкретного шаблона endpoint, integration pattern или JSON-формы.",
+  "default_prompt": "Используй $api-contracts-reference, когда задача относится к навыку \"Справочник шаблонов API контрактов\".",
+  "triggers": [
+    "api-contracts-reference",
+    "api contracts reference",
+    "API-контракты",
+    "Справочник шаблонов API контрактов по UX flows — эндпоинты, схемы, ошибки, валидация, авторизация, perf/scalability соображения, идемпотентность и интеграционные паттерны"
+  ],
+  "capabilities": [
+    "api",
+    "reference",
+    "templates"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/development/.agents/skills/api-contracts-reference/agents/copilot.json

@@ -0,0 +1,19 @@
+{
+  "name": "api-contracts-reference",
+  "display_name": "API-контракты",
+  "description": "Канонический справочник шаблонов API контрактов — endpoint template с Zod schema, JSON-примеры error/pagination, integration contracts (webhook + external API), sample проекта. Активируй при поиске конкретного шаблона endpoint, integration pattern или JSON-формы.",
+  "default_prompt": "Используй $api-contracts-reference, когда задача относится к навыку \"Справочник шаблонов API контрактов\".",
+  "triggers": [
+    "api-contracts-reference",
+    "api contracts reference",
+    "API-контракты",
+    "Справочник шаблонов API контрактов по UX flows — эндпоинты, схемы, ошибки, валидация, авторизация, perf/scalability соображения, идемпотентность и интеграционные паттерны"
+  ],
+  "capabilities": [
+    "api",
+    "reference",
+    "templates"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/development/.agents/skills/api-contracts-reference/agents/gemini.json

@@ -0,0 +1,19 @@
+{
+  "name": "api-contracts-reference",
+  "display_name": "API-контракты",
+  "description": "Канонический справочник шаблонов API контрактов — endpoint template с Zod schema, JSON-примеры error/pagination, integration contracts (webhook + external API), sample проекта. Активируй при поиске конкретного шаблона endpoint, integration pattern или JSON-формы.",
+  "default_prompt": "Используй $api-contracts-reference, когда задача относится к навыку \"Справочник шаблонов API контрактов\".",
+  "triggers": [
+    "api-contracts-reference",
+    "api contracts reference",
+    "API-контракты",
+    "Справочник шаблонов API контрактов по UX flows — эндпоинты, схемы, ошибки, валидация, авторизация, perf/scalability соображения, идемпотентность и интеграционные паттерны"
+  ],
+  "capabilities": [
+    "api",
+    "reference",
+    "templates"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/development/.agents/skills/api-contracts-reference/agents/kimi.yaml

@@ -0,0 +1,15 @@
+name: "api-contracts-reference"
+display_name: "API-контракты"
+description: "Канонический справочник шаблонов API контрактов — endpoint template с Zod schema, JSON-примеры error/pagination, integration contracts (webhook + external API), sample проекта. Активируй при поиске конкретного шаблона endpoint, integration pattern или JSON-формы."
+default_prompt: "Используй $api-contracts-reference, когда задача относится к навыку \"Справочник шаблонов API контрактов\"."
+triggers:
+  - "api-contracts-reference"
+  - "api contracts reference"
+  - "API-контракты"
+  - "Справочник шаблонов API контрактов по UX flows — эндпоинты, схемы, ошибки, валидация, авторизация, perf/scalability соображения, идемпотентность и интеграционные паттерны"
+capabilities:
+  - "api"
+  - "reference"
+  - "templates"
+tools: []
+implicit_invocation: true

package/domains/development/.agents/skills/api-contracts-reference/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "API-контракты"
+  short_description: "Канонический справочник шаблонов API контрактов — endpoint template с Zod schema, JSON-примеры error/pagination, integration contracts (webhook + external API), sample проекта. Активируй при поиске конкретного шаблона endpoint, integration pattern или JSON-формы."
+  default_prompt: "Используй $api-contracts-reference, когда задача относится к навыку \"Справочник шаблонов API контрактов\"."
+dependencies:
+  tools: []
+policy:
+  allow_implicit_invocation: true

package/domains/development/.agents/skills/api-contracts-reference/agents/qwen.json

@@ -0,0 +1,19 @@
+{
+  "name": "api-contracts-reference",
+  "display_name": "API-контракты",
+  "description": "Канонический справочник шаблонов API контрактов — endpoint template с Zod schema, JSON-примеры error/pagination, integration contracts (webhook + external API), sample проекта. Активируй при поиске конкретного шаблона endpoint, integration pattern или JSON-формы.",
+  "default_prompt": "Используй $api-contracts-reference, когда задача относится к навыку \"Справочник шаблонов API контрактов\".",
+  "triggers": [
+    "api-contracts-reference",
+    "api contracts reference",
+    "API-контракты",
+    "Справочник шаблонов API контрактов по UX flows — эндпоинты, схемы, ошибки, валидация, авторизация, perf/scalability соображения, идемпотентность и интеграционные паттерны"
+  ],
+  "capabilities": [
+    "api",
+    "reference",
+    "templates"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/development/.agents/skills/api-contracts-reference/agents/skill.yaml

@@ -0,0 +1,23 @@
+version: 1
+name: "api-contracts-reference"
+display_name: "API-контракты"
+description: "Канонический справочник шаблонов API контрактов — endpoint template с Zod schema, JSON-примеры error/pagination, integration contracts (webhook + external API), sample проекта. Активируй при поиске конкретного шаблона endpoint, integration pattern или JSON-формы."
+default_prompt: "Используй $api-contracts-reference, когда задача относится к навыку \"Справочник шаблонов API контрактов\"."
+triggers:
+  - "api-contracts-reference"
+  - "api contracts reference"
+  - "API-контракты"
+  - "Справочник шаблонов API контрактов по UX flows — эндпоинты, схемы, ошибки, валидация, авторизация, perf/scalability соображения, идемпотентность и интеграционные паттерны"
+capabilities:
+  - "api"
+  - "reference"
+  - "templates"
+tools: []
+invocation:
+  explicit: true
+  implicit: true
+localization:
+  default_locale: "ru"
+  available_locales:
+    - "ru"
+    - "en"

package/domains/development/.agents/skills/architecture-compliance-review/SKILL.md

@@ -1,18 +1,51 @@
 ---
 name: architecture-compliance-review
 description: Проверка соответствия кода архитектуре/ADR — границы модулей, слои, зависимости, конвенции, red flags.
+type: triggered
+domain: development
+owners:
+  - architect
+  - reviewer
+gates:
+  - ARCH
+  - REV
+tech: []
+topic:
+  - architecture
+  - review
+  - security
+triggers:
+  - ревью архитектуры
+  - соответствие ADR
+  - границы модулей
+  - слои приложения
+  - архитектурный дрифт
+  - red flags архитектуры
+related:
+  - architecture-doc
+  - architecture-doc-reference
+  - adr-log
+  - adr-log-reference
+  - design-patterns-reference
+  - code-review-checklist
+  - current-state-analysis
+  - lava-flow-legacy-detection
+  - system-design-checklist
+budget_lines: 300
+schema_version: 1
 ---
 
+
 # Skill: Architecture Compliance Review
 
 Ревью на соответствие архитектурному документу и ADR.
 
 **Разделы:**
-1. [Expected Architecture](#1-expected)
+1. [Expected Architecture](#1-expected-architecture)
 2. [Checklist](#2-checklist)
-3. [Automated Detection](#3-detection)
+3. [Automated Detection](#3-automated-detection)
 4. [Red Flags](#4-red-flags)
-5. [Output Template](#5-output)
+5. [Output Template](#5-output-template)
 
 ---
 
@@ -205,7 +238,6 @@ find_by_name: Pattern="*.js" → for each: check line count
 ```
 
 ---
-
 ## См. также
 - `$architecture-doc` — Architecture Document (reference)
 - `$adr-log` — ADR Log (reference)

package/domains/development/.agents/skills/architecture-compliance-review/agents/kimi.yaml

@@ -1,15 +1,15 @@
-name: "architecture-compliance-review"
-display_name: "Проверка соответствия архитектуре"
-description: "Проверка соответствия кода архитектуре/ADR — границы модулей, слои, зависимости, конвенции, red flags."
-default_prompt: "Используй $architecture-compliance-review, когда задача относится к навыку \"Проверка соответствия архитектуре\"."
-triggers:
-  - "architecture-compliance-review"
-  - "architecture compliance review"
-  - "Проверка соответствия архитектуре"
-  - "Проверка соответствия кода архитектуре/ADR — границы модулей, слои, зависимости, конвенции, red flags"
-capabilities:
-  - "architecture"
-  - "compliance"
-  - "review"
-tools: []
-implicit_invocation: true
+name: "architecture-compliance-review"
+display_name: "Проверка соответствия архитектуре"
+description: "Проверка соответствия кода архитектуре/ADR — границы модулей, слои, зависимости, конвенции, red flags."
+default_prompt: "Используй $architecture-compliance-review, когда задача относится к навыку \"Проверка соответствия архитектуре\"."
+triggers:
+  - "architecture-compliance-review"
+  - "architecture compliance review"
+  - "Проверка соответствия архитектуре"
+  - "Проверка соответствия кода архитектуре/ADR — границы модулей, слои, зависимости, конвенции, red flags"
+capabilities:
+  - "architecture"
+  - "compliance"
+  - "review"
+tools: []
+implicit_invocation: true

package/domains/development/.agents/skills/architecture-compliance-review/agents/skill.yaml

@@ -1,23 +1,22 @@
-version: 1
-name: "architecture-compliance-review"
-display_name: "Проверка соответствия архитектуре"
-description: "Проверка соответствия кода архитектуре/ADR — границы модулей, слои, зависимости, конвенции, red flags."
-default_prompt: "Используй $architecture-compliance-review, когда задача относится к навыку \"Проверка соответствия архитектуре\"."
-triggers:
-  - "architecture-compliance-review"
-  - "architecture compliance review"
-  - "Проверка соответствия архитектуре"
-  - "Проверка соответствия кода архитектуре/ADR — границы модулей, слои, зависимости, конвенции, red flags"
-capabilities:
-  - "architecture"
-  - "compliance"
-  - "review"
-tools: []
-invocation:
-  explicit: true
-  implicit: true
-localization:
-  default_locale: "ru"
-  available_locales:
-    - "ru"
-    - "en"
+version: 1
+name: "architecture-compliance-review"
+display_name: "Проверка соответствия архитектуре"
+description: "Проверка соответствия кода архитектуре/ADR — границы модулей, слои, зависимости, конвенции, red flags."
+default_prompt: "Используй $architecture-compliance-review, когда задача относится к навыку \"Проверка соответствия архитектуре\"."
+triggers:
+  - "architecture-compliance-review"
+  - "architecture compliance review"
+  - "Проверка соответствия архитектуре"
+capabilities:
+  - "architecture"
+  - "compliance"
+  - "review"
+tools: []
+invocation:
+  explicit: true
+  implicit: true
+localization:
+  default_locale: "ru"
+  available_locales:
+    - "ru"
+    - "en"