@dzhechkov/keysarium 1.1.2 → 1.3.0

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

package/templates/.claude/skills/feature-adr/modules/01-requirements.md

@@ -0,0 +1,113 @@
+# Step 1: Requirements Gathering
+
+> Transform vague feature description into structured, actionable requirements.
+
+## When
+
+Always runs. Adapts depth by tier:
+- **S:** 3-5 bullet points, inline (no file)
+- **M/L/XL:** Full structured document
+
+## Model
+
+sonnet (analytical work, not creative)
+
+## Input
+
+- Feature description from user
+- `{COMPLEXITY_TIER}` from Step 0
+- Codebase context (project structure, existing patterns)
+
+## Protocol
+
+### 1. Load Explore Skill (M/L/XL only)
+
+```
+Read: .claude/skills/explore/SKILL.md
+```
+
+Use the explore skill to clarify ambiguous requirements through adaptive questioning.
+For S-tier: skip explore, extract requirements directly from description.
+
+### 2. Identify Stakeholders
+
+| Question | Why |
+|----------|-----|
+| Who is the end user? | Drives UX decisions |
+| Who is the developer consumer? | Drives API design |
+| Who approves delivery? | Defines done criteria |
+
+### 3. Extract Functional Requirements
+
+For each requirement:
+```
+FR-{N}: {Description}
+Priority: MUST | SHOULD | COULD
+Acceptance Criteria:
+  - Given [context], When [action], Then [outcome]
+```
+
+### 4. Extract Non-Functional Requirements (M+ only)
+
+| Category | Questions |
+|----------|-----------|
+| Performance | Latency targets? Throughput? |
+| Security | Auth? Data sensitivity? |
+| Scalability | Expected load? Growth? |
+| Compatibility | Browser/OS/API versions? |
+| Accessibility | WCAG level? |
+
+### 5. Identify Constraints
+
+- Technical: language, framework, existing patterns to follow
+- Business: timeline, budget, compliance
+- Organizational: team capabilities, review process
+
+### 6. Define Scope Boundaries
+
+Explicitly state:
+- **In scope:** What this feature DOES
+- **Out of scope:** What this feature does NOT do (but someone might assume)
+- **Dependencies:** What must exist before this feature works
+- **Dependents:** What will break if this feature changes
+
+## Output
+
+### For S-tier (inline)
+Set `{REQUIREMENTS}` variable with 3-5 bullets. No file created.
+
+### For M/L/XL
+Create `features/<slug>/01_requirements.md` with:
+- Stakeholders
+- Functional requirements (FR-1..N) with acceptance criteria
+- Non-functional requirements (L/XL)
+- Constraints
+- Scope boundaries
+- Open questions (if any remain)
+
+Set `{REQUIREMENTS}` variable with structured data.
+
+## Checkpoint 1 Format
+
+```
+═══════════════════════════════════════════════════════
+⏸️ STEP 1/8: Requirements Complete
+<promise>FEATURE_ADR_REQUIREMENTS_GATHERED</promise>
+Tier: {COMPLEXITY_TIER}
+
+{N} functional requirements identified
+{M} constraints, {K} open questions
+
+• "ок" — proceed
+• "добавь [requirement]" — add more
+• "убери [requirement]" — remove
+═══════════════════════════════════════════════════════
+```
+
+## Quality Gates
+
+- [ ] All requirements have acceptance criteria (M+)
+- [ ] Scope boundaries explicitly defined
+- [ ] No ambiguous terms ("fast", "good", "flexible") without quantification
+- [ ] Dependencies identified
+- [ ] User confirmed requirements before proceeding

package/templates/.claude/skills/feature-adr/modules/02-research.md

@@ -0,0 +1,92 @@
+# Step 2: Research — Analogues & Patterns
+
+> Research existing patterns in codebase and external best practices before designing.
+
+## When
+
+L/XL tiers only. Can run **in parallel** with Step 3 (ADR).
+
+## Model
+
+sonnet (research synthesis)
+
+## Input
+
+- `{REQUIREMENTS}` from Step 1
+- `{COMPLEXITY_TIER}` from Step 0
+- Codebase access
+
+## Protocol
+
+### 1. Codebase Pattern Research (Agent 1 — sonnet)
+
+Search the current codebase for:
+
+| What | How |
+|------|-----|
+| Similar features | Grep for related domain terms, find analogous implementations |
+| Established patterns | How does existing code handle similar problems? |
+| Shared utilities | What existing helpers, services, or abstractions can be reused? |
+| Test patterns | How are similar features tested? |
+| Data access patterns | How do similar features access data? |
+
+Document each finding with file path + line reference.
+
+### 2. External Pattern Research (Agent 2 — sonnet)
+
+Research external analogues:
+
+| What | How |
+|------|-----|
+| Industry patterns | How do similar products solve this? |
+| Framework conventions | What does the framework recommend? |
+| Library options | Are there well-maintained libraries for this? |
+| Anti-patterns | What are known pitfalls to avoid? |
+
+Use `goap-research-ed25519` for verified research if the feature involves:
+- Security-sensitive decisions
+- Compliance requirements
+- Performance-critical paths
+
+### 3. Synthesize Findings
+
+Combine both research streams into:
+
+```
+## Pattern Summary
+1. Codebase has [N] similar implementations using [pattern]
+2. Framework recommends [approach] for this type of feature
+3. Key libraries considered: [list with trade-offs]
+4. Anti-patterns to avoid: [list]
+
+## Recommendation
+Based on research, the recommended approach is [X] because [reasons].
+Alternative considered: [Y], rejected because [reasons].
+```
+
+## Agent Swarm (2 parallel, sonnet)
+
+| Agent | Task | Model |
+|-------|------|-------|
+| Agent 1 | Codebase pattern research | sonnet |
+| Agent 2 | External analogues research | sonnet |
+
+After both complete, synthesize results sequentially.
+
+## Output
+
+Create `features/<slug>/02_research.md` with:
+- Codebase patterns found (with file references)
+- External patterns researched
+- Library evaluation (if applicable)
+- Anti-patterns identified
+- Recommended approach
+
+Set `{RESEARCH_FINDINGS}` variable.
+
+## Quality Gates
+
+- [ ] At least 3 codebase patterns examined
+- [ ] External patterns verified (not hallucinated)
+- [ ] Trade-offs documented for each alternative
+- [ ] Clear recommendation with rationale

package/templates/.claude/skills/feature-adr/modules/03-adr.md

@@ -0,0 +1,135 @@
+# Step 3: Architecture Decision Records
+
+> Document each significant architectural decision with context, alternatives, and rationale.
+
+## When
+
+M+ tiers. Depth varies:
+- **M:** 1 ADR for the main decision
+- **L/XL:** N ADRs for each significant decision
+
+Can run **in parallel** with Step 2 (Research) for L/XL tiers.
+
+## Model
+
+opus (complex reasoning for trade-off analysis)
+
+## Input
+
+- `{REQUIREMENTS}` from Step 1
+- `{RESEARCH_FINDINGS}` from Step 2 (if available — may arrive later in parallel)
+- Codebase context
+
+## Protocol
+
+### 1. Identify Decisions
+
+Scan requirements for decision points:
+
+| Signal | Example |
+|--------|---------|
+| Technology choice | "Which database/queue/framework?" |
+| Pattern choice | "Repository vs. Active Record?" |
+| Integration strategy | "REST vs. GraphQL vs. gRPC?" |
+| Data modeling | "Normalized vs. denormalized?" |
+| Deployment strategy | "Monolith vs. microservice?" |
+| Trade-off | "Consistency vs. availability?" |
+
+For M-tier: pick the SINGLE most impactful decision.
+For L/XL: identify ALL decisions, prioritize by impact.
+
+### 2. Draft ADR per Decision
+
+Use template from `references/adr-template.md`:
+
+```markdown
+# ADR-{NNN}: {Title}
+
+## Status
+Proposed | Accepted | Superseded by ADR-{M}
+
+## Context
+What is the issue that we're seeing that is motivating this decision?
+
+## Decision Drivers
+- {driver 1}
+- {driver 2}
+
+## Considered Options
+1. {Option A} — {1-line summary}
+2. {Option B} — {1-line summary}
+3. {Option C} — {1-line summary}
+
+## Decision
+We chose **{Option X}** because...
+
+## Consequences
+### Positive
+- ...
+### Negative
+- ...
+### Risks
+- ...
+```
+
+### 3. Evaluate Alternatives
+
+For each ADR, evaluate alternatives using a decision matrix:
+
+| Criterion | Weight | Option A | Option B | Option C |
+|-----------|--------|----------|----------|----------|
+| Simplicity | 3 | ⭐⭐⭐ | ⭐⭐ | ⭐ |
+| Performance | 2 | ⭐⭐ | ⭐⭐⭐ | ⭐⭐ |
+| Maintainability | 3 | ⭐⭐ | ⭐⭐ | ⭐⭐⭐ |
+| Team familiarity | 2 | ⭐⭐⭐ | ⭐ | ⭐⭐ |
+
+If decision involves complex trade-offs, load `problem-solver-enhanced` for TRIZ analysis.
+
+### 4. Validate Against Requirements
+
+Each ADR must trace back to specific requirements:
+- Which FR-{N} does this decision support?
+- Does the decision satisfy all relevant NFRs?
+- Does the decision respect constraints?
+
+## Anti-Patterns
+
+| Anti-Pattern | Detection | Fix |
+|-------------|-----------|-----|
+| Only one alternative | Less than 2 options considered | Require ≥2 alternatives |
+| No consequences | Missing positive/negative analysis | BLOCK until filled |
+| Decision without context | Why is unclear | Add context section |
+| Premature optimization | Choosing complex option for hypothetical scale | Prefer simpler option |
+
+## Output
+
+Create `features/<slug>/03_adr/` directory with:
+- `001-{decision-slug}.md` for each ADR
+- Each ADR follows the template
+
+Set `{ADR_DECISIONS}` variable with list of decisions.
+
+## Checkpoint Format
+
+```
+═══════════════════════════════════════════════════════
+⏸️ STEP 3/8: ADR Complete
+Tier: {COMPLEXITY_TIER}
+
+{N} architectural decisions documented:
+1. ADR-001: {title} → chose {option}
+2. ADR-002: {title} → chose {option}
+
+• "ок" — proceed
+• "пересмотри ADR-{N}" — reconsider decision
+• "добавь ADR для [topic]" — add new decision
+═══════════════════════════════════════════════════════
+```
+
+## Quality Gates
+
+- [ ] Every ADR has ≥2 alternatives considered
+- [ ] Every ADR has consequences (positive + negative)
+- [ ] Every ADR traces to requirements
+- [ ] Decision matrix used for non-trivial choices
+- [ ] No premature optimization detected