@dzhechkov/keysarium 1.1.2 → 1.3.0

package/templates/.claude/skills/feature-adr/modules/04-ddd.md

@@ -0,0 +1,114 @@
+# Step 4: Domain-Driven Design
+
+> Model the domain to ensure code structure reflects business concepts.
+
+## When
+
+L/XL tiers only. Can run **in parallel** with Step 5 (Architecture) if Step 3 is complete.
+
+## Model
+
+opus (complex domain reasoning)
+
+## Input
+
+- `{REQUIREMENTS}` from Step 1
+- `{RESEARCH_FINDINGS}` from Step 2
+- `{ADR_DECISIONS}` from Step 3
+- Existing codebase domain structure
+
+## Protocol
+
+### 1. Identify Bounded Contexts
+
+Analyze requirements for natural domain boundaries:
+
+| Signal | Bounded Context |
+|--------|----------------|
+| Different stakeholders | Separate contexts |
+| Different data lifecycles | Separate contexts |
+| Different ubiquitous languages | Separate contexts |
+| Shared data with different semantics | Separate contexts with shared kernel |
+
+For **existing projects**: map new feature to existing bounded contexts first.
+Only propose new contexts when the feature genuinely introduces a new domain.
+
+### 2. Define Ubiquitous Language
+
+For each bounded context involved:
+
+```
+## Context: {Name}
+
+| Term | Definition | NOT to be confused with |
+|------|-----------|------------------------|
+| {Term1} | {Precise definition} | {Common misuse} |
+| {Term2} | {Precise definition} | {Common misuse} |
+```
+
+Verify terms against:
+- Existing codebase naming (Grep for conflicts)
+- Requirement document terminology
+- Stakeholder vocabulary
+
+### 3. Model Aggregates & Entities
+
+```
+Aggregate: {Name}
+├── Root Entity: {Name}
+│   ├── {field}: {type}
+│   └── {field}: {type}
+├── Value Object: {Name}
+│   └── {field}: {type}
+└── Domain Event: {EventName}
+    └── {payload}
+```
+
+Rules:
+- Aggregates are consistency boundaries
+- Entities have identity, Value Objects don't
+- Domain Events signal state changes
+
+### 4. Map Relationships
+
+```mermaid
+graph LR
+    A[Context A] -- Shared Kernel --> B[Context B]
+    A -- Upstream/Downstream --> C[Context C]
+    C -- Anti-Corruption Layer --> D[External System]
+```
+
+Relationship types:
+- **Shared Kernel:** Shared code/models between contexts
+- **Customer-Supplier:** Upstream provides, downstream consumes
+- **Conformist:** Downstream adopts upstream model as-is
+- **Anti-Corruption Layer:** Translate between incompatible models
+- **Open Host Service:** Public API for multiple consumers
+
+### 5. Validate Against Codebase
+
+Check that proposed domain model is compatible with existing code:
+- Do new entities conflict with existing names?
+- Can aggregates be implemented with existing ORM/framework?
+- Do relationships align with existing data access patterns?
+
+## Output
+
+Create `features/<slug>/04_domain_model.md` with:
+- Bounded context map
+- Ubiquitous language glossary
+- Aggregate/Entity/VO definitions
+- Relationship diagram (Mermaid)
+- Mapping to existing codebase structures
+
+Create `features/<slug>/diagrams/domain-model.mermaid`
+
+Set `{DOMAIN_MODEL}` variable.
+
+## Quality Gates
+
+- [ ] All new terms defined in ubiquitous language
+- [ ] No naming conflicts with existing codebase
+- [ ] Aggregates have clear consistency boundaries
+- [ ] Relationships between contexts are typed
+- [ ] Domain model is implementable with current tech stack

package/templates/.claude/skills/feature-adr/modules/05-architecture.md

@@ -0,0 +1,149 @@
+# Step 5: Technical Architecture
+
+> Design the technical architecture using C4 diagrams and sequence flows.
+
+## When
+
+M+ tiers. Depth varies:
+- **M:** Component diagram only (light)
+- **L/XL:** Full C4 (Context + Container + Component) + sequence diagrams
+
+## Model
+
+opus (system design)
+
+## Input
+
+- `{REQUIREMENTS}` from Step 1
+- `{ADR_DECISIONS}` from Step 3
+- `{DOMAIN_MODEL}` from Step 4 (L/XL only)
+- `{RESEARCH_FINDINGS}` from Step 2 (L/XL only)
+
+## Protocol
+
+### 1. C4 Level 1 — System Context (L/XL only)
+
+Show the system in its environment:
+
+```mermaid
+graph TB
+    User[User] --> System[Our System]
+    System --> ExtA[External System A]
+    System --> ExtB[External System B]
+```
+
+Define:
+- Who uses the system? (actors)
+- What external systems does it interact with?
+- What are the trust boundaries?
+
+### 2. C4 Level 2 — Container Diagram (L/XL only)
+
+Show high-level technical building blocks:
+
+```mermaid
+graph TB
+    subgraph System
+        WebApp[Web App<br/>React]
+        API[API Server<br/>Node.js]
+        DB[(Database<br/>PostgreSQL)]
+        Queue[Message Queue<br/>Redis]
+    end
+    WebApp --> API
+    API --> DB
+    API --> Queue
+```
+
+### 3. C4 Level 3 — Component Diagram (M/L/XL)
+
+Show components within the container affected by this feature:
+
+```mermaid
+graph TB
+    subgraph API
+        Controller[FeatureController]
+        Service[FeatureService]
+        Repository[FeatureRepository]
+        Validator[InputValidator]
+    end
+    Controller --> Validator
+    Controller --> Service
+    Service --> Repository
+```
+
+For M-tier: this is the ONLY diagram required.
+
+### 4. Sequence Diagrams (L/XL)
+
+For each main user flow, create a sequence diagram:
+
+```mermaid
+sequenceDiagram
+    actor User
+    User->>Controller: POST /api/feature
+    Controller->>Validator: validate(input)
+    Validator-->>Controller: valid
+    Controller->>Service: createFeature(data)
+    Service->>Repository: save(entity)
+    Repository-->>Service: entity
+    Service-->>Controller: result
+    Controller-->>User: 201 Created
+```
+
+Create at minimum:
+- Happy path flow
+- Main error flow
+- Async flow (if applicable)
+
+### 5. Data Flow & Storage (L/XL)
+
+Document:
+- New tables/collections/schemas
+- Migrations needed
+- Data flow between components
+- Caching strategy (if applicable)
+
+### 6. API Design (if applicable)
+
+For features exposing APIs:
+
+```
+POST /api/v1/{resource}
+  Request: { field1: type, field2: type }
+  Response: { id: string, ...fields }
+  Errors: 400, 401, 404, 422
+
+GET /api/v1/{resource}/:id
+  Response: { ...full resource }
+  Errors: 401, 404
+```
+
+## Output
+
+### M-tier
+Create `features/<slug>/05_architecture.md` with:
+- Component diagram
+- Brief API design (if applicable)
+
+### L/XL-tier
+Create `features/<slug>/05_architecture.md` with:
+- C4 diagrams (all 3 levels)
+- Sequence diagrams
+- Data model changes
+- API design
+
+Create `features/<slug>/diagrams/`:
+- `architecture-c4.mermaid`
+- `sequence-*.mermaid`
+
+Set `{ARCHITECTURE}` variable.
+
+## Quality Gates
+
+- [ ] Component diagram covers all new components
+- [ ] Each component has clear responsibility
+- [ ] ADR decisions are reflected in architecture
+- [ ] Domain model (Step 4) maps to components (L/XL)
+- [ ] Mermaid syntax is valid
+- [ ] No circular dependencies between components
+- [ ] API follows existing project conventions

package/templates/.claude/skills/feature-adr/modules/06-implementation-plan.md

@@ -0,0 +1,129 @@
+# Step 6: Implementation Plan
+
+> Decompose the feature into ordered, estimable tasks with dependencies.
+
+## When
+
+Always runs. Adapts depth by tier:
+- **S:** Inline checklist (3-5 items, no file)
+- **M/L/XL:** Full structured plan document
+
+## Model
+
+sonnet (analytical decomposition)
+
+## Input
+
+- `{REQUIREMENTS}` from Step 1
+- `{ADR_DECISIONS}` from Step 3 (M+)
+- `{DOMAIN_MODEL}` from Step 4 (L/XL)
+- `{ARCHITECTURE}` from Step 5 (M+)
+
+## Protocol
+
+### 1. Decompose into Tasks
+
+Break the feature into atomic tasks. Each task should be:
+- **Independent** — can be reviewed/tested in isolation
+- **Completable** — produces working code (not half-done)
+- **Testable** — has clear done criteria
+
+Task format:
+```
+TASK-{N}: {Title}
+  Description: {What to do}
+  Files: {Files to create/modify}
+  Depends on: TASK-{M} (or none)
+  Test: {How to verify it works}
+```
+
+### 2. Order by Dependencies
+
+Build a dependency graph:
+
+```
+TASK-1: Create data model
+TASK-2: Create repository (depends: TASK-1)
+TASK-3: Create service (depends: TASK-2)
+TASK-4: Create controller (depends: TASK-3)
+TASK-5: Create tests (depends: TASK-2, TASK-3, TASK-4)
+TASK-6: Create migration (depends: TASK-1)
+```
+
+Rules:
+- Tasks with no dependencies go first
+- Parallel-safe tasks are marked for concurrent execution
+- Tests depend on the code they test (but can be written first — TDD)
+
+### 3. Identify Parallel Groups
+
+Group tasks that can be worked on simultaneously:
+
+```
+Group 1: TASK-1, TASK-6  (no dependencies, can parallel)
+Group 2: TASK-2, TASK-3  (depend on Group 1)
+Group 3: TASK-4          (depends on Group 2)
+Group 4: TASK-5          (depends on all)
+```
+
+For L/XL: assign parallel groups to different agents.
+
+### 4. Define Checkpoints
+
+Insert checkpoints between groups:
+- After data model + migrations → verify schema
+- After services → verify business logic
+- After controllers → verify API contract
+- After tests → verify coverage
+
+### 5. Risk Assessment
+
+For each group, identify:
+- What could block this task?
+- What's the fallback if approach doesn't work?
+- Does this task have external dependencies (APIs, packages)?
+
+## Output
+
+### S-tier (inline)
+Inline checklist in conversation:
+```
+Implementation plan:
+- [ ] {task 1}
+- [ ] {task 2}
+- [ ] {task 3}
+```
+
+### M/L/XL
+Create `features/<slug>/06_implementation_plan.md` with:
+- Task list with dependencies
+- Parallel groups
+- Checkpoint schedule
+- Risk assessment (L/XL)
+
+Set `{IMPL_PLAN}` variable.
+
+## Checkpoint Format
+
+```
+═══════════════════════════════════════════════════════
+⏸️ STEP 6/8: Implementation Plan Complete
+<promise>FEATURE_ADR_PLANNED</promise>
+Tier: {COMPLEXITY_TIER}
+
+{N} tasks in {M} parallel groups
+Estimated {K} files to create/modify
+
+• "ок" — start coding
+• "разбей [TASK-N]" — split task further
+• "объедини [TASK-N, TASK-M]" — merge tasks
+═══════════════════════════════════════════════════════
+```
+
+## Quality Gates
+
+- [ ] Every task has clear done criteria
+- [ ] Dependencies form a valid DAG (no cycles)
+- [ ] Parallel groups correctly identified
+- [ ] Each task touches identifiable files
+- [ ] Total file count matches complexity tier expectation

package/templates/.claude/skills/feature-adr/modules/07-code.md

@@ -0,0 +1,126 @@
+# Step 7: Code Generation
+
+> Implement the feature according to the plan, following existing patterns.
+
+## When
+
+Always runs. Adapts by tier:
+- **S:** Single-pass implementation
+- **M:** Sequential task execution with checkpoints
+- **L/XL:** Parallel agents per module/domain
+
+## Model
+
+opus (complex code generation)
+
+## Input
+
+- `{IMPL_PLAN}` from Step 6
+- `{ARCHITECTURE}` from Step 5 (M+)
+- `{ADR_DECISIONS}` from Step 3 (M+)
+- `{DOMAIN_MODEL}` from Step 4 (L/XL)
+- Codebase context (existing patterns, conventions)
+
+## Protocol
+
+### 1. Pre-Implementation Checklist
+
+Before writing any code:
+- [ ] Read existing similar implementations in codebase
+- [ ] Identify naming conventions (files, classes, functions, variables)
+- [ ] Identify import patterns and module structure
+- [ ] Identify error handling patterns
+- [ ] Identify test patterns
+
+### 2. Execute Tasks per Plan
+
+For each task in `{IMPL_PLAN}`:
+
+```
+1. Read existing files that will be modified
+2. Implement the change following existing patterns
+3. Verify: does it match the architecture diagram?
+4. Verify: does it follow ADR decisions?
+5. Mark task complete
+```
+
+### 3. Parallel Execution (L/XL)
+
+For L/XL tiers with independent modules:
+
+| Agent | Scope | Model |
+|-------|-------|-------|
+| Agent 1 | Module A (data layer) | opus |
+| Agent 2 | Module B (service layer) | opus |
+| Agent 3 | Module C (API layer) | opus |
+
+Each agent:
+- Works only on its assigned files
+- Follows the same pre-implementation checklist
+- Reports completion with list of created/modified files
+
+After all agents complete:
+- Verify integration points between modules
+- Fix any interface mismatches
+- Run existing tests to check for regressions
+
+### 4. Code Quality Rules
+
+While implementing:
+
+| Rule | Rationale |
+|------|-----------|
+| Follow existing patterns | Consistency > "better" approaches |
+| No over-engineering | Implement exactly what's planned |
+| No premature abstraction | 3 similar lines > 1 premature helper |
+| Handle errors at boundaries | Don't add internal error handling noise |
+| Write self-documenting code | Clear names > comments |
+| Respect ADR decisions | Don't deviate from chosen options |
+
+### 5. Change Manifest
+
+Track all changes:
+
+```
+## Files Created
+- path/to/new/file.ts — {description}
+
+## Files Modified
+- path/to/existing/file.ts — {what changed}
+
+## Files Deleted
+- path/to/removed/file.ts — {why}
+```
+
+## Output
+
+- Actual code changes in the repository
+- `features/<slug>/07_code_changes/change_manifest.md` — list of all changes
+
+Set `{CODE_CHANGES}` variable with file list.
+
+## Checkpoint Format
+
+```
+═══════════════════════════════════════════════════════
+⏸️ STEP 7/8: Code Implementation Complete
+<promise>FEATURE_ADR_IMPLEMENTED</promise>
+Tier: {COMPLEXITY_TIER}
+
+{N} files created, {M} modified, {K} deleted
+Tasks completed: {completed}/{total}
+
+• "ок" — proceed to QE
+• "ревью [file]" — review specific file
+• "переделай [task]" — redo specific task
+═══════════════════════════════════════════════════════
+```
+
+## Quality Gates
+
+- [ ] All planned tasks implemented
+- [ ] Code follows existing codebase conventions
+- [ ] ADR decisions reflected in code
+- [ ] No unintended side effects on existing functionality
+- [ ] Change manifest is complete and accurate
+- [ ] No TODO/FIXME/HACK left without justification

package/templates/.claude/skills/feature-adr/modules/08-qe.md

@@ -0,0 +1,167 @@
+# Step 8: Quality Engineering
+
+> Verify the implementation through testing, review, and validation.
+
+## When
+
+Always runs. Adapts depth by tier:
+- **S:** Smoke test — compile + existing tests pass
+- **M:** Unit tests + basic code review
+- **L:** Unit + integration tests + thorough review
+- **XL:** Full QE — unit + integration + e2e + security + performance review
+
+## Model
+
+sonnet (analytical evaluation)
+
+## Input
+
+- `{CODE_CHANGES}` from Step 7
+- `{REQUIREMENTS}` from Step 1 (for acceptance criteria)
+- `{ARCHITECTURE}` from Step 5 (for structural validation)
+- `{IMPL_PLAN}` from Step 6 (for completeness check)
+
+## Protocol
+
+### 1. Smoke Tests (All tiers)
+
+```
+- [ ] Code compiles / no syntax errors
+- [ ] Existing test suite passes (no regressions)
+- [ ] Linter passes (if configured)
+- [ ] Type checker passes (if configured)
+```
+
+For S-tier: if all pass, proceed to checkpoint. Done.
+
+### 2. Test Generation (M+)
+
+#### Unit Tests
+For each new/modified module:
+- Test happy path
+- Test edge cases (null, empty, boundary values)
+- Test error paths
+- Follow existing test patterns in codebase
+
+#### Integration Tests (L/XL)
+For each integration point:
+- Test API endpoints with real request/response cycle
+- Test database operations with test database
+- Test message queue interactions
+- Test external service mocks
+
+#### E2E Tests (XL only)
+For critical user flows:
+- Test complete user journey end-to-end
+- Test with realistic data volumes
+- Test failure recovery scenarios
+
+### 3. Code Review (M+)
+
+Adapted from agentic-qe brutal-honesty-review protocol:
+
+#### Review Dimensions
+
+| Dimension | Weight | Questions |
+|-----------|--------|-----------|
+| **Correctness** | 30% | Does it do what requirements say? Edge cases handled? |
+| **Security** | 20% | Injection risks? Auth bypasses? Data exposure? |
+| **Maintainability** | 20% | Readable? Follows patterns? Future-proof? |
+| **Performance** | 15% | N+1 queries? Unnecessary allocations? Missing indexes? |
+| **Consistency** | 15% | Matches codebase conventions? Naming consistent? |
+
+#### Review Process
+
+1. **Read every changed file** completely
+2. **Check against requirements** — is anything missing or extra?
+3. **Check against ADR decisions** — does code match chosen approach?
+4. **Check against architecture** — do components match diagrams?
+5. **Flag issues** with severity:
+   - 🔴 **BLOCKER** — must fix before merge
+   - 🟡 **WARNING** — should fix, but not blocking
+   - 🔵 **SUGGESTION** — nice to have improvement
+
+### 4. Multi-Agent Review Panel (XL only)
+
+For XL features, spawn 3 parallel review agents:
+
+| Agent | Role | Model | Focus |
+|-------|------|-------|-------|
+| Agent 1 | Correctness Reviewer | sonnet | Requirements coverage, logic errors |
+| Agent 2 | Security Reviewer | sonnet | OWASP top 10, auth, data exposure |
+| Agent 3 | Architecture Reviewer | sonnet | Pattern compliance, ADR adherence |
+
+Each agent produces independent findings. Synthesize into single report.
+
+### 5. Acceptance Criteria Validation
+
+For each requirement from Step 1:
+```
+FR-{N}: {requirement}
+  Status: ✅ PASS | ❌ FAIL | ⚠️ PARTIAL
+  Evidence: {how it was verified}
+  Test: {test name or manual verification}
+```
+
+### 6. QE Report
+
+Compile all findings into a structured report:
+
+```markdown
+# QE Report: {feature name}
+
+## Summary
+- Tests: {passed}/{total} ({percentage}%)
+- Review findings: {blockers} 🔴 {warnings} 🟡 {suggestions} 🔵
+- Requirements coverage: {covered}/{total} ({percentage}%)
+
+## Test Results
+### Unit Tests
+{details}
+
+### Integration Tests (L/XL)
+{details}
+
+## Review Findings
+{list of findings with severity}
+
+## Acceptance Criteria
+{FR-N status table}
+
+## Verdict
+✅ READY FOR MERGE | ❌ NEEDS FIXES | ⚠️ CONDITIONAL APPROVAL
+```
+
+## Output
+
+Create `features/<slug>/08_qe_report.md` with full QE report.
+
+Set `{QE_RESULTS}` variable.
+
+## Checkpoint Format
+
+```
+═══════════════════════════════════════════════════════
+⏸️ STEP 8/8: Quality Engineering Complete
+<promise>FEATURE_ADR_VERIFIED</promise>
+Tier: {COMPLEXITY_TIER}
+
+Tests: {passed}/{total} ✅
+Review: {blockers} blockers, {warnings} warnings
+Requirements: {covered}/{total} covered
+
+Verdict: {READY | NEEDS FIXES | CONDITIONAL}
+
+• "ок" — feature complete!
+• "исправь [finding]" — fix specific issue
+• "повтори QE" — re-run full QE
+═══════════════════════════════════════════════════════
+```
+
+## Quality Gates
+
+- [ ] All smoke tests pass
+- [ ] No 🔴 BLOCKER findings remain
+- [ ] All MUST requirements have ✅ PASS status
+- [ ] Test coverage adequate for tier (S: smoke, M: unit, L: unit+integration, XL: full)
+- [ ] QE report created and complete