@dzhechkov/keysarium 1.1.2 → 1.3.0

package/templates/lib/platform-adapters.md

@@ -0,0 +1,100 @@
+# Platform Adapter Definitions
+
+Central registry for multi-platform support. Maps each supported AI coding platform to its configuration format, output paths, and translation strategy.
+
+## Supported Platforms
+
+| Platform | Template | Config Format | Output Structure |
+|----------|----------|---------------|------------------|
+| Cursor | `lib/platform-templates/cursor.md` | Single `.cursorrules` file + optional `.cursor/skills/` | Flat rules file with inlined skills |
+| OpenCode | `lib/platform-templates/opencode.md` | `.opencode/` directory with `config.yaml` + skill files | Directory hierarchy matching `.claude/` |
+| GitHub Copilot | `lib/platform-templates/copilot.md` | `.github/copilot-instructions.md` single file | Single markdown file with all instructions |
+
+## Platform Details
+
+### Cursor
+
+| Property | Value |
+|----------|-------|
+| Config file | `.cursorrules` (project root) |
+| Format | Plain text / TOML-style rules |
+| Skills directory | `.cursor/skills/` (optional, one file per skill) |
+| Rules handling | All rules concatenated into `.cursorrules` under sections |
+| Skill handling | Key instructions extracted from SKILL.md and inlined; large skills get separate files in `.cursor/skills/` |
+| Max config size | Recommended < 10,000 tokens |
+| Platform docs | Cursor uses `.cursorrules` for project-level AI instructions |
+
+### OpenCode
+
+| Property | Value |
+|----------|-------|
+| Config directory | `.opencode/` (project root) |
+| Config file | `.opencode/config.yaml` |
+| Skills directory | `.opencode/skills/` (one `.md` file per skill) |
+| Rules directory | `.opencode/rules/` (one `.md` file per rule) |
+| Rules handling | Each rule file copied with format adaptation |
+| Skill handling | Each skill gets its own markdown file with instructions |
+| Platform docs | OpenCode uses directory-based configuration |
+
+### GitHub Copilot
+
+| Property | Value |
+|----------|-------|
+| Config file | `.github/copilot-instructions.md` |
+| Format | Single markdown file |
+| Skills handling | All skills summarized into sections within the file |
+| Rules handling | All rules merged into the instructions file |
+| Max config size | Recommended < 8,000 tokens (Copilot context window considerations) |
+| Platform docs | GitHub Copilot reads `.github/copilot-instructions.md` for custom instructions |
+
+## Translation Strategy
+
+### Source Structure (`.claude/`)
+
+```
+.claude/
+├── skills/
+│   ├── explore/SKILL.md
+│   ├── goap-research-ed25519/SKILL.md
+│   ├── problem-solver-enhanced/SKILL.md
+│   ├── frontend-design/SKILL.md
+│   ├── presentation-storyteller/SKILL.md
+│   ├── reverse-engineering-unicorn/SKILL.md
+│   ├── bto/SKILL.md
+│   └── feature-adr/SKILL.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
+└── commands/
+    └── *.md
+```
+
+### Translation Rules
+
+1. **Skills:** Read each `SKILL.md`, extract the core protocol/instructions section. For single-file platforms (Cursor, Copilot), summarize to key points. For directory-based platforms (OpenCode), preserve full content.
+
+2. **Rules:** Read each rule file. For single-file platforms, merge all rules under a unified "Rules" section with subsections. For directory-based platforms, create one file per rule.
+
+3. **Commands:** Commands are Claude Code-specific and generally not translatable. Include a note in generated configs pointing users to the `.claude/commands/` directory for reference.
+
+4. **Shards:** Governance shards (`.claude/shards/`) are pipeline-specific. Include them as supplementary context in platforms that support directory structures; omit from single-file platforms.
+
+## Adding a New Platform
+
+To add support for a new platform:
+
+1. Create `lib/platform-templates/<platform-name>.md` following the template pattern
+2. Add an entry to the "Supported Platforms" table above
+3. Add a "Platform Details" section with config format, paths, and constraints
+4. Update `/init-platform` command's `--platform` argument to include the new name
+5. Test generation with the new platform

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