@dzhechkov/keysarium 1.1.2 → 1.2.0

package/templates/lib/platform-templates/copilot.md

@@ -0,0 +1,134 @@
+# GitHub Copilot Platform Template
+
+> Generates `.github/copilot-instructions.md` from `.claude/` sources.
+
+## Target Format
+
+GitHub Copilot reads custom instructions from `.github/copilot-instructions.md`. This is a single markdown file that provides project-level context and instructions to Copilot's AI assistant.
+
+## Generation Protocol
+
+### Step 1: Generate `.github/copilot-instructions.md`
+
+Create `.github/copilot-instructions.md` with the following structure:
+
+```markdown
+# {Project Name} — Copilot Instructions
+
+> Auto-generated from .claude/ directory by /init-platform. Source of truth: .claude/
+
+## Project Overview
+
+{Extract the project description from CLAUDE.md:
+ - Purpose (2-3 sentences)
+ - Key concepts (pipeline phases, skills, research methodology)
+ - Project structure overview (simplified directory tree)
+}
+
+## Core Rules
+
+{For each file in .claude/rules/, create a subsection:}
+
+### {Rule Name}
+
+{Summarize the rule to 5-10 key bullet points.
+ Focus on actionable instructions.
+ Omit implementation details specific to Claude Code.
+ Preserve critical constraints (PARANOID mode, mandatory phases, etc.)
+}
+
+---
+
+## Skills Reference
+
+{For each skill in .claude/skills/:}
+
+### {Skill Name}
+
+**Purpose:** {One-line description}
+
+**When to use:** {Extract the "When" or trigger conditions}
+
+**Key protocol:**
+{Numbered list of 3-5 core steps from the skill's protocol section.
+ Simplify each step to 1-2 sentences.
+ Omit tool-specific references.}
+
+**Quality gates:**
+{2-4 key quality checks from the skill}
+
+---
+
+## Pipeline Overview
+
+{Simplified version of the phase pipeline:}
+
+| Phase | Purpose | Key Output |
+|-------|---------|------------|
+{One row per phase, extracted from CLAUDE.md pipeline table}
+
+## Anti-Patterns to Avoid
+
+{Extract the anti-patterns table, keeping the Pattern and Required Fix columns}
+
+## Domain-Specific Guidance
+
+{Summarize domain rules from .claude/rules/domain-specific.md:
+ - Banking: key constraints
+ - Retail: key constraints
+ - Enterprise: key constraints
+ Keep each domain to 3-4 bullet points.}
+
+## File Conventions
+
+{Extract key file naming and directory conventions from .claude/rules/file-conventions.md}
+```
+
+### Step 2: Size Check
+
+After generation, verify:
+- `.github/copilot-instructions.md` is under 8,000 tokens (~6,000 words)
+- If over limit, prioritize in this order:
+  1. Core Rules (keep all)
+  2. Anti-Patterns (keep all)
+  3. Skills Reference (summarize further)
+  4. Pipeline Overview (keep)
+  5. Domain-Specific Guidance (trim to most relevant domain)
+
+### Step 3: Ensure `.github/` Directory Exists
+
+If `.github/` directory does not exist, create it. If `copilot-instructions.md` already exists, warn the user and generate to `copilot-instructions.generated.md` instead.
+
+## Content Adaptation Rules
+
+| Source Element | Copilot Adaptation |
+|----------------|---------------------|
+| `Read: .claude/skills/X/SKILL.md` | Summarize inline (no separate files) |
+| Agent tool references | "Break complex tasks into sub-tasks" |
+| Model routing (haiku/sonnet/opus) | Omit entirely (Copilot uses its own model) |
+| `$ARGUMENTS` variable | "User-provided context" |
+| Promise tags `<promise>` | Keep as phase completion markers |
+| Checkpoint protocol | "Confirm with user before moving to next phase" |
+| BTO-specific content | Omit or heavily summarize (not relevant for Copilot workflows) |
+| Governance shards | Summarize key constraints only |
+
+## Example Output Structure
+
+```
+.github/
+└── copilot-instructions.md    (single file, <8K tokens)
+```
+
+## Copilot-Specific Notes
+
+1. **Copilot reads the entire file** on each interaction, so shorter is better
+2. **No directory-based skills** — everything must be in the single markdown file
+3. **Copilot does not support slash commands** — reference commands as "workflows" or "procedures"
+4. **Focus on rules and constraints** — Copilot benefits most from clear do/don't instructions
+5. **Code patterns over prose** — where possible, show code examples instead of lengthy descriptions
+
+## Last Verified
+
+Platform: GitHub Copilot
+Format version: .github/copilot-instructions.md (2025+)
+Last verified: 2026-03-01

package/templates/lib/platform-templates/cursor.md

@@ -0,0 +1,95 @@
+# Cursor Platform Template
+
+> Generates `.cursorrules` and optionally `.cursor/skills/` from `.claude/` sources.
+
+## Target Format
+
+Cursor uses a `.cursorrules` file in the project root. This is a plain-text/markdown file that Cursor's AI reads as project-level instructions. Optionally, `.cursor/skills/` can hold longer skill documents.
+
+## Generation Protocol
+
+### Step 1: Generate `.cursorrules`
+
+Create a file `.cursorrules` in the project root with the following structure:
+
+```
+# Project: {project name from CLAUDE.md title}
+
+## Project Overview
+
+{Extract the first 2-3 paragraphs from CLAUDE.md that describe the project purpose}
+
+## Rules
+
+{For each file in .claude/rules/:}
+
+### {Rule file name without extension, title-cased}
+
+{Extract the key rules as bullet points. Omit tables and complex formatting.
+ Keep each rule to 1-2 lines. Target: 3-8 bullet points per rule file.}
+
+## Skills
+
+{For each skill in .claude/skills/:}
+
+### {Skill name, title-cased}
+
+{Read SKILL.md and extract:
+ - One-line description (from the skill's header or first paragraph)
+ - Core protocol steps (numbered list, 3-5 key steps)
+ - Key constraints or quality gates (2-3 bullet points)
+ Keep each skill section to 15-30 lines maximum.}
+
+## Pipeline
+
+{Extract the pipeline phases table from CLAUDE.md, simplified to:
+ Phase name | Description | Key output}
+
+## Anti-Patterns
+
+{Copy the anti-patterns table from CLAUDE.md or .claude/rules/anti-patterns.md}
+```
+
+### Step 2: Generate `.cursor/skills/` (for large skills)
+
+If any skill's SKILL.md exceeds 200 lines, create a separate file in `.cursor/skills/`:
+
+```
+.cursor/skills/{skill-name}.md
+```
+
+Content: the full SKILL.md content, reformatted to remove Claude Code-specific references (like "Read: .claude/skills/..." instructions). Replace with relative references.
+
+### Step 3: Size Check
+
+After generation, verify:
+- `.cursorrules` is under 10,000 tokens (~7,500 words)
+- If over limit, further summarize skill sections (keep rules intact)
+
+## Content Adaptation Rules
+
+| Source Element | Cursor Adaptation |
+|----------------|-------------------|
+| `Read: .claude/skills/X/SKILL.md` | Replace with: "Follow the {X} skill protocol" |
+| Agent tool references | Replace with: "For parallel work, break into sub-tasks" |
+| Model routing (haiku/sonnet/opus) | Omit (Cursor uses its own model) |
+| `$ARGUMENTS` variable | Replace with: "User-provided input" |
+| Promise tags `<promise>` | Keep as documentation markers |
+| Checkpoint protocol | Adapt to: "Pause and confirm with user before proceeding" |
+
+## Example Output Structure
+
+```
+.cursorrules                          (main instructions file, <10K tokens)
+.cursor/
+└── skills/
+    ├── reverse-engineering-unicorn.md (full skill, if >200 lines)
+    ├── bto.md                        (full skill, if >200 lines)
+    └── feature-adr.md               (full skill, if >200 lines)
+```
+
+## Last Verified
+
+Platform: Cursor
+Format version: .cursorrules (2025+)
+Last verified: 2026-03-01

package/templates/lib/platform-templates/opencode.md

@@ -0,0 +1,155 @@
+# OpenCode Platform Template
+
+> Generates `.opencode/` directory structure from `.claude/` sources.
+
+## Target Format
+
+OpenCode uses a `.opencode/` directory in the project root with a `config.yaml` configuration file and skill/rule markdown files. This is the most structurally similar platform to Claude Code's `.claude/` directory.
+
+## Generation Protocol
+
+### Step 1: Generate `.opencode/config.yaml`
+
+Create `.opencode/config.yaml` with the following structure:
+
+```yaml
+# OpenCode configuration for {project name}
+# Generated from .claude/ directory by /init-platform
+# Source: product-keysarium-2026
+
+project:
+  name: "{project name from CLAUDE.md}"
+  description: "{first paragraph of CLAUDE.md}"
+
+instructions: |
+  {Extract the critical rules from CLAUDE.md:
+   - File conventions
+   - Research quality requirements (PARANOID mode)
+   - Checkpoint protocol summary
+   - Anti-patterns to avoid
+   Keep to 30-50 lines.}
+
+skills_dir: ".opencode/skills"
+rules_dir: ".opencode/rules"
+```
+
+### Step 2: Generate `.opencode/skills/`
+
+For each skill in `.claude/skills/`:
+
+Create `.opencode/skills/{skill-name}.md`:
+
+```markdown
+# {Skill Name}
+
+{Full content of SKILL.md with the following adaptations:}
+
+{Replace Claude Code-specific instructions:
+ - "Read: .claude/skills/X/SKILL.md" → "See: .opencode/skills/X.md"
+ - "Read: .claude/rules/X.md" → "See: .opencode/rules/X.md"
+ - Agent tool references → "For parallel work, break into sub-tasks"
+ - Model routing references → Omit or note as "model selection is platform-managed"
+}
+
+{If the skill has references/ directory:
+ - Inline key reference content at the bottom under "## References"
+ - Or create .opencode/skills/{skill-name}/ directory with reference files
+}
+
+{If the skill has modules/ directory:
+ - Create .opencode/skills/{skill-name}/ directory
+ - Copy module files with path adaptations
+}
+```
+
+### Step 3: Generate `.opencode/rules/`
+
+For each rule file in `.claude/rules/`:
+
+Create `.opencode/rules/{rule-name}.md`:
+
+```markdown
+# {Rule Title}
+
+{Full content of the rule file, with minimal adaptation:
+ - Replace .claude/ paths with .opencode/ paths
+ - Keep tables and structured content intact
+ - Remove Claude Code-specific tool references
+}
+```
+
+### Step 4: Generate `.opencode/README.md`
+
+Create a brief README explaining the configuration:
+
+```markdown
+# OpenCode Configuration
+
+This directory was generated from `.claude/` by the `/init-platform` command.
+
+## Structure
+
+- `config.yaml` — Main configuration
+- `skills/` — Skill definitions (one per file)
+- `rules/` — Project rules (one per file)
+
+## Regenerating
+
+To regenerate this configuration from updated `.claude/` sources:
+```
+/init-platform --platform opencode
+```
+
+## Source
+
+Generated from: .claude/ directory
+Generated on: {date}
+```
+
+## Content Adaptation Rules
+
+| Source Element | OpenCode Adaptation |
+|----------------|---------------------|
+| `.claude/skills/X/SKILL.md` | `.opencode/skills/X.md` |
+| `.claude/rules/X.md` | `.opencode/rules/X.md` |
+| `.claude/shards/X.md` | `.opencode/shards/X.md` (if shards are included) |
+| `Read: path` instructions | `See: adapted-path` |
+| Agent tool references | "Break into sub-tasks for parallel work" |
+| Model routing (haiku/sonnet/opus) | Omit (platform-managed) |
+| `$ARGUMENTS` variable | "User-provided input" |
+
+## Example Output Structure
+
+```
+.opencode/
+├── config.yaml
+├── README.md
+├── skills/
+│   ├── explore.md
+│   ├── goap-research-ed25519.md
+│   ├── problem-solver-enhanced.md
+│   ├── frontend-design.md
+│   ├── presentation-storyteller.md
+│   ├── reverse-engineering-unicorn.md
+│   ├── bto.md
+│   └── feature-adr.md
+└── rules/
+    ├── agent-swarm.md
+    ├── anti-patterns.md
+    ├── checkpoint-protocol.md
+    ├── domain-specific.md
+    ├── file-conventions.md
+    ├── modular-reuse.md
+    ├── research-quality.md
+    ├── model-routing.md
+    ├── trust-tiers.md
+    ├── bto-quality-gates.md
+    ├── feature-adr-conventions.md
+    └── feedback-loops.md
+```
+
+## Last Verified
+
+Platform: OpenCode
+Format version: .opencode/ directory (2025+)
+Last verified: 2026-03-01

package/templates/lib/reward-tracker.md

@@ -0,0 +1,256 @@
+# Reward Tracker -- Analytics & Pattern Detection
+
+Computes aggregate statistics and detects domain patterns from accumulated reward records. Used by `/learning-stats` and by `memory_query()` for pattern enrichment.
+
+## Overview
+
+The Reward Tracker operates on the data stored by the Memory Protocol (`lib/memory-protocol.md`). It reads all RewardRecord JSON files from `.keysarium/memory/` and produces two output artifacts:
+
+1. **reward-summary.json** -- aggregate statistics per phase, domain, and skill
+2. **domain-patterns.json** -- detected patterns with confidence scores
+
+## Computation Protocol
+
+### Step 1: Load All Records
+
+1. Scan `.keysarium/memory/` recursively for all `*.json` files (excluding config.json, domain-patterns.json, reward-summary.json).
+2. Parse each JSON file as a RewardRecord.
+3. Exclude records where `expires_at < current_date`.
+4. Collect into a list sorted by `timestamp` DESC.
+
+### Step 2: Per-Phase Reward Averages
+
+Group records by `phase` and compute:
+
+```json
+{
+  "phase-0": {
+    "avg_reward": 0.85,
+    "total_runs": 12,
+    "distribution": {
+      "excellent": 8,
+      "good": 3,
+      "needs_work": 1,
+      "failed": 0
+    },
+    "trend": "stable",
+    "best_case": "retail_personalization",
+    "worst_case": "bank_kc_automation"
+  }
+}
+```
+
+**Trend Detection Algorithm:**
+1. Split records for each phase into two halves by timestamp (older half, newer half).
+2. Compute average reward for each half.
+3. If newer_avg - older_avg > 0.15 -> "improving"
+4. If older_avg - newer_avg > 0.15 -> "degrading"
+5. Otherwise -> "stable"
+6. Minimum 4 records required for trend detection; otherwise "insufficient_data".
+
+### Step 3: Per-Domain Reward Averages
+
+Group records by `domain` and compute:
+
+```json
+{
+  "banking": {
+    "avg_reward": 0.72,
+    "total_runs": 18,
+    "phase_breakdown": {
+      "phase-0": 0.85,
+      "phase-1": 0.90,
+      "phase-2": 0.55,
+      "phase-2.5": 0.70,
+      "phase-3": 0.65,
+      "phase-4": 0.80,
+      "phase-5": 0.72
+    },
+    "bottleneck_phase": "phase-2",
+    "strongest_phase": "phase-1"
+  }
+}
+```
+
+**Bottleneck Detection:**
+- Phase with the lowest average reward in a domain is flagged as `bottleneck_phase`.
+- Phase with the highest average reward is flagged as `strongest_phase`.
+- Only computed if domain has 3+ records.
+
+### Step 4: Per-Skill Effectiveness
+
+Group records by `skill_used` and cross-reference with domain:
+
+```json
+{
+  "goap-research-ed25519": {
+    "overall_avg": 0.74,
+    "total_runs": 15,
+    "by_domain": {
+      "banking": { "avg": 0.65, "runs": 8 },
+      "retail": { "avg": 0.85, "runs": 7 }
+    },
+    "best_domain": "retail",
+    "worst_domain": "banking"
+  }
+}
+```
+
+### Step 5: Domain Pattern Detection
+
+Analyze accumulated data to detect actionable patterns. Each pattern has a confidence score based on evidence count.
+
+**Pattern Detection Rules:**
+
+| Rule | Condition | Pattern Template |
+|------|-----------|-----------------|
+| Phase Bottleneck | Phase avg < 0.5 in domain, 3+ records | "{domain} cases struggle in {phase} (avg reward: {avg})" |
+| Phase Excellence | Phase avg > 0.9 in domain, 3+ records | "{domain} cases excel in {phase} (avg reward: {avg})" |
+| Skill-Domain Mismatch | Skill avg < 0.5 in domain but > 0.7 in another | "{skill} underperforms in {domain} vs {other_domain}" |
+| Improving Trend | Trend = "improving" for phase in domain | "{phase} quality is improving in {domain} domain" |
+| Degrading Trend | Trend = "degrading" for phase in domain | "{phase} quality is degrading in {domain} -- investigate" |
+| Time Overhead | Phase avg iterations > 2.0 in domain | "{domain} cases require more iterations in {phase}" |
+
+**Confidence Calculation:**
+```
+confidence = min(1.0, evidence_count / 10)
+```
+Where `evidence_count` is the number of records supporting the pattern. Confidence reaches 1.0 at 10+ supporting records.
+
+### Step 6: Write Outputs
+
+#### reward-summary.json
+
+Write to `.keysarium/memory/_stats/reward-summary.json`:
+
+```json
+{
+  "version": "1.0",
+  "generated_at": "2026-03-01T14:00:00Z",
+  "total_records": 42,
+  "total_domains": 3,
+  "total_cases": 8,
+  "phase_averages": { ... },
+  "domain_averages": { ... },
+  "skill_effectiveness": { ... },
+  "overall_average": 0.76,
+  "overall_trend": "improving"
+}
+```
+
+#### domain-patterns.json
+
+Write to `.keysarium/memory/_patterns/domain-patterns.json`:
+
+```json
+{
+  "version": "1.0",
+  "generated_at": "2026-03-01T14:00:00Z",
+  "patterns": [
+    {
+      "pattern_id": "banking-phase2-bottleneck",
+      "domain": "banking",
+      "description": "Banking cases struggle in Phase 2 (Research) with average reward 0.55",
+      "category": "phase_bottleneck",
+      "confidence": 0.80,
+      "evidence_count": 8,
+      "detected_at": "2026-03-01T14:00:00Z",
+      "examples": ["bank_kc_automation", "bank_loan_approval"],
+      "actionable_advice": "Allocate 20% extra time for Phase 2 in banking cases. Consider pre-loading regulatory templates."
+    },
+    {
+      "pattern_id": "retail-triz-effective",
+      "domain": "retail",
+      "description": "TRIZ methodology produces better results than Game Theory for retail problem-solving",
+      "category": "skill_effectiveness",
+      "confidence": 0.60,
+      "evidence_count": 6,
+      "detected_at": "2026-03-01T14:00:00Z",
+      "examples": ["ecom_personalization", "retail_inventory"],
+      "actionable_advice": "Prefer TRIZ framework over Game Theory for retail domain cases in Phase 3."
+    }
+  ]
+}
+```
+
+## Display Format for /learning-stats
+
+### Phase Averages Table
+
+```
+Phase Reward Averages (42 records, 8 cases)
+───────────────────────────────────────────
+Phase       | Avg    | Runs | Trend       |
+────────────|────────|──────|─────────────|
+Phase 0     | 0.85   | 8    | stable      |
+Phase 1     | 0.92   | 8    | improving   |
+Phase 2     | 0.65   | 7    | stable      |
+Phase 2.5   | 0.78   | 6    | improving   |
+Phase 3     | 0.71   | 5    | stable      |
+Phase 4     | 0.89   | 4    | stable      |
+Phase 5     | 0.74   | 4    | stable      |
+────────────|────────|──────|─────────────|
+Overall     | 0.76   | 42   | improving   |
+```
+
+### Domain Breakdown Table
+
+```
+Domain Breakdown
+───────────────────────────────────────
+Domain      | Avg    | Cases | Bottleneck  |
+────────────|────────|───────|─────────────|
+Banking     | 0.72   | 3     | Phase 2     |
+Retail      | 0.82   | 3     | Phase 5     |
+Enterprise  | 0.69   | 2     | Phase 3     |
+```
+
+### Detected Patterns
+
+```
+Detected Patterns (confidence > 0.5)
+──────────────────────────────────────────────────────
+1. [0.80] Banking cases struggle in Phase 2 (Research)
+   Advice: Allocate 20% extra time for Phase 2 in banking cases
+
+2. [0.60] TRIZ outperforms Game Theory for retail problem-solving
+   Advice: Prefer TRIZ framework for retail domain in Phase 3
+
+3. [0.55] Phase 1 quality is improving across all domains
+   Advice: Current exploration approach is working well
+```
+
+### Skill Effectiveness Table
+
+```
+Skill Effectiveness
+────────────────────────────────────────────────────
+Skill                          | Avg  | Best Domain |
+───────────────────────────────|──────|─────────────|
+explore                        | 0.92 | retail      |
+goap-research-ed25519          | 0.74 | retail      |
+problem-solver-enhanced        | 0.71 | enterprise  |
+reverse-engineering-unicorn    | 0.85 | banking     |
+presentation-storyteller       | 0.74 | retail      |
+```
+
+## Empty State
+
+When no records exist yet:
+
+```
+Learning Stats
+──────────────
+No reward data found in .keysarium/memory/
+
+To start collecting data:
+1. Run a case with /casarium
+2. Respond at each checkpoint
+3. Rewards are automatically tracked
+
+Memory directory: .keysarium/memory/ (will be created on first run)
+```
+
+## Modular Reuse
+
+This tracker is domain-agnostic. It works with any RewardRecord JSON that conforms to the schema defined in `lib/memory-protocol.md`. The pattern detection rules can be extended by adding entries to the Pattern Detection Rules table.