code-ai-installer 1.3.1 → 1.5.0

package/.agents/observability_plan/SKILL.md

@@ -1,279 +0,0 @@
----
-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. [Пример: Smart Cart Rescue](#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" |
-| `coupon_created` | info | POST /coupons success | couponId, code, appInstanceId | "Coupon created" |
-| `coupon_duplicate` | warn | POST /coupons 409 | code, appInstanceId | "Duplicate coupon code" |
-| `settings_updated` | info | PUT /settings success | appInstanceId, changedFields | "Settings updated" |
-| `install_webhook` | info | Webhook received | appInstanceId, siteUrl | "Processing install webhook" |
-| `embed_script_ok` | info | Embed script success | appInstanceId | "Embed script registered" |
-| `embed_script_fail` | error | Embed script failed | appInstanceId, err | "Failed to embed script" |
-| `widget_served` | info | GET /widget/:id | appInstanceId, durationMs | "Widget config served" |
-| `widget_not_found` | warn | GET /widget/:id 404 | appInstanceId | "App not found for script" |
-| `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 |
-| `widget_requests_total` | Counter | status | Embedded script traffic |
-| `webhook_processed_total` | Counter | type, status | Webhook processing |
-| `embed_script_calls_total` | Counter | status | Embed API calls |
-
-### Latency targets
-
-| Endpoint | p50 | p95 | p99 | Alert threshold (p95) |
-|----------|-----|-----|-----|-----------------------|
-| GET /widget/:id | 10ms | 50ms | 100ms | > 200ms |
-| PUT /settings | 20ms | 100ms | 500ms | > 1000ms |
-| POST /coupons | 20ms | 100ms | 500ms | > 1000ms |
-| POST /webhooks/install | 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** | Embed script fail > 3/hour | 🟠 Warning | Slack | Check Wix API, manual re-embed |
-| **Disk space** | > 85% used | 🟠 Warning | Slack | Clean logs, expand volume |
-| **No traffic** | 0 requests for 10 min (production) | 🟠 Warning | Slack | Check gateway, DNS, Wix status |
-
-### Silence rules
-
-| Condition | Silence |
-|-----------|---------|
-| Deployment in progress | 10 min after deploy |
-| Planned maintenance | Duration of maintenance window |
-| Known Wix 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('[SCR] ...') → 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                   │
-│  Wix API: success/fail ▏ Webhook: rate      │
-└─────────────────────────────────────────────┘
-```
-
----
-
-## 7. Пример: Smart Cart Rescue
-
-```markdown
-# Observability Plan: Smart Cart Rescue
-
-## 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)
-- Widget serve rate + latency
-- Webhook processing rate + success/fail
-
-## Alerts
-- 🔴 Error rate > 5% → immediate
-- 🔴 DB health check fail → immediate
-- 🟠 p95 latency > 2x target → investigation
-- 🟠 Embed script fail > 3/hour → manual re-embed
-
-## UX Error Mapping
-- Dashboard: toast/inline errors with clear messages
-- Widget: silent fail (console.error only)
-```
-
----
-
-## 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/pm_backlog/SKILL.md

@@ -1,250 +0,0 @@
----
-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. [Пример: Smart Cart Rescue](#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 Wix Webhooks |
-
----
-
-## 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. Пример: Smart Cart Rescue
-
-```markdown
-## E-01: Settings Management
-### F-01: Settings CRUD API (P0)
-- T-01: Create Settings Mongoose schema — S — DEV
-- T-02: POST /settings endpoint (create on install) — 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: Design tab (color pickers, font select) — L — DEV
-- T-09: Timer tab (enable switch, min/sec inputs) — S — DEV
-- T-10: Save flow (button → API → toast) — S — DEV
-
-## E-02: Coupon Management
-### F-03: Coupon CRUD API (P0)
-- T-11: Coupon Mongoose schema — S — DEV
-- T-12: POST /coupons endpoint — S — DEV
-- T-13: GET /coupons (list) endpoint — S — DEV
-- T-14: DELETE /coupons/:id endpoint — XS — DEV
-
-### F-04: Coupon Dashboard UI (P0)
-- T-15: Coupons list (table + empty state) — M — DEV
-- T-16: Create coupon form (modal) — M — DEV
-- T-17: Delete coupon (confirm → delete → toast) — S — DEV
-
-## E-03: Widget (Public Popup)
-### F-05: Widget Rendering (P0)
-- T-18: Public widget endpoint (GET /widget/:id) — S — DEV
-- T-19: Glassmorphism template renderer — L — DEV
-- T-20: Token replacement engine (title, subtitle, colors) — M — DEV
-- T-21: Timer countdown logic — M — DEV
-
-### SP-01: Evaluate Wix Webhooks (P0, time-box: 4h)
-- Research: How to handle install/uninstall webhooks
-- 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