@dzhechkov/keysarium 1.0.0

package/README.md

@@ -0,0 +1,289 @@
+# @dzhechko/keysarium
+
+**AI Case Research Toolkit for Claude Code**
+
+Full 7-phase pipeline for AI case studies, hackathons, and casariums. Provides skills, commands, rules, agent templates, and hooks for [Claude Code](https://docs.anthropic.com/en/docs/claude-code).
+
+---
+
+## Quick Start
+
+```bash
+# One-command install via npx (no global install needed)
+npx @dzhechko/keysarium
+
+# Or install globally
+npm install -g @dzhechko/keysarium
+keysarium init
+
+# Or without npm (standalone)
+curl -fsSL https://raw.githubusercontent.com/dzhechko/product-keysarium-2026/main/packages/dz-keysarium/install.sh | bash
+```
+
+After installation, open Claude Code in your project directory and start using slash commands right away.
+
+---
+
+## What You Get
+
+| Component | Count | Description |
+|-----------|-------|-------------|
+| **Skills** | 6 | `explore`, `frontend-design`, `goap-research`, `presentation-storyteller`, `problem-solver`, `reverse-engineering` |
+| **Commands** | 11 | `/casarium`, `/new-research`, `/parallel-research`, `/discovery`, `/explore-case`, `/research`, `/cjm-prototype`, `/solve`, `/architecture-phase`, `/presentation`, `/harvest` |
+| **Rules** | 7 | `research-quality`, `checkpoint-protocol`, `agent-swarm`, `domain-specific`, `anti-patterns`, `file-conventions`, `modular-reuse` |
+| **Agent Templates** | 5 | `discovery-worker`, `research-worker`, `cjm-variant-worker`, `presentation-worker`, `parallel-research-orchestrator` |
+| **Hooks** | 3 | PreToolUse validation, PostToolUse notifications, audit logging |
+| **Library** | 4 | `phase-utils`, `agent-patterns`, `skill-loader`, `domain-templates` |
+| **Documentation** | 6 | Deployment, admin, user guide, infrastructure, architecture, flows |
+
+Everything is installed into your project's `.claude/` directory and works natively with Claude Code.
+
+---
+
+## 7-Phase Pipeline
+
+```
+Phase 0     Phase 1     Phase 2     Phase 2.5      Phase 3     Phase 4         Phase 5
+DISCOVERY   EXPLORE     RESEARCH    CJM PROTO      SOLVE       ARCHITECTURE    PRESENTATION
+  15%         5%          15%         10%            15%          15%             20%
+```
+
+| Phase | Command | What It Does |
+|-------|---------|--------------|
+| **Phase 0 -- Discovery** | `/discovery` | Deep-dive into the product/company: JTBD analysis, competitor landscape, ROI estimation. Powered by the `reverse-engineering` skill. |
+| **Phase 1 -- Explore** | `/explore-case` | Adaptive clarification of the case brief. Asks the right questions, structures ambiguity into actionable scope. |
+| **Phase 2 -- Research** | `/research` | Paranoid-mode research: analogues, technologies, regulations. Every claim must have a verifiable source. |
+| **Phase 2.5 -- CJM Prototype** | `/cjm-prototype` | Customer Journey Map prototyping with multiple variants. Generates a working React prototype. **Mandatory -- never skip this phase.** |
+| **Phase 3 -- Solve** | `/solve` | Solution strategy using TRIZ + Game Theory. Produces process diagrams (as-is / to-be). |
+| **Phase 4 -- Architecture** | `/architecture-phase` | Technical architecture: C4 diagrams, sequence flows, component design, integration plan. |
+| **Phase 5 -- Presentation** | `/presentation` | Storytelling-driven presentation, speaker script, Q&A preparation, and executive summary. |
+
+Each phase produces concrete artifacts (Markdown documents, Mermaid diagrams, JSX prototypes) stored in `researches/<case-slug>/`.
+
+---
+
+## CLI Commands
+
+```bash
+npx @dzhechko/keysarium                    # Full install (interactive, same as init)
+npx @dzhechko/keysarium init               # Install all components
+npx @dzhechko/keysarium init --minimal     # Only .claude/ (no docs, no lib)
+npx @dzhechko/keysarium init --with-docs   # Include documentation
+npx @dzhechko/keysarium init --force       # Overwrite existing files
+npx @dzhechko/keysarium init --dry-run     # Preview without making changes
+npx @dzhechko/keysarium update             # Update to latest version
+npx @dzhechko/keysarium remove             # Clean uninstall
+npx @dzhechko/keysarium list               # Show installed components
+npx @dzhechko/keysarium doctor             # Health check
+```
+
+Flags can be combined:
+
+```bash
+npx @dzhechko/keysarium init --minimal --force --dry-run
+```
+
+---
+
+## Usage After Install
+
+### Full Pipeline
+
+```bash
+# Open Claude Code in your project
+claude
+
+# Start a full case study (runs all 7 phases with checkpoints)
+/casarium Analyze how AI can automate customer support in banking
+```
+
+### Individual Phases
+
+```bash
+# Product discovery
+/discovery Analyze Tinkoff Bank
+
+# Case exploration
+/explore-case banking customer support automation
+
+# Research phase
+/research AI-powered document processing in insurance
+
+# CJM prototyping
+/cjm-prototype mobile banking onboarding flow
+
+# Solution design
+/solve reduce customer churn using predictive analytics
+```
+
+### Multi-Case Research
+
+```bash
+# Run multiple cases in parallel
+/parallel-research banking automation | retail personalization | healthcare triage
+
+# Create a new isolated research
+/new-research smart-warehouse-logistics
+
+# Extract learnings after a project
+/harvest researches/bank_kc_automation/
+/harvest all
+```
+
+### Example: Russian-Language Case (bilingual support)
+
+```bash
+/casarium Как AI может автоматизировать процесс обработки обращений клиентов в банке, сократив время ответа с 4 часов до 15 минут?
+```
+
+The toolkit processes cases in any language and adapts domain rules accordingly.
+
+---
+
+## Domain Support
+
+The toolkit automatically detects the domain from the case description and applies domain-specific rules:
+
+### Banking / FinTech
+- On-premise LLM deployment (GigaChat, YandexGPT, open-source models)
+- Regulatory compliance: FZ-152, Central Bank requirements, FSTEC
+- Human-in-the-Loop mandatory for decision-making
+- Data never leaves the security perimeter
+- Visual palette: Blue / Navy / Silver
+
+### Retail / E-commerce
+- Latency budget: < 200ms for real-time recommendations
+- A/B testing as primary validation method
+- Personalization vs. privacy balance (GDPR / FZ-152)
+- Seasonality and cold-start handling
+- Visual palette: Amber / Orange
+
+### Enterprise / B2B
+- Change management strategy (people resist AI)
+- Legacy system integration planning
+- SLA and fault tolerance definitions
+- ROI expressed in FTE / hours saved
+- Visual palette: Teal / Indigo
+
+### Healthcare
+- HITL mandatory for all clinical decisions
+- Medical device regulations (FZ-323)
+- AI explainability requirements
+- Patient data isolation (FZ-152 + medical specifics)
+
+---
+
+## Agent Swarm
+
+The toolkit leverages Claude Code's agent capabilities for parallel execution, significantly reducing research time:
+
+| Phase | Parallel Agents | Tasks |
+|-------|-----------------|-------|
+| **Phase 0** | 2 agents | JTBD analysis \|\| Competitors + ROI |
+| **Phase 2** | 3 agents | Analogues \|\| Technologies \|\| Regulations |
+| **Phase 2.5** | 3 agents | CJM Variant A \|\| Variant B+C \|\| Trend Research D |
+| **Phase 5** | 3 agents | Presentation \|\| Speaker Script \|\| Q&A + Executive Summary |
+
+Cross-case parallelism is also supported:
+
+```bash
+# Runs Phase 0 for up to 4 cases simultaneously
+/parallel-research case1 | case2 | case3 | case4
+```
+
+Each research is fully isolated in its own `researches/<slug>/` directory.
+
+---
+
+## Research Artifacts
+
+Every completed research produces a structured set of files:
+
+```
+researches/<case-slug>/
+├── 00_product_discovery.md          # Phase 0 output
+├── 01_case_brief.md                 # Phase 1 output
+├── 02_research_findings.md          # Phase 2 output
+├── 02.5_trend_brief.md              # Phase 2.5 output
+├── 03_solution_strategy.md          # Phase 3 output
+├── 04_architecture.md               # Phase 4 output
+├── 05_presentation_content.md       # Phase 5 output
+├── 06_speaker_script.md             # Phase 5 output
+├── 07_qa_preparation.md             # Phase 5 output
+├── 08_executive_summary.md          # Phase 5 output (mandatory)
+├── prototype/
+│   └── cjm-prototype.jsx           # Phase 2.5 React prototype
+├── diagrams/
+│   ├── architecture-c4.mermaid
+│   ├── sequence-main-flow.mermaid
+│   ├── process-as-is.mermaid
+│   └── process-to-be.mermaid
+└── README.md
+```
+
+---
+
+## Extending the Toolkit
+
+### Add a Custom Skill
+
+Create a new directory under `.claude/skills/`:
+
+```
+.claude/skills/my-custom-skill/
+├── SKILL.md          # Skill instructions (loaded by phases)
+└── examples/         # Reference materials (optional)
+```
+
+### Add a Custom Command
+
+Create a new file under `.claude/commands/`:
+
+```
+.claude/commands/my-command.md
+```
+
+Commands follow a standard pattern: load required skills, execute logic, produce artifacts, display a checkpoint.
+
+### Add a Custom Rule
+
+Create a new file under `.claude/rules/`:
+
+```
+.claude/rules/my-rule.md
+```
+
+Rules are automatically loaded by Claude Code and enforced across all phases.
+
+### Knowledge Harvesting
+
+After completing research, extract reusable patterns:
+
+```bash
+/harvest researches/<slug>/     # Harvest from one research
+/harvest all                    # Harvest from all researches
+```
+
+The harvester reviews completed projects, identifies universal patterns, decontextualizes them, and updates `TOOLKIT_HARVEST.md`.
+
+---
+
+## Requirements
+
+- **Claude Code CLI** -- installed and configured ([installation guide](https://docs.anthropic.com/en/docs/claude-code))
+- **Node.js >= 16.0.0** -- required for the npm install method
+- **Git** -- required for the standalone install method
+
+---
+
+## License
+
+[MIT](https://opensource.org/licenses/MIT)
+
+---
+
+## Links
+
+- **GitHub:** [https://github.com/dzhechko/product-keysarium-2026](https://github.com/dzhechko/product-keysarium-2026)
+- **Issues:** [https://github.com/dzhechko/product-keysarium-2026/issues](https://github.com/dzhechko/product-keysarium-2026/issues)
+- **npm:** [https://www.npmjs.com/package/@dzhechko/keysarium](https://www.npmjs.com/package/@dzhechko/keysarium)

package/bin/cli.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+'use strict';
+
+require('../src/cli.js');

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@dzhechkov/keysarium",
+  "version": "1.0.0",
+  "description": "AI Case Research Toolkit for Claude Code — full 7-phase pipeline for AI case studies, hackathons, and casariums",
+  "main": "src/cli.js",
+  "bin": {
+    "keysarium": "./bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/"
+  ],
+  "scripts": {
+    "test": "node bin/cli.js doctor",
+    "prepublishOnly": "node scripts/sync-templates.js"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai",
+    "research",
+    "casarium",
+    "hackathon",
+    "skills",
+    "pipeline",
+    "keysarium",
+    "product-research"
+  ],
+  "author": "dzhechko",
+  "license": "MIT",
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dzhechko/product-keysarium-2026"
+  },
+  "homepage": "https://github.com/dzhechko/product-keysarium-2026#readme",
+  "bugs": {
+    "url": "https://github.com/dzhechko/product-keysarium-2026/issues"
+  }
+}

package/src/cli.js

@@ -0,0 +1,157 @@
+'use strict';
+
+const path = require('path');
+const { bold, cyan, dim, green, yellow, red, info, error } = require('./utils');
+
+// ---------------------------------------------------------------------------
+// Banner
+// ---------------------------------------------------------------------------
+function showBanner() {
+  console.log('');
+  console.log(cyan('╔══════════════════════════════════════════════════════╗'));
+  console.log(cyan('║') + bold('        \uD83D\uDD2C DZ-KEYSARIUM — AI Research Toolkit        ') + cyan('║'));
+  console.log(cyan('║') + '     Full 7-phase pipeline for Claude Code           ' + cyan('║'));
+  console.log(cyan('╚══════════════════════════════════════════════════════╝'));
+  console.log('');
+}
+
+// ---------------------------------------------------------------------------
+// Version
+// ---------------------------------------------------------------------------
+function getVersion() {
+  const pkg = require('../package.json');
+  return pkg.version;
+}
+
+// ---------------------------------------------------------------------------
+// Help
+// ---------------------------------------------------------------------------
+function showHelp() {
+  console.log(bold('Usage:') + ' npx @dzhechko/keysarium ' + cyan('<command>') + dim(' [options]'));
+  console.log('');
+  console.log(bold('Commands:'));
+  console.log('  ' + green('init') + '      Install toolkit into current project ' + dim('(default)'));
+  console.log('  ' + green('update') + '    Update toolkit to latest version');
+  console.log('  ' + green('remove') + '    Remove toolkit from project');
+  console.log('  ' + green('list') + '      List installed components');
+  console.log('  ' + green('doctor') + '    Check installation health');
+  console.log('');
+  console.log(bold('Options:'));
+  console.log('  ' + yellow('--minimal') + '    Install only .claude/ directory (skills, commands, rules)');
+  console.log('  ' + yellow('--force') + '      Overwrite existing files without prompting');
+  console.log('  ' + yellow('--with-docs') + '  Include docs/ directory');
+  console.log('  ' + yellow('--dry-run') + '    Show what would be done without making changes');
+  console.log('  ' + yellow('--help, -h') + '   Show this help message');
+  console.log('  ' + yellow('--version, -v') + ' Show version number');
+  console.log('');
+  console.log(bold('Examples:'));
+  console.log(dim('  $ ') + 'npx @dzhechko/keysarium init');
+  console.log(dim('  $ ') + 'npx @dzhechko/keysarium init --minimal --force');
+  console.log(dim('  $ ') + 'npx @dzhechko/keysarium update --dry-run');
+  console.log(dim('  $ ') + 'npx @dzhechko/keysarium doctor');
+  console.log('');
+}
+
+// ---------------------------------------------------------------------------
+// Parse arguments
+// ---------------------------------------------------------------------------
+function parseArgs(argv) {
+  const args = argv.slice(2);
+
+  const flags = {
+    minimal: false,
+    force: false,
+    withDocs: false,
+    dryRun: false,
+    targetDir: process.cwd(),
+  };
+
+  let command = null;
+
+  for (const arg of args) {
+    switch (arg) {
+      case '--minimal':
+        flags.minimal = true;
+        break;
+      case '--force':
+        flags.force = true;
+        break;
+      case '--with-docs':
+        flags.withDocs = true;
+        break;
+      case '--dry-run':
+        flags.dryRun = true;
+        break;
+      case '--help':
+      case '-h':
+        command = 'help';
+        break;
+      case '--version':
+      case '-v':
+        command = 'version';
+        break;
+      default:
+        if (!arg.startsWith('-') && command === null) {
+          command = arg;
+        }
+        break;
+    }
+  }
+
+  return { command, flags };
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+function main() {
+  const { command, flags } = parseArgs(process.argv);
+
+  // Handle version early (no banner)
+  if (command === 'version') {
+    console.log(getVersion());
+    return;
+  }
+
+  showBanner();
+
+  // Handle help early
+  if (command === 'help') {
+    showHelp();
+    return;
+  }
+
+  // Route to command handlers
+  const resolvedCommand = command || 'init';
+
+  switch (resolvedCommand) {
+    case 'init':
+      require('./commands/init')(flags);
+      break;
+
+    case 'update':
+      require('./commands/update')(flags);
+      break;
+
+    case 'remove':
+      require('./commands/remove')(flags);
+      break;
+
+    case 'list':
+      require('./commands/list')(flags);
+      break;
+
+    case 'doctor':
+      require('./commands/doctor')(flags);
+      break;
+
+    default:
+      error(`Unknown command: "${resolvedCommand}"`);
+      console.log('');
+      showHelp();
+      process.exitCode = 1;
+      break;
+  }
+}
+
+main();