@dzhechkov/keysarium 1.1.1 → 1.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dzhechkov/keysarium",
-  "version": "1.1.1",
-  "description": "AI Case Research Toolkit for Claude Code — full 7-phase pipeline for AI case studies, hackathons, and casariums",
+  "version": "1.2.0",
+  "description": "AI Case Research Toolkit for Claude Code — full 7-phase pipeline with feature-adr, dream cycles, background workers, multi-platform support, and reward learning",
   "main": "src/cli.js",
   "bin": {
     "keysarium": "./bin/cli.js"
@@ -39,5 +39,13 @@
   "homepage": "https://github.com/dzhechko/product-keysarium-2026#readme",
   "bugs": {
     "url": "https://github.com/dzhechko/product-keysarium-2026/issues"
+  },
+  "peerDependencies": {
+    "@dzhechkov/keysarium-core": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@dzhechkov/keysarium-core": {
+      "optional": true
+    }
   }
 }

package/src/commands/init.js

@@ -23,7 +23,7 @@ const {
  */
 function resolveComponents(options) {
   const { minimal, withDocs } = options;
-  const coreKeys = ['skills', 'commands', 'rules', 'agents', 'hooks', 'claude_md', 'harvest'];
+  const coreKeys = ['skills', 'commands', 'rules', 'shards', 'agents', 'hooks', 'claude_md', 'harvest'];
   const keys = [...coreKeys];
 
   if (!minimal) {

package/templates/.claude/commands/dream.md

@@ -0,0 +1,101 @@
+# /dream -- Dream Cycles Management
+
+Manage Dream Cycles: trigger dream analysis, view insights, check trigger status.
+
+Dream Cycles build on the reward-calibrated learning system (`lib/memory-protocol.md`,
+`lib/reward-tracker.md`) and background workers (`lib/background-workers.md`).
+
+## Usage
+
+```
+/dream run          — Manually trigger a dream cycle
+/dream insights     — Show latest insights
+/dream status       — Show trigger state
+/dream clear        — Clear old insights (keep last 10)
+```
+
+The argument `$ARGUMENTS` determines which subcommand to execute.
+
+## Protocol
+
+### 1. Parse Subcommand
+
+Parse `$ARGUMENTS` to determine subcommand:
+- If starts with "run" -> execute RUN
+- If starts with "insights" -> execute INSIGHTS
+- If starts with "status" -> execute STATUS
+- If starts with "clear" -> execute CLEAR
+- If empty or unrecognized -> show usage help
+
+### 2. Execute Subcommand
+
+#### RUN: Manually Trigger Dream Cycle
+
+1. Read the DreamEngine protocol: `lib/dream-engine.md`
+2. Read the worker template: `lib/worker-templates/dream-cycle.md`
+3. Read the background workers protocol: `lib/background-workers.md`
+4. Generate a worker ID: `wkr-{YYYYMMDD}-{HHmmss}-dream-cycle`
+5. Create worker directory: `.keysarium/workers/{worker_id}/output/`
+6. Register in `.keysarium/workers/registry.json`
+7. Launch background worker agent with:
+   - Prompt: Contents of `lib/worker-templates/dream-cycle.md` with WORKER_ID, OUTPUT_DIR, TRIGGER_REASON="manual" injected
+   - Model: sonnet
+   - run_in_background: true
+8. Report to user:
+
+```
+Dream cycle started.
+  ID:     {worker_id}
+  Trigger: manual
+  Model:  sonnet
+  Output: .keysarium/workers/{worker_id}/
+
+Use /dream status to check progress.
+Use /dream insights to view results after completion.
+```
+
+#### INSIGHTS: Show Latest Insights
+
+1. Check if `.keysarium/insights/` exists. If not, display empty state.
+2. List all `dream-*.json` files, sort by name DESC, take the first (most recent).
+3. Read the most recent dream result file.
+4. Display insights using the format from `lib/dream-engine.md` (Insight Display Format).
+5. Only show insights with `confidence >= 0.3`.
+6. If no dream files exist, display:
+
+```
+No dream insights available yet.
+
+To generate insights:
+1. Run several cases with /casarium (data is collected automatically)
+2. Run /dream run to trigger analysis
+3. Use /dream insights to view results
+
+Dream insights are generated from accumulated reward data in .keysarium/memory/
+```
+
+#### STATUS: Show Trigger State
+
+1. Read `.keysarium/insights/trigger-state.json`. If missing, display default state.
+2. Calculate time elapsed since `last_dream_completed_at`.
+3. Display using the format from `lib/dream-engine.md` (Status Display Format).
+4. Evaluate triggers and show which are met.
+5. If any trigger is met, suggest running `/dream run`.
+
+#### CLEAR: Clear Old Insights
+
+1. List all `dream-*.json` files in `.keysarium/insights/`.
+2. Sort by name DESC.
+3. Keep the 10 most recent files.
+4. Delete older files.
+5. Report count of deleted files.
+6. If 10 or fewer files exist, report "Nothing to clear."
+
+```
+Dream insights cleanup:
+  Total files: 15
+  Kept: 10 (most recent)
+  Deleted: 5
+
+Trigger state preserved.
+```

package/templates/.claude/commands/feature-adr.md

@@ -0,0 +1,92 @@
+# /feature-adr — Adaptive Feature Development Pipeline
+
+## Использование
+```
+/feature-adr [описание фичи или путь к issue]
+```
+
+## Аргумент
+$ARGUMENTS
+
+## Действия
+
+1. **Загрузи governance shard:** Прочитай `.claude/shards/feature-adr.shard.md`
+2. **Загрузи скилл:** Прочитай `.claude/skills/feature-adr/SKILL.md`
+
+3. **Step 0 — Complexity Router:**
+   - Прочитай `modules/00-complexity-router.md` и `references/complexity-matrix.md`
+   - Классифицируй фичу в S/M/L/XL
+   - Определи `{ACTIVE_STEPS}` и `{TIME_BUDGET}`
+   - Покажи Checkpoint 0 и **жди подтверждения tier**
+
+4. **Steps 1-8 — Execute Active Steps:**
+   - Для каждого шага из `{ACTIVE_STEPS}`:
+     - Прочитай `modules/{step}.md`
+     - Выполни протокол шага
+     - Создай артефакты в `features/<slug>/`
+     - Покажи Checkpoint N
+
+5. **Финализация:**
+   - Создай `features/<slug>/README.md` с summary
+   - Покажи итоговый отчёт
+
+## Создание директории
+
+При первом запуске создай:
+```
+features/<feature-slug>/
+├── diagrams/        ← для Mermaid диаграмм (M+)
+├── 03_adr/          ← для ADR файлов (M+)
+└── 07_code_changes/ ← для манифеста изменений
+```
+
+Slug: kebab-case из описания фичи (латиница, max 40 символов).
+
+## Параллелизация (Agent Swarm)
+
+Для L/XL тiers:
+- Steps 2+3 запускай параллельно (2 агента, sonnet + opus)
+- Steps 4+5 можно параллельно если Step 3 уже завершён
+- Step 7: N параллельных агентов (по одному на модуль)
+- Step 8: 3 параллельных агента (unit ‖ integration ‖ review)
+
+Для S/M: всё последовательно, параллелизация не нужна.
+
+## Model Routing
+
+| Step | Model |
+|------|-------|
+| 0 Router | haiku |
+| 1 Requirements | sonnet |
+| 2 Research | sonnet |
+| 3 ADR | opus |
+| 4 DDD | opus |
+| 5 Architecture | opus |
+| 6 Impl Plan | sonnet |
+| 7 Code | opus |
+| 8 QE | sonnet |
+
+## Checkpoint формат
+
+```
+═══════════════════════════════════════════════════════
+⏸️ STEP N/8: [Step Name] Complete
+<promise>[PROMISE_TAG]</promise>
+Tier: {COMPLEXITY_TIER} | Active Steps: {ACTIVE_STEPS}
+
+[Summary]
+Artifacts: [list] ✅
+
+• "ок" — next step
+• "углуби [section]" — elaborate
+• "[feedback]" — adjust
+═══════════════════════════════════════════════════════
+```
+
+## Critical Rules
+
+- **НИКОГДА** не пропускай Step 0 (Router) — всегда классифицируй сначала
+- **НИКОГДА** не начинай Step 7 (Code) без Step 6 (Plan)
+- **НИКОГДА** не пропускай Step 8 (QE) — тестирование обязательно
+- **ВСЕГДА** жди подтверждения пользователя на Checkpoint перед переходом
+- **ВСЕ артефакты** создаются в `features/<slug>/`, не в корне проекта

package/templates/.claude/commands/init-platform.md

@@ -0,0 +1,161 @@
+---
+description: "Generate platform-specific configuration for Cursor, OpenCode, or GitHub Copilot"
+argument: "--platform cursor|opencode|copilot|all"
+---
+
+# Init Platform — Multi-Platform Config Generator
+
+Generate platform-native configuration files from the existing `.claude/` directory structure.
+Supports Cursor, OpenCode, and GitHub Copilot.
+
+## Protocol
+
+### Step 1: Parse Arguments
+
+Parse `$ARGUMENTS` for the `--platform` flag:
+
+| Argument | Action |
+|----------|--------|
+| `--platform cursor` | Generate Cursor config only |
+| `--platform opencode` | Generate OpenCode config only |
+| `--platform copilot` | Generate GitHub Copilot config only |
+| `--platform all` | Generate configs for all three platforms |
+| (no argument) | Prompt user to choose a platform |
+
+If `$ARGUMENTS` does not contain `--platform`, ask:
+```
+Which platform(s) to generate config for?
+1. cursor — .cursorrules + .cursor/skills/
+2. opencode — .opencode/ directory
+3. copilot — .github/copilot-instructions.md
+4. all — all three platforms
+```
+
+### Step 2: Load Adapter Definitions
+
+```
+Read: lib/platform-adapters.md
+```
+
+This file contains the platform registry: mapping platform names to their template paths,
+output structures, and translation strategies.
+
+### Step 3: Scan Source Content
+
+Scan the following directories for content to translate:
+
+1. **Skills:** List all directories in `.claude/skills/`, read each `SKILL.md`
+2. **Rules:** List all `.md` files in `.claude/rules/`
+3. **Project context:** Read `CLAUDE.md` for project overview, pipeline description, and anti-patterns
+
+Build a content inventory:
+```
+Skills found: [list skill names]
+Rules found: [list rule file names]
+Project: [project name from CLAUDE.md]
+```
+
+### Step 4: Check for Existing Configs
+
+Before generating, check if target files already exist:
+
+| Platform | Check |
+|----------|-------|
+| Cursor | Does `.cursorrules` exist? Does `.cursor/` exist? |
+| OpenCode | Does `.opencode/` exist? |
+| Copilot | Does `.github/copilot-instructions.md` exist? |
+
+If any target file exists, warn:
+```
+Warning: {file} already exists.
+Options:
+  - "перезаписать" — overwrite existing config
+  - "рядом" — generate as {file}.generated.md
+  - "пропустить" — skip this platform
+```
+
+For auto-proceed mode: generate as `.generated.md` variant to avoid data loss.
+
+### Step 5: Generate Platform Configs
+
+For each selected platform, load the corresponding template and follow its generation protocol:
+
+#### Cursor
+```
+Read: lib/platform-templates/cursor.md
+```
+Follow the template to generate:
+- `.cursorrules` (main instructions, <10K tokens)
+- `.cursor/skills/` (optional, for large skills >200 lines)
+
+#### OpenCode
+```
+Read: lib/platform-templates/opencode.md
+```
+Follow the template to generate:
+- `.opencode/config.yaml` (main configuration)
+- `.opencode/skills/` (one file per skill)
+- `.opencode/rules/` (one file per rule)
+- `.opencode/README.md` (brief explanation)
+
+#### GitHub Copilot
+```
+Read: lib/platform-templates/copilot.md
+```
+Follow the template to generate:
+- `.github/copilot-instructions.md` (single file, <8K tokens)
+
+### Step 6: Validate Generated Output
+
+For each generated platform config:
+
+- [ ] All skills from `.claude/skills/` are represented
+- [ ] All rules from `.claude/rules/` are represented
+- [ ] Project overview is included
+- [ ] Platform-specific size limits are respected
+- [ ] No Claude Code-specific tool references remain (Agent tool, model routing)
+- [ ] File paths in generated content reference the correct platform directory
+
+### Step 7: Report Results
+
+Display a summary:
+
+```
+═══════════════════════════════════════════════════════
+Platform Config Generation Complete
+
+Platform: {platform name(s)}
+Skills translated: {N}
+Rules translated: {N}
+
+Files created:
+  {list each file created with path}
+
+Source: .claude/ directory
+Note: .claude/ remains the source of truth.
+      Re-run /init-platform after modifying skills or rules.
+
+• "ок" — done
+• "покажи {file}" — preview a generated file
+• "перегенерируй {platform}" — regenerate for specific platform
+═══════════════════════════════════════════════════════
+```
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| No `.claude/skills/` found | Abort with message: "No skills found in .claude/skills/. Nothing to translate." |
+| No `.claude/rules/` found | Warn but continue: rules section will be empty |
+| Template file missing | Abort with message: "Template not found: lib/platform-templates/{platform}.md" |
+| Target file exists | See Step 4 (conflict resolution) |
+
+## Modular Reuse
+
+This command follows the scan-then-generate pattern from `/brain-export`.
+The template-based approach means adding a new platform requires only:
+1. A new template file in `lib/platform-templates/`
+2. An entry in `lib/platform-adapters.md`
+3. A new case in Step 5 of this command
+
+No changes to the core command logic are needed for platform additions.

package/templates/.claude/commands/learning-stats.md

@@ -0,0 +1,130 @@
+---
+description: "Show reward learning statistics: phase averages, domain patterns, skill effectiveness"
+argument: "optional filters: --domain <name> --phase <number>"
+---
+
+# Learning Stats -- Reward Analytics Dashboard
+
+Display accumulated reward learning statistics from the Reward-Calibrated Learning System.
+
+## Protocol
+
+Read `lib/reward-tracker.md` for the full analytics specification.
+
+### Step 1: Parse Arguments
+
+Parse `$ARGUMENTS` for optional filters:
+- `--domain <name>` -- Filter by domain (banking, retail, enterprise, healthcare)
+- `--phase <number>` -- Filter by phase number (0-5)
+- No arguments -- Show all data
+
+### Step 2: Check Memory Directory
+
+Check if `.keysarium/memory/` exists and contains reward records.
+
+If **no data exists**, display:
+```
+═══════════════════════════════════════════════════════
+Learning Stats
+═══════════════════════════════════════════════════════
+
+No reward data found in .keysarium/memory/
+
+To start collecting data:
+1. Run a case with /casarium
+2. Respond at each checkpoint -- rewards are tracked automatically
+3. Run /learning-stats again after completing a case
+
+Memory directory: .keysarium/memory/ (created on first pipeline run)
+═══════════════════════════════════════════════════════
+```
+
+### Step 3: Load and Compute Statistics
+
+1. Scan `.keysarium/memory/` recursively for all reward record JSON files.
+2. Exclude expired records (where `expires_at < current_date`).
+3. Apply filters from Step 1 (if provided).
+4. Compute statistics following the protocol in `lib/reward-tracker.md`:
+   - Per-phase reward averages with trend detection
+   - Per-domain breakdown with bottleneck identification
+   - Per-skill effectiveness rankings
+   - Domain pattern detection
+
+### Step 4: Write Updated Stats
+
+Write computed statistics to:
+- `.keysarium/memory/_stats/reward-summary.json`
+- `.keysarium/memory/_patterns/domain-patterns.json`
+
+### Step 5: Display Results
+
+Display formatted tables following the output format in `lib/reward-tracker.md`:
+
+```
+═══════════════════════════════════════════════════════
+Learning Stats ({total_records} records, {total_cases} cases)
+═══════════════════════════════════════════════════════
+
+Phase Reward Averages
+───────────────────────────────────────────
+Phase       | Avg    | Runs | Trend       |
+────────────|────────|──────|─────────────|
+Phase 0     | {avg}  | {n}  | {trend}     |
+Phase 1     | {avg}  | {n}  | {trend}     |
+Phase 2     | {avg}  | {n}  | {trend}     |
+Phase 2.5   | {avg}  | {n}  | {trend}     |
+Phase 3     | {avg}  | {n}  | {trend}     |
+Phase 4     | {avg}  | {n}  | {trend}     |
+Phase 5     | {avg}  | {n}  | {trend}     |
+────────────|────────|──────|─────────────|
+Overall     | {avg}  | {n}  | {trend}     |
+
+Domain Breakdown
+───────────────────────────────────────────
+Domain      | Avg    | Cases | Bottleneck  |
+────────────|────────|───────|─────────────|
+{domain}    | {avg}  | {n}   | {phase}     |
+
+Skill Effectiveness
+───────────────────────────────────────────
+Skill                       | Avg  | Best Domain |
+────────────────────────────|──────|─────────────|
+{skill}                     | {avg}| {domain}    |
+
+Detected Patterns (confidence > 0.5)
+───────────────────────────────────────────
+1. [{confidence}] {description}
+   Advice: {actionable_advice}
+
+═══════════════════════════════════════════════════════
+
+• "/learning-stats --domain banking" — filter by domain
+• "/learning-stats --phase 2" — filter by phase
+• "ок" — done
+═══════════════════════════════════════════════════════
+```
+
+### Step 6: Offer Actions
+
+After displaying stats, offer:
+- Filter by domain or phase (if not already filtered)
+- "purge expired" -- Run retention policy cleanup
+- "reset" -- Delete all memory data and start fresh (with confirmation)
+
+## Filtered Views
+
+### --domain Filter
+
+When `--domain` is specified, show only:
+- Phase averages for that domain
+- Skill effectiveness in that domain
+- Patterns for that domain
+- Cases in that domain
+
+### --phase Filter
+
+When `--phase` is specified, show only:
+- That phase's statistics across all domains
+- Domain breakdown for that specific phase
+- Skills used in that phase with their rewards
+- Patterns related to that phase

package/templates/.claude/commands/workers.md

@@ -0,0 +1,140 @@
+# /workers — Background Worker Management
+
+Manage background workers for non-blocking operations in Keysarium.
+
+## Usage
+
+```
+/workers start <type>    — Launch a background worker
+/workers status          — Show active workers and progress
+/workers stop <id>       — Stop a running worker
+/workers list            — List available worker types
+```
+
+## Arguments
+
+$ARGUMENTS — Subcommand and optional parameters (e.g., "start consolidate", "status", "stop wkr-xxx", "list")
+
+## Protocol
+
+### Step 1: Parse Command
+
+Parse $ARGUMENTS to determine the subcommand:
+
+- If starts with "start": extract worker type from remaining args
+- If "status": no additional args needed
+- If starts with "stop": extract worker ID from remaining args
+- If "list": no additional args needed
+- If empty or unrecognized: show usage help
+
+### Step 2: Load Protocol
+
+Read the worker protocol:
+```
+Read: lib/background-workers.md
+Read: .claude/rules/background-workers.md
+```
+
+### Step 3: Execute Subcommand
+
+#### For `/workers list`
+
+Display available worker types from the protocol:
+
+```
+═══════════════════════════════════════════════════════
+Available Worker Types
+═══════════════════════════════════════════════════════
+
+Type              Model    Description
+consolidate       sonnet   Scan completed researches for patterns, update TOOLKIT_HARVEST.md
+export-brain      haiku    Non-blocking brain export to .keysarium/exports/
+health-check      haiku    Verify skill trust tiers, check for stale data
+pattern-analysis  sonnet   Analyze reward data and trends across cases
+
+Usage: /workers start <type>
+═══════════════════════════════════════════════════════
+```
+
+#### For `/workers start <type>`
+
+1. Validate `<type>` is one of: consolidate, export-brain, health-check, pattern-analysis
+2. Ensure `.keysarium/workers/` directory exists (create if needed)
+3. Read or create `.keysarium/workers/registry.json`
+4. Count active workers (status = starting or running)
+5. If count >= 3: reject with "Maximum concurrent workers (3) reached"
+6. Generate worker ID: `wkr-{YYYYMMDD}-{HHmmss}-{type}`
+7. Create worker directory: `.keysarium/workers/{worker_id}/output/`
+8. Add entry to registry.json with status `starting`
+9. Read worker template from `lib/worker-templates/{type}.md`
+10. Spawn background agent:
+
+```
+Use the Agent tool with:
+- prompt: [Worker template content with WORKER_ID and OUTPUT_DIR injected]
+- model: [From routing table in protocol]
+- run_in_background: true
+```
+
+11. Report to user:
+```
+Background worker started.
+  ID:     {worker_id}
+  Type:   {type}
+  Model:  {model}
+  Output: .keysarium/workers/{worker_id}/
+
+Use `/workers status` to check progress.
+```
+
+#### For `/workers status`
+
+1. Read `.keysarium/workers/registry.json`
+2. If no registry or empty: "No workers have been started yet."
+3. For each worker in registry:
+   - Read `.keysarium/workers/{id}/status.json` if it exists
+   - Update registry entry with latest status
+   - If status.json missing and registry says "running": mark as "unknown"
+4. Prune entries older than 24 hours that are completed/failed/stopped
+5. Write updated registry
+6. Display formatted table:
+
+```
+═══════════════════════════════════════════════════════
+Background Workers Status
+═══════════════════════════════════════════════════════
+
+ID                                    Type          Status      Progress         Started
+wkr-20260301-143022-consolidate       consolidate   running     scanning (3/7)   14:30
+wkr-20260301-143500-health-check      health-check  completed   6/6 checks       14:35
+wkr-20260301-144000-export-brain      export-brain  failed      —                14:40
+
+Active: 1/3 | Completed: 1 | Failed: 1
+═══════════════════════════════════════════════════════
+```
+
+If a worker is completed, also show output location:
+```
+Completed worker output:
+  wkr-20260301-143500-health-check → .keysarium/workers/wkr-20260301-143500-health-check/output/
+```
+
+#### For `/workers stop <id>`
+
+1. Read registry.json
+2. Find worker entry by ID (or prefix match for convenience)
+3. If not found: "Worker {id} not found in registry"
+4. If status is not `running`: "Worker {id} is not running (status: {status})"
+5. Write empty file: `.keysarium/workers/{id}/stop-requested`
+6. Update registry entry status to `stop-requested`
+7. Report:
+```
+Stop requested for worker {id}.
+Worker will stop at next safe point.
+Use `/workers status` to confirm.
+```
+
+### Step 4: Confirm
+
+After executing the subcommand, confirm the action was completed.
+Do NOT display a checkpoint -- `/workers` is a utility command, not a pipeline phase.