@dzhechkov/keysarium 1.1.2 → 1.2.0

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

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