@dzhechkov/keysarium 1.1.2 → 1.2.0

package/templates/.claude/skills/feature-adr/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: feature-adr
+description: >
+  9-step feature development pipeline with Complexity Router (S/M/L/XL),
+  ADR-driven architecture decisions, DDD modeling, and multi-agent QE.
+  Triggers on "реализуй фичу", "feature implementation", "добавь функциональность",
+  "implement feature", "/feature-adr".
+trust_tier: 0
+trust_tier_label: "Advisory"
+trust_tier_path: "Run /bto-test to promote to Tier 1"
+---
+
+# Feature ADR — Adaptive Feature Development Pipeline
+
+> 9-шаговый pipeline для разработки фич любой сложности.
+> Complexity Router автоматически определяет масштаб (S/M/L/XL) и пропускает ненужные шаги.
+
+## When To Activate
+
+Trigger on:
+- "реализуй фичу [описание]"
+- "implement feature [description]"
+- "добавь функциональность [описание]"
+- "feature [описание]"
+- `/feature-adr [описание или путь к issue]`
+
+## Architecture
+
+```
+.claude/skills/feature-adr/
+├── SKILL.md                           ← This file (orchestrator)
+├── modules/
+│   ├── 00-complexity-router.md        ← Step 0: S/M/L/XL classification
+│   ├── 01-requirements.md             ← Step 1: Requirements gathering
+│   ├── 02-research.md                 ← Step 2: Analogues & patterns research
+│   ├── 03-adr.md                      ← Step 3: Architecture Decision Records
+│   ├── 04-ddd.md                      ← Step 4: Domain-Driven Design
+│   ├── 05-architecture.md             ← Step 5: Technical architecture
+│   ├── 06-implementation-plan.md      ← Step 6: Task decomposition & ordering
+│   ├── 07-code.md                     ← Step 7: Code generation
+│   └── 08-qe.md                       ← Step 8: Quality Engineering
+├── references/
+│   ├── complexity-matrix.md           ← S/M/L/XL criteria & step activation
+│   ├── adr-template.md                ← ADR document template
+│   ├── c4-template.md                 ← C4 diagram templates
+│   └── qe-checklist.md                ← Quality engineering checklist
+└── examples/
+    └── sample-feature-output.md       ← Example output for M-tier feature
+```
+
+## Pipeline Overview
+
+```
+Step 0        Step 1          Step 2        Step 3       Step 4
+ROUTER   →  REQUIREMENTS  →  RESEARCH  →   ADR    →    DDD
+ (all)        (all)          (L/XL)       (M+)        (L/XL)
+                                            │            │
+                                            └──→ Step 5 ←┘
+                                            ARCHITECTURE
+                                              (M+)
+                                                │
+                                                ↓
+                                           Step 6
+                                         IMPL PLAN
+                                           (all)
+                                              │
+                                              ↓
+                                           Step 7
+                                            CODE
+                                           (all)
+                                              │
+                                              ↓
+                                           Step 8
+                                             QE
+                                           (all)
+```
+
+## Complexity Tiers
+
+| Tier | Scope | Steps | Example |
+|------|-------|-------|---------|
+| **S** | 1-3 files, single domain | 0→1→6→7→8 | Bug fix, config change, small util |
+| **M** | 4-10 files, 1-2 domains | 0→1→3→5(light)→6→7→8 | New API endpoint, UI component |
+| **L** | 11-30 files, 2-4 domains | 0→1→2→3→4→5→6→7→8 | New module, integration |
+| **XL** | 30+ files, cross-cutting | Full DAG with parallelism | New subsystem, major refactor |
+
+See `references/complexity-matrix.md` for detailed classification criteria.
+
+## Step Activation Matrix
+
+```
+Step                    | S | M | L | XL | Model   |
+───────────────────────────────────────────────────────
+0 Complexity Router     | ✓ | ✓ | ✓ | ✓  | haiku   |
+1 Requirements          | ✓ | ✓ | ✓ | ✓  | sonnet  |
+2 Research              | - | - | ✓ | ✓  | sonnet  |
+3 ADR                   | - | ✓ | ✓ | ✓  | opus    |
+4 DDD                   | - | - | ✓ | ✓  | opus    |
+5 Architecture          | - | ✓ | ✓ | ✓  | opus    |
+6 Implementation Plan   | ✓ | ✓ | ✓ | ✓  | sonnet  |
+7 Code                  | ✓ | ✓ | ✓ | ✓  | opus    |
+8 QE                    | ✓ | ✓ | ✓ | ✓  | sonnet  |
+```
+
+## DAG Dependencies
+
+Steps are NOT purely linear. The DAG defines what can run in parallel:
+
+```
+Group 1 (sequential): Step 0 → Step 1
+Group 2 (parallel):   Step 2 ‖ Step 3  (after Step 1)
+Group 3 (parallel):   Step 4 ‖ Step 5  (after Steps 2+3)
+Group 4 (sequential): Step 6 (after Step 5)
+Group 5 (sequential): Step 7 (after Step 6)
+Group 6 (sequential): Step 8 (after Step 7)
+```
+
+For tiers S/M, the DAG collapses to a linear sequence (no parallelism needed).
+
+## Agent Swarm Strategy
+
+### Per-Step Parallelism (L/XL tiers only)
+
+| Step | Agents | Tasks |
+|------|--------|-------|
+| Step 2 | 2 parallel (sonnet) | Codebase patterns ‖ External analogues |
+| Step 3+4 | 2 parallel (opus) | ADR drafting ‖ DDD modeling |
+| Step 7 | N parallel (opus) | One agent per independent module/file |
+| Step 8 | 3 parallel (sonnet) | Unit tests ‖ Integration tests ‖ Code review |
+
+### Cross-Step Parallelism
+
+For L/XL: Steps 2 and 3 run in parallel after Step 1 completes.
+For L/XL: Steps 4 and 5 can overlap if Step 3 finishes before Step 2.
+
+## Execution Protocol
+
+### 1. Load Governance
+```
+Read: .claude/shards/feature-adr.shard.md
+```
+
+### 2. Run Step 0 (Complexity Router)
+```
+Read: modules/00-complexity-router.md
+Read: references/complexity-matrix.md
+→ Output: {COMPLEXITY_TIER}, {ACTIVE_STEPS}, {TIME_BUDGET}
+→ Checkpoint 0
+```
+
+### 3. Execute Active Steps per DAG
+For each active step:
+```
+Read: modules/<step>.md
+Execute protocol
+→ Create artifacts in features/<feature-slug>/
+→ Checkpoint N
+```
+
+### 4. Final Verification
+After Step 8 completes, verify:
+- All mandatory artifacts exist per tier
+- QE checks passed
+- ADR decisions are traceable to code (L/XL)
+
+## Cross-Phase Variables
+
+| Variable | Set In | Used In | Type |
+|----------|--------|---------|------|
+| `{COMPLEXITY_TIER}` | Step 0 | All steps | S/M/L/XL |
+| `{ACTIVE_STEPS}` | Step 0 | Orchestrator | list[int] |
+| `{TIME_BUDGET}` | Step 0 | All steps | dict |
+| `{REQUIREMENTS}` | Step 1 | Steps 2-8 | structured |
+| `{RESEARCH_FINDINGS}` | Step 2 | Steps 3-5 | structured |
+| `{ADR_DECISIONS}` | Step 3 | Steps 4-7 | list[ADR] |
+| `{DOMAIN_MODEL}` | Step 4 | Steps 5-7 | structured |
+| `{ARCHITECTURE}` | Step 5 | Steps 6-7 | structured |
+| `{IMPL_PLAN}` | Step 6 | Step 7 | list[task] |
+| `{QE_RESULTS}` | Step 8 | Final report | structured |
+
+## Output Directory Structure
+
+All artifacts are created in `features/<feature-slug>/`:
+
+```
+features/<feature-slug>/
+├── 00_complexity_assessment.md        ← Always
+├── 01_requirements.md                 ← Always
+├── 02_research.md                     ← L/XL only
+├── 03_adr/                            ← M+ only
+│   ├── 001-<decision>.md
+│   └── ...
+├── 04_domain_model.md                 ← L/XL only
+├── 05_architecture.md                 ← M+ only
+├── 06_implementation_plan.md          ← Always
+├── 07_code_changes/                   ← Always (actual code in repo)
+│   └── change_manifest.md             ← List of modified files
+├── 08_qe_report.md                    ← Always
+├── diagrams/                          ← M+ only
+│   ├── architecture-c4.mermaid
+│   ├── sequence-*.mermaid
+│   └── domain-model.mermaid
+└── README.md                          ← Always (auto-generated summary)
+```
+
+## Promise Tags
+
+| Step | Promise Tag |
+|------|-------------|
+| Step 0 | `<promise>FEATURE_ADR_ROUTED</promise>` |
+| Step 1 | `<promise>FEATURE_ADR_REQUIREMENTS_GATHERED</promise>` |
+| Steps 2-5 | `<promise>FEATURE_ADR_DESIGNED</promise>` |
+| Step 6 | `<promise>FEATURE_ADR_PLANNED</promise>` |
+| Step 7 | `<promise>FEATURE_ADR_IMPLEMENTED</promise>` |
+| Step 8 | `<promise>FEATURE_ADR_VERIFIED</promise>` |
+
+## External Skills (loaded as needed)
+
+| Skill | Used In | Purpose |
+|-------|---------|---------|
+| explore | Step 1 | Requirements clarification |
+| problem-solver-enhanced | Step 3 | Trade-off analysis for ADR decisions |
+| frontend-design | Step 7 | UI implementation (if feature has UI) |
+
+## Anti-Patterns
+
+| Anti-Pattern | Detection | Fix |
+|-------------|-----------|-----|
+| Skip complexity assessment | Jump straight to coding | BLOCK — always run Step 0 |
+| Over-engineer S-tier | Run full pipeline for a config change | Router should classify as S |
+| Under-engineer XL-tier | Skip ADR/DDD for major refactor | Router should classify as XL |
+| ADR without alternatives | Only one option considered | Require ≥2 alternatives per ADR |
+| Architecture without ADR | Diagram before decisions | Step 5 requires Step 3 output |
+| Code without plan | Start coding without Step 6 | BLOCK — plan is mandatory |
+| No QE | Ship without testing | BLOCK — Step 8 is mandatory |
+
+## Checkpoint Format
+
+```
+═══════════════════════════════════════════════════════
+⏸️ STEP N/8: [Step Name] Complete
+<promise>[PROMISE_TAG]</promise>
+Tier: {COMPLEXITY_TIER} | Active Steps: {ACTIVE_STEPS}
+
+[2-3 line summary]
+Artifacts: [list] ✅
+
+• "ок" — next step
+• "углуби [section]" — elaborate
+• "[feedback]" — adjust
+═══════════════════════════════════════════════════════
+```

package/templates/.claude/skills/feature-adr/examples/sample-feature-output.md

@@ -0,0 +1,257 @@
+# Sample Output: M-tier Feature — "Add User Notifications"
+
+> This example shows the expected output structure for a medium-complexity feature.
+
+---
+
+## Step 0: Complexity Assessment
+
+```
+Feature: Add email and in-app notifications for order status changes
+```
+
+| Dimension | Score | Reasoning |
+|-----------|-------|-----------|
+| Files affected | 2 (M) | ~8 files: model, service, controller, templates, tests |
+| Domains touched | 2 (M) | Orders domain + Notifications domain |
+| New integrations | 2 (M) | Email service (SendGrid) |
+| Breaking changes | 1 (S) | No breaking changes |
+| New data models | 2 (M) | Notification entity + preferences |
+| Cross-cutting concerns | 1 (S) | None |
+
+**Total: 10 → Tier M**
+
+Active steps: 0, 1, 3, 5(light), 6, 7, 8
+
+---
+
+## Step 1: Requirements
+
+```markdown
+# Requirements: User Notifications
+
+## Stakeholders
+- End user: receives notifications
+- Product owner: defines notification triggers
+- Ops team: monitors delivery rates
+
+## Functional Requirements
+
+FR-1: Order status notification
+  Priority: MUST
+  Acceptance: Given a user with email notifications enabled,
+              When their order status changes,
+              Then they receive an email within 5 minutes.
+
+FR-2: In-app notification
+  Priority: MUST
+  Acceptance: Given a user is logged in,
+              When a notification is created,
+              Then it appears in the notification bell within 10 seconds.
+
+FR-3: Notification preferences
+  Priority: SHOULD
+  Acceptance: Given a user in settings,
+              When they toggle notification types,
+              Then only enabled types are delivered.
+
+FR-4: Notification history
+  Priority: COULD
+  Acceptance: Given a user in notification center,
+              When they scroll,
+              Then they see paginated notification history.
+
+## Constraints
+- Must use existing SendGrid account
+- Must not exceed 10K emails/day (current plan limit)
+- Must follow existing event-driven architecture
+
+## Scope
+- IN: Order status emails, in-app notifications, preferences
+- OUT: Push notifications (mobile), SMS, marketing emails
+```
+
+---
+
+## Step 3: ADR
+
+```markdown
+# ADR-001: Notification Delivery Strategy
+
+## Status
+Accepted
+
+## Context
+We need to deliver notifications both via email and in-app.
+The question is whether to send synchronously or asynchronously.
+
+## Decision Drivers
+- Order status changes happen in bursts (batch processing)
+- Email delivery latency is acceptable within 5 minutes
+- System should not slow down order processing
+
+## Considered Options
+
+### Option 1: Synchronous delivery
+Send notification during order status update request.
+- ✅ Simple implementation
+- ❌ Slows down order status updates
+- ❌ Email failures block the request
+
+### Option 2: Async via existing job queue
+Publish notification event, worker processes it.
+- ✅ Non-blocking for order processing
+- ✅ Retry on failure
+- ✅ Uses existing Bull queue infrastructure
+- ❌ Slight delay (acceptable per requirements)
+
+## Decision
+We chose **Option 2: Async via job queue** because it matches our existing
+event-driven architecture and meets the 5-minute SLA with room to spare.
+
+## Consequences
+### Positive
+- Order processing unaffected by notification delivery
+- Built-in retry and dead-letter handling
+### Negative
+- Need to monitor queue depth for capacity planning
+```
+
+---
+
+## Step 5: Architecture (Light)
+
+```markdown
+# Architecture: User Notifications
+
+## Component Diagram
+
+​```mermaid
+graph TB
+    subgraph "API Server"
+        OrderService[OrderService]
+        NotifService[NotificationService]
+        NotifController[NotificationController]
+        PrefsController[PreferencesController]
+    end
+
+    subgraph "Workers"
+        EmailWorker[EmailNotificationWorker]
+        InAppWorker[InAppNotificationWorker]
+    end
+
+    OrderService -->|"publish event"| Queue[(Bull Queue)]
+    Queue -->|"consume"| EmailWorker
+    Queue -->|"consume"| InAppWorker
+    EmailWorker -->|"send"| SendGrid[SendGrid API]
+    InAppWorker -->|"write"| DB[(Database)]
+    NotifController -->|"read"| DB
+    PrefsController -->|"read/write"| DB
+​```
+
+## API Endpoints
+- GET /api/notifications — list user notifications (paginated)
+- PATCH /api/notifications/:id/read — mark as read
+- GET /api/preferences/notifications — get preferences
+- PUT /api/preferences/notifications — update preferences
+```
+
+---
+
+## Step 6: Implementation Plan
+
+```markdown
+# Implementation Plan
+
+## Tasks
+
+TASK-1: Create Notification model + migration
+  Files: models/notification.ts, migrations/add-notifications.ts
+  Depends: none
+  Test: Migration runs, model validates
+
+TASK-2: Create NotificationPreference model + migration
+  Files: models/notification-preference.ts, migrations/add-notification-prefs.ts
+  Depends: none
+  Test: Migration runs, defaults created for existing users
+
+TASK-3: Create NotificationService
+  Files: services/notification.service.ts
+  Depends: TASK-1, TASK-2
+  Test: Unit tests for create/read/mark-read/filter-by-prefs
+
+TASK-4: Create notification workers
+  Files: workers/email-notification.worker.ts, workers/in-app-notification.worker.ts
+  Depends: TASK-3
+  Test: Worker processes event, creates notification, sends email mock
+
+TASK-5: Add event publishing to OrderService
+  Files: services/order.service.ts (modify)
+  Depends: TASK-4
+  Test: Order status change publishes notification event
+
+TASK-6: Create API endpoints
+  Files: controllers/notification.controller.ts, controllers/preferences.controller.ts
+  Depends: TASK-3
+  Test: API returns notifications, updates preferences
+
+TASK-7: Write integration tests
+  Files: tests/notifications.integration.test.ts
+  Depends: TASK-4, TASK-5, TASK-6
+  Test: Full flow: order change → event → worker → notification visible via API
+
+## Parallel Groups
+Group 1: TASK-1, TASK-2 (parallel)
+Group 2: TASK-3 (after Group 1)
+Group 3: TASK-4, TASK-5, TASK-6 (parallel, after Group 2)
+Group 4: TASK-7 (after Group 3)
+```
+
+---
+
+## Step 8: QE Report
+
+```markdown
+# QE Report: User Notifications
+
+## Summary
+- Tests: 14/14 (100%)
+- Review findings: 0 🔴, 2 🟡, 1 🔵
+- Requirements: 3/3 MUST passed, 1/1 SHOULD passed
+
+## Review Findings
+🟡 WARNING: NotificationService.create() doesn't validate notification type enum
+🟡 WARNING: Email template uses inline styles instead of project's template engine
+🔵 SUGGESTION: Consider adding index on notifications.user_id + created_at
+
+## Acceptance Criteria
+| Req | Status | Evidence |
+|-----|--------|----------|
+| FR-1 | ✅ PASS | Integration test: order_status_email_notification |
+| FR-2 | ✅ PASS | Integration test: in_app_notification_created |
+| FR-3 | ✅ PASS | Unit test: filters_by_user_preferences |
+| FR-4 | ✅ PASS | API test: paginated_notification_history |
+
+## Verdict
+⚠️ CONDITIONAL APPROVAL — fix 2 warnings before merge
+```
+
+---
+
+## Final Directory Structure
+
+```
+features/add-user-notifications/
+├── 00_complexity_assessment.md
+├── 01_requirements.md
+├── 03_adr/
+│   └── 001-notification-delivery-strategy.md
+├── 05_architecture.md
+├── 06_implementation_plan.md
+├── 07_code_changes/
+│   └── change_manifest.md
+├── 08_qe_report.md
+├── diagrams/
+│   └── architecture-c4.mermaid
+└── README.md
+```

package/templates/.claude/skills/feature-adr/modules/00-complexity-router.md

@@ -0,0 +1,114 @@
+# Step 0: Complexity Router
+
+> Classify the feature into S/M/L/XL tier and determine which pipeline steps to activate.
+
+## When
+
+Always runs first. Takes ~30 seconds. Uses haiku model.
+
+## Input
+
+- Feature description (from user or issue)
+- Current codebase context (project structure, tech stack)
+
+## Protocol
+
+### 1. Analyze Feature Scope
+
+Evaluate the feature against 6 dimensions:
+
+| Dimension | S (1pt) | M (2pt) | L (3pt) | XL (4pt) |
+|-----------|---------|---------|---------|----------|
+| **Files affected** | 1-3 | 4-10 | 11-30 | 30+ |
+| **Domains touched** | 1 | 1-2 | 2-4 | 4+ |
+| **New integrations** | 0 | 0-1 | 1-3 | 3+ |
+| **Breaking changes** | 0 | 0 | 0-2 | 2+ |
+| **New data models** | 0 | 0-1 | 1-3 | 3+ |
+| **Cross-cutting concerns** | 0 | 0-1 | 1-2 | 3+ |
+
+Cross-cutting concerns: auth, logging, caching, i18n, error handling, etc.
+
+### 2. Score and Classify
+
+Sum all dimension scores:
+
+| Total Score | Tier | Label |
+|-------------|------|-------|
+| 6-8 | **S** | Small — localized change |
+| 9-13 | **M** | Medium — bounded feature |
+| 14-19 | **L** | Large — multi-domain feature |
+| 20-24 | **XL** | Extra Large — cross-cutting system change |
+
+### 3. Override Rules
+
+The router may override the score-based classification:
+
+- If **any single dimension = XL (4pt)** → minimum tier is L
+- If **breaking changes > 0** → minimum tier is M
+- If user explicitly requests a tier → use that tier
+- If feature description mentions "refactor", "migration", "redesign" → bias toward L/XL
+
+### 4. Determine Active Steps
+
+Load `references/complexity-matrix.md` for the full matrix. Summary:
+
+| Step | S | M | L | XL |
+|------|---|---|---|-----|
+| 0 Complexity Router | ✓ | ✓ | ✓ | ✓ |
+| 1 Requirements | ✓ light | ✓ | ✓ | ✓ |
+| 2 Research | - | - | ✓ | ✓ |
+| 3 ADR | - | ✓ (1 ADR) | ✓ (N ADRs) | ✓ (N ADRs) |
+| 4 DDD | - | - | ✓ | ✓ |
+| 5 Architecture | - | ✓ light | ✓ | ✓ |
+| 6 Implementation Plan | ✓ inline | ✓ | ✓ | ✓ |
+| 7 Code | ✓ | ✓ | ✓ | ✓ |
+| 8 QE | ✓ smoke | ✓ | ✓ | ✓ full |
+
+### 5. Calculate Time Budget
+
+| Tier | Total Budget | Distribution |
+|------|-------------|--------------|
+| S | 15 min | R:2 P:0 I:10 Q:3 |
+| M | 45 min | R:5 P:10 I:20 Q:10 |
+| L | 2 hours | R:15 P:30 I:45 Q:30 |
+| XL | 4+ hours | R:30 P:60 I:90 Q:60 |
+
+R = Requirements, P = Planning (ADR+DDD+Arch), I = Implementation, Q = QE
+
+## Output
+
+Set the following variables:
+
+```
+{COMPLEXITY_TIER} = S | M | L | XL
+{ACTIVE_STEPS} = [0, 1, 6, 7, 8]  # example for S
+{TIME_BUDGET} = { requirements: 2, planning: 0, implementation: 10, qe: 3 }
+{DIMENSION_SCORES} = { files: 1, domains: 1, integrations: 1, breaking: 1, models: 1, crosscutting: 1 }
+```
+
+Create artifact: `features/<slug>/00_complexity_assessment.md`
+
+## Checkpoint 0 Format
+
+```
+═══════════════════════════════════════════════════════
+⏸️ STEP 0/8: Complexity Router Complete
+<promise>FEATURE_ADR_ROUTED</promise>
+Tier: {COMPLEXITY_TIER} | Active Steps: {ACTIVE_STEPS}
+
+Feature classified as {TIER} based on: {top 2-3 scoring dimensions}
+Pipeline: {ACTIVE_STEPS count} steps, estimated {TIME_BUDGET total}
+
+• "ок" — proceed with this tier
+• "повысь" — bump to next tier
+• "понизь" — drop to lower tier
+═══════════════════════════════════════════════════════
+```
+
+## Quality Gates
+
+- [ ] All 6 dimensions evaluated with explicit reasoning
+- [ ] Override rules checked
+- [ ] Active steps list matches tier definition
+- [ ] Time budget calculated
+- [ ] User confirmed tier before proceeding