@dzhechkov/keysarium 1.1.2 → 1.3.0

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.

package/templates/.claude/rules/background-workers.md

@@ -0,0 +1,72 @@
+# Background Workers Rules
+
+## When to Auto-Launch Workers
+
+| Trigger | Worker Type | Condition |
+|---------|------------|-----------|
+| Case completion | `consolidate` | After 3rd completed `/casarium` case in project |
+| Post-BTO test | `health-check` | After any `/bto-test` run (advisory, not enforced) |
+| Manual | Any | User runs `/workers start <type>` |
+
+Auto-launch triggers are ADVISORY. The system may suggest launching a worker but
+MUST wait for user confirmation before actually spawning a background agent.
+
+## Worker Isolation Rules
+
+1. Workers MUST only write to `.keysarium/workers/{worker_id}/` directory
+2. Workers MUST NOT modify files in `researches/` (active research data)
+3. Workers MUST NOT modify files in `features/` (active feature data)
+4. Workers MUST NOT modify files in `.claude/` (commands, rules, skills)
+5. Workers MUST NOT modify `CLAUDE.md`, `TOOLKIT_HARVEST.md`, or any root-level file
+6. Workers MAY read any file in the project for analysis purposes
+7. Exception: `export-brain` worker MAY write to `.keysarium/exports/` (standard export location)
+
+## Model Routing for Workers
+
+| Worker Type | Model | Rationale |
+|-------------|-------|-----------|
+| `consolidate` | sonnet | Pattern synthesis requires analytical reasoning |
+| `export-brain` | haiku | Primarily file reading and JSON assembly |
+| `health-check` | haiku | Structural checks, simple pattern matching |
+| `pattern-analysis` | sonnet | Trend analysis requires deeper reasoning |
+
+NEVER use opus for background workers -- workers perform routine tasks, not creative work.
+ALWAYS specify the model parameter when spawning a worker agent.
+
+## Concurrency Limits
+
+- Maximum concurrent workers: **3**
+- If limit reached, new worker requests MUST be rejected (not queued)
+- Rationale: prevent context exhaustion and ensure foreground responsiveness
+
+## Worker Naming Convention
+
+When spawning worker agents, use this naming format:
+```
+"Background Worker: {type} ({worker_id})"
+```
+
+Example: `"Background Worker: consolidate (wkr-20260301-143022-consolidate)"`
+
+## Worker Timeout
+
+- Workers are subject to the Agent tool's built-in timeout (~10 minutes)
+- Design workers to complete within this window
+- If a worker needs more time, it should checkpoint its progress and be re-launched
+
+## Registry Management
+
+- Only the `/workers` command (orchestrator) may write to `registry.json`
+- Workers write to their own `status.json` in their output directory
+- This prevents write conflicts between the orchestrator and workers
+
+## Anti-Patterns
+
+| Anti-Pattern | Detection | Fix |
+|-------------|-----------|-----|
+| Worker modifies research files | File write outside `.keysarium/workers/` | BLOCK -- enforce isolation |
+| Worker uses opus model | Model parameter check | Use haiku or sonnet per routing table |
+| More than 3 concurrent workers | Registry count check | Reject new worker start |
+| Worker spawns sub-agents | Instruction check in template | Templates explicitly forbid sub-agents |
+| Auto-launch without user consent | Missing user confirmation | Always ask before auto-launching |
+| Worker runs indefinitely | No progress updates | Workers must update status.json periodically |

package/templates/.claude/rules/dream-cycles.md

@@ -0,0 +1,90 @@
+# Dream Cycles Integration Rules
+
+## Auto-Trigger Rules
+
+When starting a new pipeline run (`/casarium` or `/feature-adr`), the orchestrator SHOULD check dream triggers:
+
+1. Read `.keysarium/insights/trigger-state.json`
+2. Evaluate triggers using the protocol in `lib/dream-engine.md`
+3. If any trigger is met, suggest to the user:
+   ```
+   Dream cycle trigger met ({reason}). Consider running /dream run for fresh insights.
+   ```
+4. This is ADVISORY only -- do not auto-launch without user confirmation
+5. If user declines, proceed normally
+
+### Trigger Check Timing
+
+- Check triggers at pipeline START (before Phase 0 or Step 0)
+- Do NOT check triggers mid-pipeline (would interrupt flow)
+- Do NOT check triggers on simple commands (/harvest, /brain-export, /learning-stats)
+
+## Insight Application Rules
+
+### At /casarium Phase 0 (Discovery)
+
+1. After domain detection, check `.keysarium/insights/` for the most recent dream result
+2. Filter insights by detected domain
+3. For each relevant insight, apply:
+   - **Performance insights**: Adjust time budget recommendations for flagged phases
+   - **Effectiveness insights**: Note skill preferences in the case brief
+   - **Preference insights**: Flag preferred CJM variants for Phase 2.5
+   - **Anti-pattern insights**: Add explicit warnings to the case brief
+4. Log loaded insights: "Applied {count} dream insights for {domain} domain"
+
+### At /casarium Phase 2 (Research)
+
+If a performance insight flags Phase 2 as problematic for the current domain:
+- Log a warning: "Dream insight: Phase 2 is historically challenging for {domain}. Extra attention recommended."
+- This is informational only -- does not change the research protocol
+
+### At /feature-adr Step 0 (Complexity Router)
+
+Dream insights are NOT applied to feature-adr (different pipeline, different context).
+
+## Retention Rules
+
+1. Maximum 10 dream result files in `.keysarium/insights/`
+2. Retention is enforced at the END of each dream cycle (Step 5)
+3. Retention is also enforced by `/dream clear`
+4. `trigger-state.json` is NEVER deleted by retention (it is state, not a result)
+5. Dream result files are named `dream-{YYYYMMDD}-{HHmmss}.json` for chronological sorting
+
+## Integration with memory_store()
+
+After writing a reward record via `memory_store()`, the system SHOULD:
+1. Attempt to read `.keysarium/insights/trigger-state.json`
+2. If it exists, increment `records_since_last_dream` and write back
+3. If it does not exist, skip silently (dream cycles not yet initialized)
+4. If write fails, log warning and continue (non-critical)
+
+This integration is ADVISORY -- memory_store() must succeed even if trigger state update fails.
+
+## Integration with Event Triggers
+
+### Quality Gate Failure
+
+When a BTO quality gate fails (Layer 0 rejection after 3 retries):
+1. Append event to `trigger-state.json`:
+   ```json
+   { "event_type": "quality_gate_failure", "timestamp": "...", "details": "BTO Layer 0 failed 3x" }
+   ```
+2. Suggest running `/dream run` to analyze the failure pattern
+
+### Case Completion
+
+When a `/casarium` run completes (Phase 6 packaging done):
+1. Append event to `trigger-state.json`:
+   ```json
+   { "event_type": "case_completion", "timestamp": "...", "details": "Completed {slug}" }
+   ```
+2. If `records_since_last_dream >= 10` (half of volume threshold), suggest a dream run
+
+## Model Routing
+
+| Operation | Model | Rationale |
+|-----------|-------|-----------|
+| Dream cycle execution | sonnet | Analytical pattern detection |
+| Trigger evaluation | N/A | Deterministic JSON operations |
+| Insight display | N/A | File reading and formatting |
+| Status display | N/A | File reading and formatting |

package/templates/.claude/rules/feature-adr-conventions.md

@@ -0,0 +1,82 @@
+# Feature ADR Conventions
+
+## When to Use /feature-adr vs Other Commands
+
+| Situation | Command |
+|-----------|---------|
+| Implementing a software feature | `/feature-adr` |
+| Researching an AI case for hackathon | `/casarium` |
+| Solving a complex problem (no code) | `/solve` |
+| Designing architecture only (no code) | `/architecture-phase` |
+| Building a new skill/command | `/bto-build` |
+
+## Output Directory
+
+All `/feature-adr` artifacts go into `features/<feature-slug>/`.
+NEVER create feature artifacts in the project root or in `researches/`.
+
+`researches/` is for `/casarium` pipeline only.
+`features/` is for `/feature-adr` pipeline only.
+
+## Slug Naming
+
+- Format: `kebab-case`, Latin characters only
+- Max length: 40 characters
+- Examples: `add-user-auth`, `refactor-payment-flow`, `migrate-to-postgres`
+- NO dates, NO ticket numbers in slug (put those in the artifact files)
+
+## Artifact Naming
+
+All artifacts use numbered prefix matching their step:
+
+```
+00_complexity_assessment.md
+01_requirements.md
+02_research.md
+03_adr/001-{decision-slug}.md
+04_domain_model.md
+05_architecture.md
+06_implementation_plan.md
+07_code_changes/change_manifest.md
+08_qe_report.md
+```
+
+## Complexity Tier Rules
+
+- Tier is determined by Step 0 (Complexity Router) — never guess
+- User can override tier at Checkpoint 0
+- Once confirmed, tier determines which steps run
+- Tier CANNOT change mid-pipeline (restart if scope changes significantly)
+
+## Integration with Existing Pipeline
+
+`/feature-adr` is independent from the Casarium pipeline.
+It does NOT use:
+- Phase numbering (Phase 0-6)
+- Research artifacts (00_product_discovery.md, etc.)
+- CJM prototypes
+- Presentation generation
+
+It DOES share:
+- Skills (`explore`, `problem-solver-enhanced`, `frontend-design`)
+- Agent swarm patterns
+- Checkpoint protocol
+- Promise tag system
+- Model routing rules
+
+## Feature Lifecycle
+
+```
+/feature-adr [description]
+  → Step 0: classify
+  → Steps 1-5: design (per tier)
+  → Step 6: plan
+  → Step 7: code
+  → Step 8: QE
+  → Done: README.md + code changes in repo
+```
+
+After completion:
+- Code changes live in the actual codebase (not just in `features/`)
+- `features/<slug>/` contains the design artifacts (ADRs, diagrams, reports)
+- These artifacts serve as documentation for the feature