@dzhechkov/keysarium 1.1.2 → 1.2.0

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

package/templates/.claude/skills/feature-adr/references/adr-template.md

@@ -0,0 +1,102 @@
+# ADR Template
+
+Use this template for every Architecture Decision Record.
+
+---
+
+```markdown
+# ADR-{NNN}: {Short Title of Decision}
+
+## Status
+
+{Proposed | Accepted | Deprecated | Superseded by ADR-{M}}
+
+## Date
+
+{YYYY-MM-DD}
+
+## Context
+
+{What is the issue that we're seeing that is motivating this decision or change?
+Describe the forces at play — technical, business, political, social.
+Describe the problem space, not the solution.}
+
+## Decision Drivers
+
+- {driver 1: e.g., "Team has no experience with technology X"}
+- {driver 2: e.g., "Feature requires sub-100ms latency"}
+- {driver 3: e.g., "Must integrate with existing auth system"}
+
+## Considered Options
+
+### Option 1: {Name}
+
+{1-2 paragraph description of this option}
+
+- ✅ {Pro 1}
+- ✅ {Pro 2}
+- ❌ {Con 1}
+- ❌ {Con 2}
+
+### Option 2: {Name}
+
+{1-2 paragraph description}
+
+- ✅ {Pro 1}
+- ❌ {Con 1}
+
+### Option 3: {Name} (optional)
+
+{1-2 paragraph description}
+
+- ✅ {Pro 1}
+- ❌ {Con 1}
+
+## Decision Matrix
+
+| Criterion | Weight | Option 1 | Option 2 | Option 3 |
+|-----------|--------|----------|----------|----------|
+| {Criterion 1} | {1-5} | {1-5} | {1-5} | {1-5} |
+| {Criterion 2} | {1-5} | {1-5} | {1-5} | {1-5} |
+| {Criterion 3} | {1-5} | {1-5} | {1-5} | {1-5} |
+| **Weighted Total** | | **{sum}** | **{sum}** | **{sum}** |
+
+## Decision
+
+We chose **{Option N}** because {1-2 sentence rationale linking back to decision drivers}.
+
+## Consequences
+
+### Positive
+- {Positive consequence 1}
+- {Positive consequence 2}
+
+### Negative
+- {Negative consequence 1 — with mitigation strategy}
+
+### Risks
+- {Risk 1} — Mitigation: {how to mitigate}
+- {Risk 2} — Mitigation: {how to mitigate}
+
+## Links
+
+- Requirement: FR-{N}
+- Related: ADR-{M} (if any)
+```
+
+---
+
+## ADR Numbering
+
+- Start from 001 for each feature
+- Use kebab-case slugs: `001-choose-database-engine.md`
+- Keep sequential within a feature, no gaps
+
+## ADR Quality Checklist
+
+- [ ] At least 2 options considered
+- [ ] Every option has both pros and cons
+- [ ] Decision matrix used for non-trivial decisions
+- [ ] Consequences include both positive AND negative
+- [ ] Risks have mitigation strategies
+- [ ] Links to requirements present

package/templates/.claude/skills/feature-adr/references/c4-template.md

@@ -0,0 +1,120 @@
+# C4 Diagram Templates
+
+Reference templates for C4 architecture diagrams in Mermaid format.
+
+---
+
+## Level 1: System Context
+
+```mermaid
+graph TB
+    %% Actors
+    User["👤 User<br/><i>Description of user</i>"]
+    Admin["👤 Admin<br/><i>Description of admin</i>"]
+
+    %% System
+    System["🖥️ Our System<br/><i>What it does</i>"]
+
+    %% External Systems
+    ExtAuth["🔐 Auth Provider<br/><i>OAuth 2.0</i>"]
+    ExtPay["💳 Payment Gateway<br/><i>Stripe/etc</i>"]
+    ExtEmail["📧 Email Service<br/><i>SendGrid/etc</i>"]
+
+    %% Relationships
+    User -->|"Uses"| System
+    Admin -->|"Manages"| System
+    System -->|"Authenticates via"| ExtAuth
+    System -->|"Processes payments via"| ExtPay
+    System -->|"Sends emails via"| ExtEmail
+
+    %% Styling
+    classDef system fill:#1168bd,stroke:#0b4884,color:#fff
+    classDef external fill:#999,stroke:#666,color:#fff
+    classDef person fill:#08427b,stroke:#052e56,color:#fff
+    class System system
+    class ExtAuth,ExtPay,ExtEmail external
+    class User,Admin person
+```
+
+## Level 2: Container
+
+```mermaid
+graph TB
+    subgraph boundary ["System Boundary"]
+        WebApp["🌐 Web Application<br/><i>React / Next.js</i>"]
+        API["⚙️ API Server<br/><i>Node.js / Express</i>"]
+        Worker["🔄 Background Worker<br/><i>Bull / Agenda</i>"]
+        DB[("💾 Database<br/><i>PostgreSQL</i>")]
+        Cache[("⚡ Cache<br/><i>Redis</i>")]
+        Queue["📬 Message Queue<br/><i>Redis / RabbitMQ</i>"]
+    end
+
+    User["👤 User"] -->|"HTTPS"| WebApp
+    WebApp -->|"REST/GraphQL"| API
+    API -->|"SQL"| DB
+    API -->|"Read/Write"| Cache
+    API -->|"Publish"| Queue
+    Queue -->|"Consume"| Worker
+    Worker -->|"SQL"| DB
+```
+
+## Level 3: Component
+
+```mermaid
+graph TB
+    subgraph container ["API Server"]
+        Router["🔀 Router<br/><i>Express Router</i>"]
+        AuthMW["🔐 Auth Middleware<br/><i>JWT validation</i>"]
+        Controller["📋 Controller<br/><i>Request handling</i>"]
+        Validator["✅ Validator<br/><i>Input validation</i>"]
+        Service["⚙️ Service<br/><i>Business logic</i>"]
+        Repository["💾 Repository<br/><i>Data access</i>"]
+        EventBus["📡 Event Bus<br/><i>Domain events</i>"]
+    end
+
+    Router --> AuthMW
+    AuthMW --> Controller
+    Controller --> Validator
+    Controller --> Service
+    Service --> Repository
+    Service --> EventBus
+    Repository --> DB[("Database")]
+    EventBus --> Queue["Message Queue"]
+```
+
+## Sequence Diagram Template
+
+```mermaid
+sequenceDiagram
+    actor User
+    participant FE as Frontend
+    participant API as API Server
+    participant Auth as Auth Service
+    participant DB as Database
+    participant Queue as Message Queue
+
+    User->>FE: Action
+    FE->>API: POST /api/resource
+    API->>Auth: Validate token
+    Auth-->>API: Valid
+
+    API->>API: Validate input
+    API->>DB: INSERT INTO resource
+    DB-->>API: Created
+
+    API->>Queue: Publish event
+    API-->>FE: 201 Created
+    FE-->>User: Success feedback
+
+    Note over Queue: Async processing
+    Queue->>Worker: Process event
+    Worker->>DB: UPDATE status
+```
+
+## Tips
+
+1. **Keep diagrams focused** — one concept per diagram
+2. **Use consistent naming** — match code namespaces
+3. **Show data flow direction** — arrows point from caller to callee
+4. **Label relationships** — what protocol/format
+5. **Highlight the new** — mark new components vs existing