@dzhechkov/keysarium 1.0.0

package/src/utils.js

@@ -0,0 +1,274 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// ===========================================================================
+// Colors — ANSI escape codes (zero dependencies)
+// ===========================================================================
+
+const supportsColor = process.stdout.isTTY && !process.env.NO_COLOR;
+
+function wrap(code, text) {
+  if (!supportsColor) return text;
+  return `\x1b[${code}m${text}\x1b[0m`;
+}
+
+function green(text)  { return wrap('32', text); }
+function red(text)    { return wrap('31', text); }
+function yellow(text) { return wrap('33', text); }
+function blue(text)   { return wrap('34', text); }
+function cyan(text)   { return wrap('36', text); }
+function bold(text)   { return wrap('1',  text); }
+function dim(text)    { return wrap('2',  text); }
+function gray(text)   { return wrap('90', text); }
+
+// ===========================================================================
+// Logging
+// ===========================================================================
+
+function info(msg)  { console.log(blue('[INFO]') + ' ' + msg); }
+function success(msg) { console.log(green('[OK]') + '   ' + msg); }
+function warn(msg)  { console.log(yellow('[WARN]') + ' ' + msg); }
+function error(msg) { console.log(red('[ERROR]') + ' ' + msg); }
+
+function step(n, total, msg) {
+  console.log(cyan(`[${n}/${total}]`) + ' ' + msg);
+}
+
+// ===========================================================================
+// File operations — all synchronous, Node.js built-ins only
+// ===========================================================================
+
+/**
+ * Copy a directory recursively from src to dest, creating dirs as needed.
+ * If src is a file, copies the single file.
+ */
+function copyDirRecursive(src, dest) {
+  const stat = fs.statSync(src);
+
+  if (stat.isFile()) {
+    ensureDir(path.dirname(dest));
+    fs.copyFileSync(src, dest);
+    return;
+  }
+
+  if (stat.isDirectory()) {
+    ensureDir(dest);
+    const entries = fs.readdirSync(src);
+    for (const entry of entries) {
+      const srcEntry = path.join(src, entry);
+      const destEntry = path.join(dest, entry);
+      copyDirRecursive(srcEntry, destEntry);
+    }
+  }
+}
+
+/**
+ * Returns true if the path exists (file or directory).
+ */
+function fileExists(filePath) {
+  try {
+    fs.accessSync(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read and parse a JSON file. Returns null if file not found or invalid.
+ */
+function readJSON(filePath) {
+  try {
+    const raw = fs.readFileSync(filePath, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write an object as JSON with 2-space indentation.
+ */
+function writeJSON(filePath, data) {
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * Create a directory (and parents) if it does not exist.
+ */
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+/**
+ * Return an array of all file paths relative to `dir`, traversed recursively.
+ */
+function getRelativePaths(dir) {
+  const results = [];
+
+  function walk(current, rel) {
+    const entries = fs.readdirSync(current);
+    for (const entry of entries) {
+      const full = path.join(current, entry);
+      const relPath = rel ? path.join(rel, entry) : entry;
+      const stat = fs.statSync(full);
+      if (stat.isDirectory()) {
+        walk(full, relPath);
+      } else {
+        results.push(relPath);
+      }
+    }
+  }
+
+  if (fileExists(dir) && fs.statSync(dir).isDirectory()) {
+    walk(dir, '');
+  }
+
+  return results;
+}
+
+/**
+ * Compare files between srcDir and destDir.
+ * Returns { added, modified, unchanged, missing }.
+ *   added:     files in src but not in dest
+ *   modified:  files in both but with different content
+ *   unchanged: files in both with identical content
+ *   missing:   files in dest but not in src (would be removed on clean install)
+ */
+function diffFiles(srcDir, destDir) {
+  const srcFiles = new Set(getRelativePaths(srcDir));
+  const destFiles = new Set(getRelativePaths(destDir));
+
+  const added = [];
+  const modified = [];
+  const unchanged = [];
+  const missing = [];
+
+  for (const rel of srcFiles) {
+    if (!destFiles.has(rel)) {
+      added.push(rel);
+    } else {
+      const srcContent = fs.readFileSync(path.join(srcDir, rel));
+      const destContent = fs.readFileSync(path.join(destDir, rel));
+      if (srcContent.equals(destContent)) {
+        unchanged.push(rel);
+      } else {
+        modified.push(rel);
+      }
+    }
+  }
+
+  for (const rel of destFiles) {
+    if (!srcFiles.has(rel)) {
+      missing.push(rel);
+    }
+  }
+
+  return { added, modified, unchanged, missing };
+}
+
+// ===========================================================================
+// Manifest — .keysarium.json management
+// ===========================================================================
+
+const MANIFEST_FILE = '.keysarium.json';
+
+/**
+ * Read the manifest from targetDir. Returns null if not found.
+ */
+function readManifest(targetDir) {
+  return readJSON(path.join(targetDir, MANIFEST_FILE));
+}
+
+/**
+ * Write the manifest to targetDir.
+ */
+function writeManifest(targetDir, data) {
+  writeJSON(path.join(targetDir, MANIFEST_FILE), data);
+}
+
+/**
+ * Create a fresh manifest object.
+ */
+function createManifest(version, components, files) {
+  return {
+    version: version,
+    installedAt: new Date().toISOString(),
+    components: components,
+    files: files,
+  };
+}
+
+// ===========================================================================
+// Templates path
+// ===========================================================================
+
+/**
+ * Returns the absolute path to the templates/ directory inside the package.
+ */
+function getTemplatesDir() {
+  return path.join(__dirname, '..', 'templates');
+}
+
+// ===========================================================================
+// Component definitions
+// ===========================================================================
+
+const COMPONENTS = {
+  skills:    { src: '.claude/skills',         label: 'Skills (6 skill packs)',           group: 'core' },
+  commands:  { src: '.claude/commands',        label: 'Commands (11 slash commands)',      group: 'core' },
+  rules:     { src: '.claude/rules',           label: 'Rules (7 auto-loaded rules)',      group: 'core' },
+  agents:    { src: '.claude/agents',          label: 'Agent templates (5 swarm configs)', group: 'core' },
+  hooks:     { src: '.claude/settings.json',   label: 'Hooks configuration',              group: 'core', isFile: true },
+  lib:       { src: 'lib',                     label: 'Library modules (4 modules)',       group: 'extended' },
+  docs:      { src: 'docs',                    label: 'Documentation (6 guides)',          group: 'docs' },
+  claude_md: { src: 'CLAUDE.md',               label: 'Master instructions',              group: 'core', isFile: true },
+  harvest:   { src: 'TOOLKIT_HARVEST.md',      label: 'Knowledge harvest tracker',        group: 'core', isFile: true },
+};
+
+// ===========================================================================
+// Exports
+// ===========================================================================
+
+module.exports = {
+  // Colors
+  green,
+  red,
+  yellow,
+  blue,
+  cyan,
+  bold,
+  dim,
+  gray,
+
+  // Logging
+  info,
+  success,
+  warn,
+  error,
+  step,
+
+  // File operations
+  copyDirRecursive,
+  fileExists,
+  readJSON,
+  writeJSON,
+  ensureDir,
+  getRelativePaths,
+  diffFiles,
+
+  // Manifest
+  MANIFEST_FILE,
+  readManifest,
+  writeManifest,
+  createManifest,
+
+  // Templates
+  getTemplatesDir,
+
+  // Components
+  COMPONENTS,
+};

package/templates/.claude/agents/cjm-variant-worker.md

@@ -0,0 +1,60 @@
+# Agent Template: CJM Variant Worker
+
+## Purpose
+Генерирует один вариант CJM (Customer Journey Map) в рамках Phase 2.5.
+Используется как один из 3 параллельных агентов.
+
+## Spawning Pattern
+```
+Agent(
+  subagent_type="general-purpose",
+  description="Phase 2.5 CJM Variant [X]",
+  prompt="""
+    Read the skills:
+    - .claude/skills/reverse-engineering-unicorn/modules/025-cjm-prototype.md
+    - .claude/skills/frontend-design/SKILL.md
+
+    Read the context:
+    - researches/<slug>/00_product_discovery.md
+    - researches/<slug>/01_case_brief.md
+    - researches/<slug>/02_research_findings.md
+
+    Generate CJM Variant [X]: [VARIANT_NAME]
+
+    Approach: [APPROACH_DESCRIPTION]
+    - Entry point: [pull/push/hybrid]
+    - AI autonomy: [advisor/executor/partner]
+    - Target segment: [user segment]
+
+    Deliverable: Return a JSON-like structure:
+    {
+      name: "[variant name]",
+      emoji: "[emoji]",
+      trigger: { title, scenario, metric },
+      input: { title, fields, scenario },
+      processing: { title, steps, duration },
+      result: { title, format, scenario },
+      review: { title, hitl, scenario },
+      action: { title, integration, scenario }
+    }
+
+    Plus a brief comparison row for the variant table.
+  """
+)
+```
+
+## Variants
+1. **Agent A** — Variant A: основной подход (наиболее очевидный)
+2. **Agent B** — Variants B + C: альтернативные подходы
+3. **Agent C** — Trend Research для Variant D (Future-Ready)
+
+## Agent C Special Instructions
+Agent C uses GOAP research (`.claude/skills/goap-research-ed25519/SKILL.md`) to:
+1. Research 5 trend categories (AI Evolution, UX Shifts, Infra, Regulatory, Competitive)
+2. Create Trend Brief
+3. Synthesize Variant D based on trends + best of A/B/C
+
+## Synthesis
+Orchestrator combines all variants into:
+- `02.5_trend_brief.md` (from Agent C)
+- `prototype/cjm-prototype.jsx` (unified React component with all 4 variants)

package/templates/.claude/agents/discovery-worker.md

@@ -0,0 +1,45 @@
+# Agent Template: Discovery Worker
+
+## Purpose
+Выполняет часть Product Discovery в рамках Phase 0.
+Используется как один из 2 параллельных агентов.
+
+## Spawning Pattern
+```
+Agent(
+  subagent_type="general-purpose",
+  description="Phase 0 [direction]",
+  prompt="""
+    Read the skill: .claude/skills/reverse-engineering-unicorn/SKILL.md
+    Read module: .claude/skills/reverse-engineering-unicorn/modules/02-product-customers.md
+
+    Case description: [CASE_TEXT]
+    Domain: [DOMAIN]
+
+    Direction: [DIRECTION]
+
+    [DIRECTION-SPECIFIC INSTRUCTIONS]
+
+    Deliverable: Return markdown sections as specified.
+  """
+)
+```
+
+## Agents
+
+### Agent 1: JTBD + User Analysis
+Sections to generate:
+- A. Current Process (As-Is One-Liner)
+- B. User Segments (JTBD table: 3+ segments)
+- C. Voice of Customer (hate/value)
+- D. Aha Moment for AI solution
+- H. Adoption Strategy (Pilot → Rollout → Scale)
+
+### Agent 2: Market + Business Analysis
+Sections to generate:
+- E. Why AI, Why Now? (4 factors table)
+- F. Competitive Analysis (3+ competitors)
+- G. Business Case (ROI, payback period)
+
+## Synthesis
+Orchestrator merges both agents' outputs into `00_product_discovery.md`.

package/templates/.claude/agents/parallel-research-orchestrator.md

@@ -0,0 +1,70 @@
+# Agent Template: Parallel Research Orchestrator
+
+## Purpose
+Оркестратор для запуска нескольких исследований параллельно.
+Каждое исследование выполняется изолированным агентом.
+
+## Spawning Pattern
+```
+# For each case in the parallel-research input:
+Agent(
+  subagent_type="general-purpose",
+  description="Research: [case_name]",
+  prompt="""
+    You are conducting Phase 0 (Product Discovery) for a case study.
+
+    Read the skill: .claude/skills/reverse-engineering-unicorn/SKILL.md
+
+    Case: [CASE_DESCRIPTION]
+    Working directory: researches/[SLUG]/
+
+    Create the following structure:
+    1. researches/[SLUG]/prototype/ (directory)
+    2. researches/[SLUG]/diagrams/ (directory)
+    3. researches/[SLUG]/README.md (with case metadata)
+    4. researches/[SLUG]/00_product_discovery.md (full Phase 0 output)
+
+    Follow the Product Discovery template from the skill.
+    Use PARANOID mode for any factual claims.
+
+    After completion, provide a 3-line summary:
+    - Key user segments found
+    - Main competitive differentiator
+    - Estimated ROI
+  """
+)
+```
+
+## Orchestration Flow
+
+```
+1. Parse input: split by "|" separator
+2. For each case:
+   a. Generate slug (snake_case, latin)
+   b. Create directory structure
+   c. Spawn isolated agent
+3. Wait for all agents to complete
+4. Generate summary table
+5. Present to user for next steps
+```
+
+## Limits
+- Maximum 4 parallel cases (Claude Code context/cost optimization)
+- Each agent is independent — no shared state
+- If one agent fails, others continue
+
+## Post-Completion
+```
+═══════════════════════════════════════════════════════
+✅ Parallel Discovery Complete
+
+| # | Case | Directory | Segments | ROI | Status |
+|---|------|-----------|----------|-----|--------|
+| 1 | [name] | researches/[slug]/ | [N] | [X] руб/мес | ✅ |
+| 2 | [name] | researches/[slug]/ | [N] | [X] руб/мес | ✅ |
+
+Next steps:
+  /casarium researches/[slug1]/ — continue case 1
+  /casarium researches/[slug2]/ — continue case 2
+═══════════════════════════════════════════════════════
+```

package/templates/.claude/agents/presentation-worker.md

@@ -0,0 +1,55 @@
+# Agent Template: Presentation Worker
+
+## Purpose
+Генерирует один из компонентов презентации в рамках Phase 5.
+Используется как один из 3 параллельных агентов.
+
+## Spawning Pattern
+```
+Agent(
+  subagent_type="general-purpose",
+  description="Phase 5 [component]",
+  prompt="""
+    Read the skill: .claude/skills/presentation-storyteller/SKILL.md
+
+    Read ALL prior artifacts for full context:
+    - researches/<slug>/00_product_discovery.md
+    - researches/<slug>/01_case_brief.md
+    - researches/<slug>/02_research_findings.md
+    - researches/<slug>/02.5_trend_brief.md
+    - researches/<slug>/03_solution_strategy.md
+    - researches/<slug>/04_architecture.md
+
+    Component to generate: [COMPONENT]
+
+    [COMPONENT-SPECIFIC INSTRUCTIONS]
+
+    Write the result to: researches/<slug>/[FILENAME]
+  """
+)
+```
+
+## Components (spawn one agent per component)
+
+### Agent 1: Presentation Content
+- File: `05_presentation_content.md`
+- 10-12 slides with structure: Title, Problem, Question+Answer, Concept, User Flow, AI Pipeline, Data, Security, Metrics+ROI, Roadmap, Team+CTA, Q&A
+- Each slide: title, key message, visual description, data points
+
+### Agent 2: Speaker Script
+- File: `06_speaker_script.md`
+- For each slide: HOOK (question/fact), CONTENT (30-60 sec), BRIDGE (transition), TONE, KEY MOMENT
+- Total time: 7-10 minutes
+- Storytelling arc: Problem → Journey → Solution → Impact
+
+### Agent 3: Q&A + Executive Summary
+- Files: `07_qa_preparation.md` + `08_executive_summary.md`
+- Q&A: 7+ typical jury questions with 30-sec answers and supporting data
+- Executive Summary: 1-page summary (Problem, Solution, Architecture, Metrics, Roadmap, Verification)
+- Executive Summary is MANDATORY — never skip
+
+## Synthesis
+Orchestrator reviews all 3 outputs for:
+- Consistency of narrative across presentation, script, and Q&A
+- No contradictions between slides and speaker notes
+- Executive summary accurately reflects the full solution

package/templates/.claude/agents/research-worker.md

@@ -0,0 +1,43 @@
+# Agent Template: Research Worker
+
+## Purpose
+Выполняет research по одному направлению в рамках Phase 2 (Research).
+Используется как один из 3 параллельных агентов.
+
+## Spawning Pattern
+```
+Agent(
+  subagent_type="general-purpose",
+  description="Phase 2 [direction] research",
+  prompt="""
+    Read the skill: .claude/skills/goap-research-ed25519/SKILL.md
+    Read the case context: researches/<slug>/00_product_discovery.md
+    Read the case brief: researches/<slug>/01_case_brief.md
+
+    Research direction: [DIRECTION]
+    Mode: PARANOID (confidence threshold 0.99)
+
+    Deliverable: Return a markdown section with:
+    ## [Direction Title]
+    ### Findings
+    | Finding | Source | Verified |
+    |---------|--------|----------|
+    ### Key Insights
+    - [insight 1]
+    - [insight 2]
+    ### Recommendations
+    - [recommendation with justification]
+
+    IMPORTANT: Every claim must have a verifiable source.
+    Mark unverifiable claims as [UNVERIFIED].
+  """
+)
+```
+
+## Directions (spawn one agent per direction)
+1. **Analogues + Metrics** — кто решал, какие результаты
+2. **Technologies + Anti-patterns** — стек, что не работает
+3. **Regulations + Market Data** — требования, рыночные данные
+
+## Synthesis
+After all 3 agents complete, the orchestrator merges results into `02_research_findings.md`.

package/templates/.claude/commands/architecture-phase.md

@@ -0,0 +1,37 @@
+# Phase 4: Architecture — Техническая архитектура
+
+## Использование
+```
+/architecture-phase [путь к директории исследования]
+```
+
+## Аргумент
+$ARGUMENTS
+
+## Действия
+
+1. **Прочитай Phase 0-3** для полного контекста
+2. **Спроектируй архитектуру:**
+   - Архитектурная диаграмма (Mermaid C4)
+   - Компоненты решения (технология, назначение, обоснование)
+   - AI Models & Pipeline (задача, тип, конкретная модель)
+   - Data Architecture (источники, ETL, storage, Vector DB)
+   - Интеграции (система, протокол)
+   - Security & Compliance (контур, RBAC, аудит, регуляторика)
+   - Scalability (latency, throughput, масштабирование)
+   - MVP Scope
+
+3. **Обязательные диаграммы (минимум 2):**
+   - `architecture-c4.mermaid` — C4 Context
+   - `sequence-main-flow.mermaid` — Sequence diagram ключевого flow
+
+4. **Создай файлы:**
+   - `04_architecture.md`
+   - `diagrams/architecture-c4.mermaid`
+   - `diagrams/sequence-main-flow.mermaid`
+5. **Покажи Checkpoint 4**
+
+## Domain-specific правила
+- **Банк:** on-premise LLM, ФЗ-152, ЦБ, ФСТЭК, GigaChat/YandexGPT
+- **Ритейл:** Latency < 200ms, A/B тестирование
+- **Enterprise:** Change Management, Legacy интеграции, SLA