code-ai-installer 1.3.0 → 1.4.0

package/.agents/skills/observability_plan/SKILL.md

@@ -0,0 +1,276 @@
+---
+name: observability_plan
+description: План наблюдаемости — какие логи/метрики/трейсы собирать, корреляция запросов, уровни логов, алерты. Без утечки PII/секретов.
+---
+
+# Skill: Observability Plan
+
+Архитектурный план наблюдаемости: что логировать, что измерять, когда алертить.
+
+**Разделы:**
+1. [Logging Plan](#1-logging)
+2. [Metrics Plan](#2-metrics)
+3. [Alerting Plan](#3-alerting)
+4. [Tracing](#4-tracing)
+5. [UX Error Mapping](#5-ux-mapping)
+6. [Dashboard Layout](#6-dashboard)
+7. [Пример](#7-пример)
+8. [Output Template](#8-output)
+
+---
+
+## 1. Logging Plan
+
+### Log Events Registry
+
+| Event | Level | When | Fields | Example message |
+|-------|-------|------|--------|----------------|
+| `server_started` | info | App startup | port, env, version | "Server started" |
+| `server_shutdown` | info | Graceful shutdown | reason, uptime | "Server shutting down" |
+| `http_request` | info | Every request (finish) | method, url, status, durationMs, requestId | "HTTP request" |
+| `slow_request` | warn | durationMs > 2000 | method, url, durationMs | "Slow request detected" |
+| `item_created` | info | POST /items success | itemId, ownerId | "Item created" |
+| `item_duplicate` | warn | POST /items 409 | name, ownerId | "Duplicate item" |
+| `settings_updated` | info | PUT /settings success | ownerId, changedFields | "Settings updated" |
+| `webhook_received` | info | Webhook received | eventType, sourceId | "Processing webhook" |
+| `content_served` | info | Public content served | contentId, durationMs | "Content served" |
+| `content_not_found` | warn | GET /content/:id 404 | contentId | "Content not found" |
+| `validation_error` | warn | Input validation failed | endpoint, fields, requestId | "Validation failed" |
+| `auth_failed` | warn | Auth check failed | endpoint, reason, ip | "Authentication failed" |
+| `db_error` | error | DB operation failed | operation, err | "Database error" |
+| `db_connected` | info | DB connection established | host, dbName | "MongoDB connected" |
+| `db_disconnected` | warn | DB connection lost | — | "MongoDB disconnected" |
+| `unhandled_error` | error | Uncaught exception | err, requestId | "Unhandled error" |
+
+### Correlation
+
+```
+Every request gets:
+  requestId: UUID (from X-Request-ID header or generated)
+  → Attached to child logger: req.log = logger.child({ requestId })
+  → All logs in request chain include requestId automatically
+  → Propagated to external calls via X-Request-ID header
+```
+
+### Log levels by environment
+
+| Env | Level | Reason |
+|-----|-------|--------|
+| Production | `info` | Business events + errors |
+| Staging | `debug` | Debugging without overload |
+| Development | `debug` | Full visibility |
+| Test | `silent` | Don't clutter test output |
+
+### PII/Secrets — never log
+
+| Field | Rule |
+|-------|------|
+| `password` | pino redact |
+| `token` / `secret` / `apiKey` | pino redact |
+| `authorization` header | pino redact |
+| `cookie` header | pino redact |
+| `email` | mask: `a****@example.com` |
+| `creditCard` | pino redact |
+| Connection string | pino redact `DATABASE_URL` |
+
+---
+
+## 2. Metrics Plan
+
+### Key Metrics
+
+| Metric | Type | Labels | Purpose |
+|--------|------|--------|---------|
+| `http_requests_total` | Counter | method, route, status | Request volume |
+| `http_request_duration_seconds` | Histogram | method, route, status | Latency (p50/p95/p99) |
+| `http_errors_total` | Counter | method, route, status | Error rate |
+| `db_query_duration_seconds` | Histogram | operation, collection | DB performance |
+| `db_connections_active` | Gauge | — | Connection pool usage |
+| `content_requests_total` | Counter | status | Public content traffic |
+| `webhook_processed_total` | Counter | type, status | Webhook processing |
+
+### Latency targets
+
+| Endpoint | p50 | p95 | p99 | Alert threshold (p95) |
+|----------|-----|-----|-----|-----------------------|
+| GET /content/:id | 10ms | 50ms | 100ms | > 200ms |
+| PUT /settings | 20ms | 100ms | 500ms | > 1000ms |
+| POST /items | 20ms | 100ms | 500ms | > 1000ms |
+| POST /webhooks | 50ms | 500ms | 2000ms | > 5000ms |
+
+---
+
+## 3. Alerting Plan
+
+### Alert Rules
+
+| Alert | Condition | Severity | Channel | Response |
+|-------|-----------|----------|---------|----------|
+| **High error rate** | 5xx > 5% of requests (5 min window) | 🔴 Critical | Slack/PagerDuty | Check logs, identify failing endpoint |
+| **Latency spike** | p95 > 2x target (5 min window) | 🟠 Warning | Slack | Check DB performance, slow queries |
+| **DB down** | Health check /ready fails 3 consecutive | 🔴 Critical | Slack/PagerDuty | Check MongoDB, restart if needed |
+| **Webhook failures** | Webhook processing fail > 3/hour | 🟠 Warning | Slack | Check external API, retry manually |
+| **Disk space** | > 85% used | 🟠 Warning | Slack | Clean logs, expand volume |
+| **No traffic** | 0 requests for 10 min (production) | 🟠 Warning | Slack | Check gateway, DNS, upstream services |
+
+### Silence rules
+
+| Condition | Silence |
+|-----------|---------|
+| Deployment in progress | 10 min after deploy |
+| Planned maintenance | Duration of maintenance window |
+| Known upstream outage | Until resolved |
+
+---
+
+## 4. Tracing
+
+### Span structure (if implementing distributed tracing)
+
+```
+[HTTP Request] ← parent span
+  ├── [Auth Check]
+  ├── [Validation]
+  ├── [Service Call]
+  │   ├── [DB Query: findOne]
+  │   └── [DB Query: updateOne]
+  └── [Response Serialization]
+```
+
+### MVP approach (без full tracing infra)
+
+For MVP, structured logs with `requestId` correlation provide 80% of tracing value:
+
+```
+# Find all logs for a specific request:
+grep "requestId":"abc-123" app.log
+
+# Trace request flow:
+13:00:01 INFO  requestId=abc-123 msg="HTTP request started" method=PUT url=/api/v1/settings/app-1
+13:00:01 DEBUG requestId=abc-123 msg="Validation passed"
+13:00:01 DEBUG requestId=abc-123 msg="DB query" operation=updateOne durationMs=5
+13:00:01 INFO  requestId=abc-123 msg="HTTP request" status=200 durationMs=12
+```
+
+---
+
+## 5. UX Error Mapping
+
+### API errors → UI states
+
+| API Error | HTTP | UI State | User sees |
+|-----------|------|----------|-----------|
+| Validation | 400 | Form error | Red field borders + messages |
+| Not Found | 404 | Empty state | "Not found" illustration |
+| Duplicate | 409 | Form error | "Code already exists" |
+| Auth | 401 | Redirect | Login page / re-auth |
+| Forbidden | 403 | Error state | "Access denied" |
+| Rate limit | 429 | Toast | "Too many requests, try later" |
+| Server error | 500 | Error state | "Something went wrong" + retry button |
+| Widget 404 | 404 | No render | Embedded script silently fails (no popup) |
+| Widget 500 | 500 | No render | Embedded script silently fails |
+
+### Rule: Embedded script NEVER shows errors to visitors
+
+```
+Widget errors → console.error('[App] ...') → no UI
+Dashboard errors → toast or inline error → clear user message
+```
+
+---
+
+## 6. Dashboard Layout
+
+### Recommended observability dashboard sections
+
+```
+┌─────────────────────────────────────────────┐
+│               OVERVIEW                       │
+│  Request Rate ▏ Error Rate ▏ p95 Latency    │
+│  [sparkline]  ▏ [sparkline]▏ [sparkline]    │
+├─────────────────────────────────────────────┤
+│               ENDPOINTS                      │
+│  Table: route, requests, errors, p95, p99   │
+├─────────────────────────────────────────────┤
+│               ERRORS                         │
+│  Top errors by: code, endpoint, message     │
+├─────────────────────────────────────────────┤
+│               DATABASE                       │
+│  Query duration ▏ Connections ▏ Slow queries │
+├─────────────────────────────────────────────┤
+│               INTEGRATIONS                   │
+│  External API: success/fail │ Webhook: rate   │
+└─────────────────────────────────────────────┘
+```
+
+---
+
+## 7. Пример
+
+```markdown
+# Observability Plan: SaaS Admin Panel
+
+## Logging
+- Structured JSON (pino), level: info (prod), debug (dev)
+- requestId correlation on all requests
+- Redact: authorization, password, token, cookie, DATABASE_URL
+
+## Key Metrics
+- http_requests_total (method, route, status)
+- http_request_duration_seconds (p50, p95, p99)
+- Public content serve rate + latency
+- Webhook processing rate + success/fail
+
+## Alerts
+- 🔴 Error rate > 5% → immediate
+- 🔴 DB health check fail → immediate
+- 🟠 p95 latency > 2x target → investigation
+- 🟠 Webhook fail > 3/hour → manual retry
+
+## UX Error Mapping
+- Dashboard: toast/inline errors with clear messages
+- Public content: graceful fallback (no error UI)
+```
+
+---
+
+## 8. Output Template
+
+```markdown
+# Observability Plan: <project-name>
+
+**Date:** YYYY-MM-DD
+
+## Logging
+### Events Registry
+<section 1 event table>
+
+### Correlation
+<requestId strategy>
+
+### Redaction
+<PII/secrets list>
+
+## Metrics
+<section 2 metrics table + latency targets>
+
+## Alerting
+<section 3 alert rules>
+
+## Tracing
+<section 4 strategy>
+
+## UX Error Mapping
+<section 5 table>
+
+## Dashboard
+<section 6 layout>
+```
+
+---
+
+## См. также
+- `$observability_logging` — implementation (pino setup, middleware, redaction code)
+- `$architecture_doc` — Architecture Document (observability section)
+- `$api_contracts` — error codes (map to UI states)
+- `$threat_model_baseline` — audit logging requirements

package/.agents/skills/pm_backlog/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: pm_backlog
+description: Декомпозиция PRD в первичный backlog — эпики, фичи и задачи с приоритетами, зависимостями и предложением итераций (MVP → v1).
+---
+
+# Skill: Backlog (эпики/фичи/задачи)
+
+Превратить PRD в планируемую работу.
+
+**Разделы:**
+1. [Workflow](#1-workflow)
+2. [Hierarchy](#2-hierarchy)
+3. [Task Card Template](#3-task-card)
+4. [Decomposition Rules](#4-rules)
+5. [Iteration Planning](#5-iterations)
+6. [Пример](#6-пример)
+7. [Output Template](#7-output)
+
+---
+
+## 1. Workflow
+
+```
+1. Input: PRD (из $pm_prd) — user stories + AC
+2. Group stories into Epics (business domain areas)
+3. Break each story into Features (deliverable chunks)
+4. Break each feature into Tasks (implementable units)
+5. Assign priorities (P0/P1/P2)
+6. Map dependencies
+7. Propose iterations (section 5)
+8. Submit for review → $board
+```
+
+---
+
+## 2. Hierarchy
+
+```
+Epic (E-xx) — business domain area
+├── Feature (F-xx) — deliverable user-facing chunk
+│   ├── Task (T-xx) — implementable unit (1-4h of work)
+│   ├── Task (T-xx)
+│   └── Task (T-xx)
+├── Feature (F-xx)
+│   └── ...
+└── Spike (SP-xx) — research / time-boxed exploration
+```
+
+### Level definitions
+
+| Level | What | Size | Example |
+|-------|------|------|---------|
+| **Epic** | Business domain area | 1-3 weeks | E-01: Settings Management |
+| **Feature** | User-facing deliverable | 2-5 days | F-01: Settings CRUD API |
+| **Task** | Implementable unit | 1-4 hours | T-01: Create settings schema |
+| **Spike** | Research / exploration | Time-boxed (2-8h) | SP-01: Evaluate external API integration |
+
+---
+
+## 3. Task Card Template
+
+```markdown
+### T-XX: <Title>
+
+**Feature:** F-XX
+**Owner:** DEV / UX / ARCH / TEST
+**Priority:** P0 / P1 / P2
+**Estimate:** XS (1h) / S (2h) / M (4h) / L (8h) / XL (16h)
+
+**Description:**
+<What needs to be done, concretely>
+
+**Acceptance Criteria:**
+- [ ] <Measurable, checkable criterion>
+- [ ] <Measurable, checkable criterion>
+
+**Dependencies:**
+- Requires: T-XX (schema), F-XX (API)
+- Blocks: T-XX (UI integration)
+
+**DoD (Definition of Done):**
+- [ ] Code complete
+- [ ] Unit tests pass
+- [ ] Code review passed
+- [ ] No P0 bugs
+```
+
+### Estimation guide
+
+| Size | Hours | Complexity | Example |
+|------|:-----:|-----------|---------|
+| **XS** | ~1h | Trivial change | Add field to schema |
+| **S** | ~2h | Simple, well-understood | CRUD endpoint |
+| **M** | ~4h | Moderate, some decisions | Form with validation |
+| **L** | ~8h | Complex, multiple parts | Full settings page |
+| **XL** | ~16h | Large, risky → split if possible | Template system |
+
+---
+
+## 4. Decomposition Rules
+
+| Rule | Explanation |
+|------|------------|
+| **Vertical slices** | End-to-end features (API + UI + tests), not layer-by-layer |
+| **MVP first** | P0 = product doesn't work without it |
+| **One task = one result** | Each task produces a checkable artifact |
+| **Max 4h per task** | If larger → split into subtasks |
+| **Spike for unknowns** | Uncertainty → create time-boxed Spike task |
+| **Dependencies explicit** | State what's required before and what this blocks |
+| **Cross-cutting last** | Polish, a11y, perf → P1/P2 after core works |
+
+### Priority rules
+
+| Priority | Criteria | % of MVP |
+|----------|---------|:--------:|
+| 🔴 **P0** | Core functionality, must ship | 60-70% |
+| 🟠 **P1** | Important UX, error handling, polish | 20-30% |
+| 🟡 **P2** | Nice-to-have, future iteration | 5-10% |
+
+---
+
+## 5. Iteration Planning
+
+### Iteration format
+
+```markdown
+### Iteration N: <Name> (<duration>)
+
+**Goal:** <One-sentence goal>
+**Scope:** <Features/tasks included>
+**Entry criteria:** <What must be ready>
+**Exit criteria:** <What must be done>
+
+| Task | Priority | Estimate | Owner | Status |
+|------|:--------:|:--------:|:-----:|:------:|
+| T-01 | P0 | S | DEV | ☐ |
+| T-02 | P0 | M | DEV | ☐ |
+```
+
+### Typical MVP breakdown
+
+| Iteration | Focus | Content |
+|-----------|-------|---------|
+| **Iter 1** | Foundation | Schema, API, basic CRUD, install flow |
+| **Iter 2** | Core UI | Dashboard, settings, config panel |
+| **Iter 3** | Integration | Widget, live preview, templates |
+| **Iter 4** | Hardening | Error handling, edge cases, testing |
+
+---
+
+## 6. Пример
+
+```markdown
+## E-01: Settings Management
+### F-01: Settings CRUD API (P0)
+- T-01: Create Settings schema — S — DEV
+- T-02: POST /settings endpoint (create) — S — DEV
+- T-03: PUT /settings/:id endpoint (update) — S — DEV
+- T-04: GET /settings/:id endpoint (read) — XS — DEV
+- T-05: Settings validation (Zod schema) — S — DEV
+
+### F-02: Settings Dashboard UI (P0)
+- T-06: Settings page layout (2-column: config + preview) — M — DEV
+- T-07: General tab (title, subtitle, CTA fields) — M — DEV
+- T-08: Appearance tab (color pickers, font select) — L — DEV
+- T-09: Notifications tab (enable switch, config inputs) — S — DEV
+- T-10: Save flow (button → API → toast) — S — DEV
+
+## E-02: Product Management
+### F-03: Product CRUD API (P0)
+- T-11: Product schema — S — DEV
+- T-12: POST /products endpoint — S — DEV
+- T-13: GET /products (list) endpoint — S — DEV
+- T-14: DELETE /products/:id endpoint — XS — DEV
+
+### F-04: Product Dashboard UI (P0)
+- T-15: Products list (table + empty state) — M — DEV
+- T-16: Create product form (modal) — M — DEV
+- T-17: Delete product (confirm → delete → toast) — S — DEV
+
+## E-03: Public Content
+### F-05: Content Rendering (P0)
+- T-18: Public content endpoint (GET /content/:id) — S — DEV
+- T-19: Content template renderer — L — DEV
+- T-20: Token replacement engine (title, subtitle, colors) — M — DEV
+
+### SP-01: Evaluate External API Integration (P0, time-box: 4h)
+- Research: How to handle external webhook events
+- Output: ADR with chosen approach
+```
+
+---
+
+## 7. Output Template
+
+```markdown
+# Product Backlog: <Project Name>
+
+**PRD:** <reference>
+**Date:** YYYY-MM-DD
+**Author:** Product Manager Agent
+
+## Summary
+| Metric | Count |
+|--------|:-----:|
+| Epics | X |
+| Features | Y |
+| Tasks | Z |
+| Spikes | W |
+| P0 tasks | A |
+| P1 tasks | B |
+| P2 tasks | C |
+
+## Backlog
+
+### E-01: <Epic Name>
+#### F-01: <Feature Name> (P0)
+| Task | Priority | Estimate | Owner | Deps | Status |
+|------|:--------:|:--------:|:-----:|------|:------:|
+| T-01: ... | P0 | S | DEV | — | ☐ |
+| T-02: ... | P0 | M | DEV | T-01 | ☐ |
+
+#### F-02: <Feature Name> (P0)
+...
+
+### E-02: <Epic Name>
+...
+
+## Iterations
+<section 5 format>
+
+## Dependencies Graph
+<list critical path dependencies>
+
+## Spikes
+| ID | Question | Time box | Output | Status |
+|----|---------|:--------:|--------|:------:|
+| SP-01 | ... | 4h | ADR | ☐ |
+
+## Next Step
+→ Transfer to $board for tracking
+```
+
+---
+
+## См. также
+- `$pm_prd` — PRD (input)
+- `$board` — project board (tracks execution)
+- `$handoff` — gate transitions

package/.agents/skills/pm_interview/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: pm_interview
+description: Структурированное интервью/разбор документации — собрать цели, аудиторию, MVP, ограничения, интеграции и критерии успеха, чтобы можно было написать PRD.
+---
+
+# Skill: PM Interview / Discovery
+
+Собрать минимально достаточную информацию для PRD.
+
+**Разделы:**
+1. [Workflow](#1-workflow)
+2. [Question Bank](#2-questions)
+3. [Priority & Assumptions](#3-priority)
+4. [Output Template](#5-output)
+
+---
+
+## 1. Workflow
+
+```
+1. Прочитай то, что уже есть:
+   ├── User brief / описание идеи
+   ├── Существующий код / README
+   └── Предыдущие документы (если есть)
+
+2. Извлеки факты (что уже известно)
+
+3. Определи пробелы (что нужно уточнить)
+   └── Используй Question Bank (section 2)
+
+4. Приоритизируй вопросы:
+   ├── 🔴 Blocking — без ответа нельзя писать PRD
+   ├── 🟠 Important — влияет на PRD, но можно допустить
+   └── 🟡 Nice-to-know — можно отложить
+
+5. Задай вопросы (только blocking + important)
+   └── Остальное → допущения с пометкой ASSUMPTION
+
+6. Сформируй Interview Summary (section 5)
+   └── Передай в → $pm_prd
+```
+
+### Когда НЕ нужен interview
+
+| Ситуация | Действие |
+|----------|---------|
+| User дал детальный brief с ответами на всё | Пропустить → сразу $pm_prd |
+| Итерация над существующим PRD | Минимальный interview (только новые вопросы) |
+| Bugfix / patch | Не нужен |
+
+---
+
+## 2. Question Bank
+
+### A) Продукт и пользователи
+
+| # | Вопрос | Зачем | Priority |
+|---|--------|-------|:--------:|
+| Q-01 | Кто целевые пользователи? | Определяет user stories и UX | 🔴 |
+| Q-02 | Какая главная боль/задача? | Core value proposition | 🔴 |
+| Q-03 | Как пользователь решает это сейчас? | Competitive context | 🟠 |
+| Q-04 | Какие роли и различия в правах? | Auth/ACL scope | 🔴 |
+
+### B) MVP и границы
+
+| # | Вопрос | Зачем | Priority |
+|---|--------|-------|:--------:|
+| Q-05 | Что обязательно в MVP (3-7 пунктов)? | Scope control | 🔴 |
+| Q-06 | Что точно НЕ входит (out-of-scope)? | Prevent scope creep | 🔴 |
+| Q-07 | Какие сценарии самые частые/критичные? | Priority of user flows | 🟠 |
+
+### C) Успех и метрики
+
+| # | Вопрос | Зачем | Priority |
+|---|--------|-------|:--------:|
+| Q-08 | Как поймём что продукт успешен? | Success criteria | 🟠 |
+| Q-09 | Есть ли KPI (скорость, конверсия, retention)? | Measurable goals | 🟡 |
+
+### D) Данные и интеграции
+
+| # | Вопрос | Зачем | Priority |
+|---|--------|-------|:--------:|
+| Q-10 | Какие данные храним? | Data model scope | 🔴 |
+| Q-11 | Нужны ли внешние интеграции? | Architecture dependencies | 🔴 |
+| Q-12 | Есть ли внешние API и ограничения? | API constraints | 🟠 |
+
+### E) NFR (нефункциональные)
+
+| # | Вопрос | Зачем | Priority |
+|---|--------|-------|:--------:|
+| Q-13 | Есть ли требования по безопасности/compliance? | Security scope | 🟠 |
+| Q-14 | Ожидаемая нагрузка? | Scaling strategy | 🟡 |
+| Q-15 | Локализация / языки? | i18n scope | 🟡 |
+
+### F) Технологии и деплой
+
+| # | Вопрос | Зачем | Priority |
+|---|--------|-------|:--------:|
+| Q-16 | Предпочтительный стек? | Tech decisions | 🟠 |
+| Q-17 | Где деплоим? | Infrastructure | 🟠 |
+| Q-18 | Нужна ли админка? | Additional scope | 🟡 |
+
+---
+
+## 3. Priority & Assumptions
+
+### Правило минимизации вопросов
+
+| Ситуация | Действие |
+|----------|---------|
+| Ответ критичен для архитектуры/UX | 🔴 Обязательно спросить |
+| Можно двигаться с безопасным допущением | 🟠 Допустить + пометить ASSUMPTION |
+| Можно отложить до PRD review | 🟡 Добавить в Open Questions |
+
+### Assumption format
+
+```markdown
+**ASSUMPTION-XX:** <Statement>
+- Основание: <Why this is safe to assume>
+- Риск: Low / Medium / High
+- Подтвердить до: <milestone>
+```
+
+---
+
+
+---
+
+## 5. Output Template
+
+```markdown
+# PM Interview Summary
+
+**Date:** YYYY-MM-DD
+**Interviewer:** Product Manager Agent
+**Source:** <user brief / existing docs / conversation>
+
+## Facts (confirmed)
+| # | Fact | Source |
+|---|------|--------|
+| F-01 | ... | User brief |
+| F-02 | ... | README.md |
+
+## Questions & Answers
+| # | Question | Priority | Answer | Status |
+|---|----------|:--------:|--------|:------:|
+| Q-01 | ... | 🔴 | ... | ✅ Answered |
+| Q-05 | ... | 🔴 | ... | ✅ Answered |
+| Q-09 | ... | 🟡 | — | ASSUMED |
+
+## Assumptions
+| ID | Assumption | Risk | Confirm by |
+|----|-----------|:----:|-----------|
+| ASSUMPTION-01 | ... | Low | MVP review |
+
+## Open Questions (deferred)
+| # | Question | Why deferred | Address at |
+|---|----------|-------------|-----------|
+| Q-14 | Expected load? | Not critical for MVP | Pre-launch |
+
+## Next Step
+→ Proceed to $pm_prd
+```
+
+---
+
+## См. также
+- `$pm_prd` — PRD (output of interview)
+- `$pm_backlog` — Backlog decomposition
+- `$ux_discovery` — UX-specific discovery