@dzhechkov/keysarium 1.1.2 → 1.2.0

package/templates/lib/judge-attestation.md

@@ -0,0 +1,322 @@
+# Judge Attestation Protocol
+
+> Cryptographic proof of BTO judge isolation via SHA-256 hash chain attestations.
+
+## Purpose
+
+This protocol defines how BTO judges (Domain Expert, Critic, Completeness Auditor) create cryptographic attestations proving their evaluations were performed independently. Each judge records a hash of its evaluation before seeing other judges' scores. The attestations are chained to provide ordering proof.
+
+## Constants
+
+```
+NULL_HASH = "0000000000000000000000000000000000000000000000000000000000000000"
+ATTESTATION_FILE = ".judge-attestations.json"
+HASH_PREFIX = "sha256:"
+STANDARD_PANEL_SIZE = 3
+HIGH_STAKES_PANEL_SIZE = 5
+```
+
+## Section 1: Attestation Creation
+
+### Hash Input Construction
+
+Each judge's evaluation hash is computed from a deterministic concatenation of:
+
+```
+evaluation_hash = SHA-256(judge_id + "|" + artifact_hash + "|" + score + "|" + rationale_summary)
+```
+
+The pipe character `|` serves as a delimiter to prevent ambiguity in concatenation.
+
+**Fields:**
+- `judge_id`: One of `"domain-expert"`, `"critic"`, `"completeness-auditor"` (or `"meta-judge"` for escalation)
+- `artifact_hash`: SHA-256 hash of the artifact being evaluated (computed before evaluation starts)
+- `score`: The numeric score as a string with one decimal place (e.g., `"8.2"`)
+- `rationale_summary`: First 500 characters of the judge's rationale text, trimmed of leading/trailing whitespace
+
+### Computing the Artifact Hash
+
+Before any judge starts evaluation, compute the artifact hash:
+
+```bash
+ARTIFACT_HASH=$(${SHA_CMD} "path/to/artifact.md" | awk '{print $1}')
+```
+
+This hash is shared with all judges and recorded in each attestation. It proves all judges evaluated the same artifact.
+
+### Computing the Evaluation Hash
+
+After a judge completes its evaluation:
+
+```bash
+JUDGE_ID="domain-expert"
+ARTIFACT_HASH="<computed above>"
+SCORE="8.2"
+RATIONALE_SUMMARY="<first 500 chars of rationale>"
+
+EVAL_HASH=$(printf '%s' "${JUDGE_ID}|${ARTIFACT_HASH}|${SCORE}|${RATIONALE_SUMMARY}" | ${SHA_CMD} | awk '{print $1}')
+```
+
+**Important:** The rationale_summary must be trimmed to exactly 500 characters (or fewer if the rationale is shorter) to ensure deterministic reproduction during verification.
+
+## Section 2: Chain Linking
+
+### Attestation Order
+
+Judges are recorded in a fixed order within each evaluation round:
+
+1. Domain Expert (first, previous = NULL_HASH)
+2. Critic (second, previous = Domain Expert's evaluation_hash)
+3. Completeness Auditor (third, previous = Critic's evaluation_hash)
+
+For a 5-judge high-stakes panel:
+4. Additional Expert (fourth, previous = Auditor's evaluation_hash)
+5. Tiebreaker (fifth, previous = Additional Expert's evaluation_hash)
+
+### Chain Link Protocol
+
+```bash
+# Judge 1 (Domain Expert)
+PREV_ATTESTATION_HASH="${NULL_HASH}"
+# ... compute evaluation_hash_1 ...
+# Record attestation with previous = NULL_HASH
+
+# Judge 2 (Critic)
+PREV_ATTESTATION_HASH="${EVAL_HASH_1}"
+# ... compute evaluation_hash_2 ...
+# Record attestation with previous = evaluation_hash_1
+
+# Judge 3 (Completeness Auditor)
+PREV_ATTESTATION_HASH="${EVAL_HASH_2}"
+# ... compute evaluation_hash_3 ...
+# Record attestation with previous = evaluation_hash_2
+```
+
+### Ordering Note
+
+The chain records the ORDER in which attestations were finalized, not the order in which judges started evaluating. Since judges evaluate in parallel but record sequentially, the chain proves:
+- Each attestation was recorded after the previous one
+- The evaluation_hash was computed from the judge's OWN data only
+- The previous_attestation_hash links to the preceding record (not to the preceding judge's score)
+
+## Section 3: Isolation Verification
+
+### Verification Algorithm
+
+```
+1. Load .judge-attestations.json
+2. For each evaluation round:
+   a. Verify artifact_hash matches across all attestations
+   b. For each attestation (index i):
+      i.   Reconstruct evaluation_hash from (judge_id, artifact_hash, score, rationale_summary)
+      ii.  Compare reconstructed hash with stored evaluation_hash
+      iii. If i == 0: verify previous_attestation_hash == NULL_HASH
+      iv.  If i > 0: verify previous_attestation_hash == attestations[i-1].evaluation_hash
+      v.   Verify timestamp > attestations[i-1].timestamp (if i > 0)
+3. Produce verification report
+```
+
+### Isolation Proof Logic
+
+The isolation proof works as follows:
+
+1. **Hash Independence:** Each evaluation_hash is computed from `judge_id|artifact_hash|score|rationale`. If a judge had seen another judge's score, it would not affect its own hash computation -- but it would be detectable if the rationale text references specific scores from other judges.
+
+2. **Chain Integrity:** The previous_attestation_hash links attestations in order but does NOT include other judges' scores in the hash input. This means the chain proves ORDER but the evaluation content is provably independent.
+
+3. **Timestamp Monotonicity:** Timestamps must be strictly increasing. If Judge B's timestamp is BEFORE Judge A's, but Judge B's previous_attestation_hash points to Judge A, then something is wrong.
+
+### Verification Script
+
+```bash
+python3 << 'VERIFY_ATTESTATION'
+import json, subprocess, sys
+
+NULL_HASH = "0" * 64
+
+def sha256(content):
+    result = subprocess.run(
+        ["sha256sum"],
+        input=content.encode(),
+        capture_output=True
+    )
+    if result.returncode != 0:
+        result = subprocess.run(
+            ["shasum", "-a", "256"],
+            input=content.encode(),
+            capture_output=True
+        )
+    return result.stdout.decode().split()[0]
+
+DIR = sys.argv[1] if len(sys.argv) > 1 else "."
+
+with open(f"{DIR}/.judge-attestations.json") as f:
+    data = json.load(f)
+
+for eval_round in data.get("evaluations", [data]):
+    attestations = eval_round.get("attestations", [])
+    artifact_hash = eval_round.get("artifact_hash", "")
+    violations = []
+
+    for i, att in enumerate(attestations):
+        # Reconstruct evaluation hash
+        hash_input = f"{att['judge_id']}|{artifact_hash}|{att['score']}|{att.get('rationale_summary', '')}"
+        expected = sha256(hash_input)
+        actual = att["evaluation_hash"].replace("sha256:", "")
+
+        if expected != actual:
+            violations.append(f"Judge {att['judge_id']}: evaluation_hash mismatch")
+
+        # Verify chain link
+        if i == 0:
+            expected_prev = NULL_HASH
+        else:
+            expected_prev = attestations[i-1]["evaluation_hash"].replace("sha256:", "")
+
+        actual_prev = att["previous_attestation_hash"].replace("sha256:", "")
+        if expected_prev != actual_prev:
+            violations.append(f"Judge {att['judge_id']}: chain link broken")
+
+    if not violations:
+        print(f"PASS: All {len(attestations)} judge attestations verified. Isolation confirmed.")
+    else:
+        print(f"FAIL: {len(violations)} violations detected:")
+        for v in violations:
+            print(f"  - {v}")
+
+VERIFY_ATTESTATION
+```
+
+## Section 4: File Format
+
+### .judge-attestations.json Schema
+
+```json
+{
+  "evaluations": [
+    {
+      "evaluation_id": "string — unique ID for this evaluation round",
+      "artifact_path": "string — path to the evaluated artifact",
+      "artifact_hash": "string — sha256:<hex> of the artifact content",
+      "panel_size": "integer — 3 (standard) or 5 (high-stakes)",
+      "started_at": "ISO-8601 — when evaluation round began",
+      "completed_at": "ISO-8601 — when last attestation recorded",
+      "attestations": [
+        {
+          "judge_id": "string — domain-expert|critic|completeness-auditor",
+          "score": "float — 0.0-10.0",
+          "rationale_summary": "string — first 500 chars of rationale",
+          "evaluation_hash": "string — sha256:<hex>",
+          "timestamp": "ISO-8601 — when attestation was recorded",
+          "previous_attestation_hash": "string — sha256:<hex> or null hash"
+        }
+      ],
+      "final_score": "float — weighted average",
+      "weights": {
+        "domain-expert": 0.4,
+        "critic": 0.3,
+        "completeness-auditor": 0.3
+      }
+    }
+  ]
+}
+```
+
+### Example Attestation File
+
+```json
+{
+  "evaluations": [
+    {
+      "evaluation_id": "bto-eval-2026-03-01T12:00:00Z",
+      "artifact_path": ".claude/skills/explore/SKILL.md",
+      "artifact_hash": "sha256:abc123def456789012345678901234567890123456789012345678901234fedc",
+      "panel_size": 3,
+      "started_at": "2026-03-01T12:00:00Z",
+      "completed_at": "2026-03-01T12:01:45Z",
+      "attestations": [
+        {
+          "judge_id": "domain-expert",
+          "score": 8.2,
+          "rationale_summary": "Strong SKILL.md with clear protocol steps. References directory provides good examples...",
+          "evaluation_hash": "sha256:111222333444555666777888999000aaabbbcccdddeeefff000111222333444555",
+          "timestamp": "2026-03-01T12:00:30Z",
+          "previous_attestation_hash": "sha256:0000000000000000000000000000000000000000000000000000000000000000"
+        },
+        {
+          "judge_id": "critic",
+          "score": 7.5,
+          "rationale_summary": "Missing edge case handling for multi-language inputs. Error recovery protocol unclear...",
+          "evaluation_hash": "sha256:222333444555666777888999000aaabbbcccdddeeefff000111222333444555666",
+          "timestamp": "2026-03-01T12:01:00Z",
+          "previous_attestation_hash": "sha256:111222333444555666777888999000aaabbbcccdddeeefff000111222333444555"
+        },
+        {
+          "judge_id": "completeness-auditor",
+          "score": 8.0,
+          "rationale_summary": "All required sections present. References directory has 3 examples. Missing: performance benchmarks...",
+          "evaluation_hash": "sha256:333444555666777888999000aaabbbcccdddeeefff000111222333444555666777",
+          "timestamp": "2026-03-01T12:01:30Z",
+          "previous_attestation_hash": "sha256:222333444555666777888999000aaabbbcccdddeeefff000111222333444555666"
+        }
+      ],
+      "final_score": 7.94,
+      "weights": {
+        "domain-expert": 0.4,
+        "critic": 0.3,
+        "completeness-auditor": 0.3
+      }
+    }
+  ]
+}
+```
+
+## Section 5: Integration with BTO Pipeline
+
+### When to Create Attestations
+
+Attestations are created during **BTO Layer 2 evaluation** (the judge panel stage):
+
+1. **Before panel starts:** Compute `artifact_hash` of the artifact being evaluated
+2. **After each judge completes:** Create attestation record with evaluation_hash
+3. **After all judges complete:** Write `.judge-attestations.json`
+4. **If meta-judge is invoked:** Add a 4th attestation with `judge_id: "meta-judge"`
+
+### Integration Points
+
+| BTO Stage | Attestation Action |
+|-----------|-------------------|
+| Layer 0 (structural) | No attestation needed (deterministic checks) |
+| Layer 1 (semantic) | No attestation needed (single haiku agent) |
+| Layer 2 (judge panel) | Create attestation set with 3 attestations |
+| Meta-judge (escalation) | Append meta-judge attestation to the set |
+| Optimization rounds | Create new attestation set per round's final evaluation |
+
+### Disagreement Detection Enhancement
+
+With attestations, disagreement detection gains cryptographic backing:
+
+```
+If max_score - min_score > 3.0:
+  1. Verify all attestations are valid (no tampering)
+  2. Verify isolation (no judge influenced another)
+  3. If isolation verified: escalate to meta-judge (genuine disagreement)
+  4. If isolation violated: flag conformity collapse warning
+```
+
+## Section 6: Meta-Judge Attestation
+
+When the meta-judge is invoked (disagreement > 3 points), it creates its own attestation:
+
+```json
+{
+  "judge_id": "meta-judge",
+  "score": 7.8,
+  "rationale_summary": "Disagreement between domain-expert (8.5) and critic (5.2) on dimension 'completeness'...",
+  "evaluation_hash": "sha256:...",
+  "timestamp": "2026-03-01T12:02:00Z",
+  "previous_attestation_hash": "sha256:<last judge's eval hash>"
+}
+```
+
+The meta-judge's rationale MAY reference other judges' scores (it has access to them for arbitration). This is expected and does not violate isolation -- the meta-judge is explicitly a synthesizer, not an independent evaluator.

package/templates/lib/memory-protocol.md

@@ -0,0 +1,239 @@
+# Memory Protocol -- Reward-Calibrated Learning
+
+Core protocol for persistent memory in the Keysarium pipeline. Provides `memory_query()` before tasks and `memory_store()` after tasks.
+
+## Memory Namespace
+
+All memory files live in `.keysarium/memory/`:
+
+```
+.keysarium/memory/
+├── config.json                                    ← Global configuration
+├── _patterns/
+│   └── domain-patterns.json                       ← Detected domain patterns
+├── _stats/
+│   └── reward-summary.json                        ← Aggregate statistics
+├── {domain}/                                      ← banking | retail | enterprise | healthcare
+│   └── {case-slug}/
+│       └── {phase}_{timestamp}.json               ← Individual reward records
+```
+
+## Configuration
+
+### config.json (auto-created with defaults on first access)
+
+```json
+{
+  "version": "1.0",
+  "retention_days": 90,
+  "max_results_per_query": 10,
+  "enabled": true,
+  "known_domains": ["banking", "retail", "enterprise", "healthcare"],
+  "reward_levels": {
+    "excellent": 1.0,
+    "good": 0.7,
+    "needs_work": 0.3,
+    "failed": 0.0
+  }
+}
+```
+
+## Protocol: memory_query(context)
+
+Call at the **start** of each pipeline phase to load relevant historical patterns.
+
+### Input
+
+```json
+{
+  "phase": "phase-2",
+  "domain": "banking",
+  "slug": "bank_kc_automation",
+  "skill": "goap-research-ed25519"
+}
+```
+
+### Algorithm
+
+1. **Check enabled:** Read `.keysarium/memory/config.json`. If `enabled` is false or directory does not exist, return empty list.
+2. **Resolve path:** Construct `.keysarium/memory/{domain}/` (scan all slugs, not just current).
+3. **Scan records:** Read all `{phase}_*.json` files matching the requested phase across all slugs in the domain.
+4. **Filter expired:** Exclude records where `expires_at < current_date`.
+5. **Sort:** By `reward` DESC, then `timestamp` DESC.
+6. **Limit:** Return top `max_results_per_query` records (default 10).
+7. **Enrich:** Also load `.keysarium/memory/_patterns/domain-patterns.json` for matching domain patterns.
+
+### Output
+
+```json
+{
+  "records": [
+    {
+      "case_slug": "bank_loan_approval",
+      "phase": "phase-2",
+      "reward": 1.0,
+      "reward_label": "excellent",
+      "skill_used": "goap-research-ed25519",
+      "outcome_summary": "Research completed with all claims verified...",
+      "timestamp": "2026-02-15T14:30:00Z"
+    }
+  ],
+  "patterns": [
+    {
+      "pattern_id": "banking-phase2-slow",
+      "description": "Banking cases take 2x longer in Phase 2 due to regulatory research",
+      "confidence": 0.85,
+      "actionable_advice": "Allocate extra time budget for Phase 2 in banking domain"
+    }
+  ],
+  "count": 3,
+  "domain": "banking"
+}
+```
+
+### Usage in Phase
+
+After calling `memory_query()`, the agent should:
+1. Log: "Loaded {count} historical patterns for {phase} in {domain} domain"
+2. If `records` is non-empty, review the top 3 records for relevant approaches
+3. If `patterns` is non-empty, apply actionable advice to current phase execution
+4. If both are empty (first run), proceed normally
+
+## Protocol: memory_store(result, reward)
+
+Call at each **checkpoint** after the user responds, to persist the phase outcome with a reward score.
+
+### Input
+
+```json
+{
+  "case_slug": "bank_kc_automation",
+  "domain": "banking",
+  "phase": "phase-2",
+  "phase_name": "Research",
+  "skill_used": "goap-research-ed25519",
+  "reward": 0.7,
+  "reward_label": "good",
+  "reward_reason": "User requested minor edits to competitor analysis section",
+  "context": {
+    "phase_number": 2,
+    "domain_detected": "banking",
+    "upstream_promises": ["DISCOVERY_COMPLETE", "CASE_EXPLORED"],
+    "patterns_loaded": 3,
+    "time_budget_pct": 15.0,
+    "agent_count": 3
+  },
+  "outcome": {
+    "artifacts_created": ["02_research_findings.md"],
+    "checkpoint_response": "ok, but expand the FinTech competitor section",
+    "iterations": 2,
+    "promise_emitted": "RESEARCH_PARANOID_PASSED"
+  }
+}
+```
+
+### Algorithm
+
+1. **Ensure directory exists:** Create `.keysarium/memory/{domain}/{slug}/` if it does not exist.
+2. **Build record:** Construct full RewardRecord JSON from input.
+3. **Compute expires_at:** `current_date + retention_days` (from config, default 90 days).
+4. **Generate filename:** `{phase}_{ISO-timestamp}.json` (e.g., `phase-2_2026-03-01T12-30-00.json`).
+5. **Write file:** Write JSON to `.keysarium/memory/{domain}/{slug}/{filename}`.
+6. **Log:** "Stored reward {reward} ({reward_label}) for {phase} of {slug}"
+
+### RewardRecord JSON Schema
+
+```json
+{
+  "id": "bank_kc_automation_phase-2_2026-03-01T12-30-00",
+  "version": "1.0",
+  "timestamp": "2026-03-01T12:30:00Z",
+  "case_slug": "bank_kc_automation",
+  "domain": "banking",
+  "phase": "phase-2",
+  "phase_name": "Research",
+  "skill_used": "goap-research-ed25519",
+  "reward": 0.7,
+  "reward_label": "good",
+  "reward_reason": "User requested minor edits to competitor analysis section",
+  "context": {
+    "phase_number": 2,
+    "domain_detected": "banking",
+    "upstream_promises": ["DISCOVERY_COMPLETE", "CASE_EXPLORED"],
+    "patterns_loaded": 3,
+    "time_budget_pct": 15.0,
+    "agent_count": 3
+  },
+  "outcome": {
+    "artifacts_created": ["02_research_findings.md"],
+    "checkpoint_response": "ok, but expand the FinTech competitor section",
+    "iterations": 2,
+    "promise_emitted": "RESEARCH_PARANOID_PASSED"
+  },
+  "promise_tag": "RESEARCH_PARANOID_PASSED",
+  "expires_at": "2026-05-30T12:30:00Z"
+}
+```
+
+## Reward Assignment Rules
+
+The reward score is determined by the user's response at the checkpoint:
+
+| User Behavior | Reward | Label | Detection |
+|---------------|--------|-------|-----------|
+| Says "ok" / "ок" / proceeds to next phase immediately | 1.0 | excellent | Exact match or single-word approval |
+| Requests minor adjustments ("углуби X", small edits to one section) | 0.7 | good | Feedback is scoped to one area, does not change direction |
+| Requests significant rework (multiple sections, changed approach, re-research) | 0.3 | needs_work | Feedback affects multiple areas or changes phase direction |
+| Restarts phase entirely / says result is unusable / requests complete redo | 0.0 | failed | Phase restarts from scratch |
+
+### Edge Cases
+
+- **"углуби [section]"** = 0.7 (deepening is enhancement, not failure)
+- **Multiple rounds of minor feedback** = 0.7 on first round, 0.3 if third+ round
+- **Positive feedback with minor note** ("great, just fix the typo in section 3") = 1.0
+- **No explicit response** (session ends) = do not store (no record created)
+
+## Purge Protocol
+
+To prevent unbounded growth, expired records should be cleaned up:
+
+1. **Trigger:** At each `memory_query()` call, check for expired records
+2. **Scan:** Within the queried domain directory, find records where `expires_at < current_date`
+3. **Delete:** Remove expired JSON files
+4. **Log:** "Purged {count} expired records from {domain}"
+
+## Error Handling
+
+| Error | Behavior |
+|-------|----------|
+| `.keysarium/memory/` does not exist | `memory_query()` returns empty; `memory_store()` creates directory |
+| `config.json` missing | Use defaults (90 days, 10 results, enabled) |
+| Malformed JSON file | Skip that record, log warning, continue |
+| Write fails (permissions, disk) | Log error, continue pipeline without storing |
+| Domain not in `known_domains` | Use "unknown" as domain directory |
+
+## Integration with Brain Export
+
+When `/brain-export` runs, it should include a `"reward_data"` section:
+
+```json
+{
+  "reward_data": {
+    "total_records": 42,
+    "domains": ["banking", "retail"],
+    "phase_averages": {
+      "phase-0": 0.85,
+      "phase-1": 0.92,
+      "phase-2": 0.65,
+      "phase-2.5": 0.78,
+      "phase-3": 0.71,
+      "phase-4": 0.89,
+      "phase-5": 0.74
+    },
+    "top_patterns": [],
+    "exported_from": ".keysarium/memory/"
+  }
+}
+```
+
+Individual records are NOT exported (too voluminous). Only aggregates and patterns are included.

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