@dzhechkov/keysarium 1.0.1 → 1.1.1

package/README.md

@@ -2,7 +2,7 @@
 
 **AI Case Research Toolkit for Claude Code**
 
-Full 7-phase pipeline for AI case studies, hackathons, and casariums. Provides skills, commands, rules, agent templates, and hooks for [Claude Code](https://docs.anthropic.com/en/docs/claude-code).
+Full 7-phase pipeline for AI case studies, hackathons, and casariums. Provides skills, commands, rules, shards, agent templates, and brain portability for [Claude Code](https://docs.anthropic.com/en/docs/claude-code).
 
 ---
 
@@ -29,12 +29,12 @@ After installation, open Claude Code in your project directory and start using s
 | Component | Count | Description |
 |-----------|-------|-------------|
 | **Skills** | 6 | `explore`, `frontend-design`, `goap-research`, `presentation-storyteller`, `problem-solver`, `reverse-engineering` |
-| **Commands** | 11 | `/casarium`, `/new-research`, `/parallel-research`, `/discovery`, `/explore-case`, `/research`, `/cjm-prototype`, `/solve`, `/architecture-phase`, `/presentation`, `/harvest` |
-| **Rules** | 7 | `research-quality`, `checkpoint-protocol`, `agent-swarm`, `domain-specific`, `anti-patterns`, `file-conventions`, `modular-reuse` |
+| **Commands** | 13 | `/casarium`, `/new-research`, `/parallel-research`, `/discovery`, `/explore-case`, `/research`, `/cjm-prototype`, `/solve`, `/architecture-phase`, `/presentation`, `/harvest`, `/brain-export`, `/brain-import` |
+| **Rules** | 10 | `research-quality`, `checkpoint-protocol`, `agent-swarm`, `domain-specific`, `anti-patterns`, `file-conventions`, `modular-reuse`, `feedback-loops`, `model-routing`, `trust-tiers` |
+| **Shards** | 8 | Context shards for each phase: `phase-0-discovery`, `phase-1-explore`, `phase-2-research`, `phase-25-cjm`, `phase-3-solve`, `phase-4-architecture`, `phase-5-presentation`, `bto-evaluation` |
 | **Agent Templates** | 5 | `discovery-worker`, `research-worker`, `cjm-variant-worker`, `presentation-worker`, `parallel-research-orchestrator` |
-| **Hooks** | 3 | PreToolUse validation, PostToolUse notifications, audit logging |
 | **Library** | 4 | `phase-utils`, `agent-patterns`, `skill-loader`, `domain-templates` |
-| **Documentation** | 6 | Deployment, admin, user guide, infrastructure, architecture, flows |
+| **Documentation** | 12 | Deployment, admin, user guide, infrastructure, architecture, flows (for Keysarium and BTO) |
 
 Everything is installed into your project's `.claude/` directory and works natively with Claude Code.
 
@@ -266,6 +266,22 @@ After completing research, extract reusable patterns:
 
 The harvester reviews completed projects, identifies universal patterns, decontextualizes them, and updates `TOOLKIT_HARVEST.md`.
 
+### Brain Portability
+
+Export and import accumulated knowledge between projects:
+
+```bash
+# Export knowledge as a portable JSON container
+/brain-export
+
+# Import a brain container into another project
+/brain-import path/to/brain.json
+```
+
+### Context Shards
+
+Shards (`.claude/shards/`) are lightweight context fragments that phases load on demand. They keep the main CLAUDE.md lean while providing phase-specific instructions, semantic completion promises, and quality checklists.
+
 ---
 
 ## Requirements

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/keysarium",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "AI Case Research Toolkit for Claude Code — full 7-phase pipeline for AI case studies, hackathons, and casariums",
   "main": "src/cli.js",
   "bin": {

package/src/utils.js

@@ -218,13 +218,14 @@ function getTemplatesDir() {
 // ===========================================================================
 
 const COMPONENTS = {
-  skills:    { src: '.claude/skills',         label: 'Skills (6 skill packs)',           group: 'core' },
-  commands:  { src: '.claude/commands',        label: 'Commands (11 slash commands)',      group: 'core' },
-  rules:     { src: '.claude/rules',           label: 'Rules (7 auto-loaded rules)',      group: 'core' },
+  skills:    { src: '.claude/skills',         label: 'Skills (6 skill packs)',            group: 'core' },
+  commands:  { src: '.claude/commands',        label: 'Commands (13 slash commands)',      group: 'core' },
+  rules:     { src: '.claude/rules',           label: 'Rules (10 auto-loaded rules)',     group: 'core' },
+  shards:    { src: '.claude/shards',          label: 'Shards (7 context shards)',        group: 'core' },
   agents:    { src: '.claude/agents',          label: 'Agent templates (5 swarm configs)', group: 'core' },
   hooks:     { src: '.claude/settings.json',   label: 'Hooks configuration',              group: 'core', isFile: true },
   lib:       { src: 'lib',                     label: 'Library modules (4 modules)',       group: 'extended' },
-  docs:      { src: 'docs',                    label: 'Documentation (6 guides)',          group: 'docs' },
+  docs:      { src: 'docs',                    label: 'Documentation (12 guides)',         group: 'docs' },
   claude_md: { src: 'CLAUDE.md',               label: 'Master instructions',              group: 'core', isFile: true },
   harvest:   { src: 'TOOLKIT_HARVEST.md',      label: 'Knowledge harvest tracker',        group: 'core', isFile: true },
 };

package/templates/.claude/commands/brain-export.md

@@ -0,0 +1,121 @@
+---
+description: "Export accumulated knowledge as a portable brain container (JSON)"
+argument: "optional path to specific research directory, or 'all' for everything"
+---
+
+# Brain Export — Portable Knowledge Container
+
+Export accumulated knowledge, patterns, and evaluations into a portable JSON container
+that can be imported into other projects.
+
+## Protocol
+
+### Step 1: Scan Knowledge Sources
+
+Scan the following sources for exportable knowledge:
+1. `TOOLKIT_HARVEST.md` — harvested patterns and learnings
+2. `researches/*/` — all completed research directories
+3. `.claude/skills/*/SKILL.md` — skill metadata and trust tiers
+4. BTO evaluation reports (if any exist in researches)
+
+If `$ARGUMENTS` specifies a path, export only from that directory.
+If `$ARGUMENTS` is "all" or empty, export from all sources.
+
+### Step 2: Build Brain Container
+
+Construct a JSON structure:
+
+```json
+{
+  "version": "1.0",
+  "format": "keysarium-brain",
+  "exported_at": "[ISO 8601 timestamp]",
+  "source_project": "product-keysarium-2026",
+  "source_branch": "[current git branch]",
+
+  "skills": {
+    "[skill-name]": {
+      "trust_tier": 0-3,
+      "trust_tier_label": "Advisory|Structured|Validated|Verified",
+      "bto_score": null or float,
+      "last_evaluated": null or ISO date
+    }
+  },
+
+  "domain_patterns": {
+    "[domain]": {
+      "rules_applied": ["list of domain rules"],
+      "common_pitfalls": ["list"],
+      "successful_strategies": ["list"]
+    }
+  },
+
+  "research_summaries": [
+    {
+      "slug": "[case-slug]",
+      "domain": "[detected domain]",
+      "phases_completed": ["list of completed phases"],
+      "key_findings": ["top 3-5 findings"],
+      "chosen_cjm_variant": "A|B|C|D or null",
+      "presentation_score": null or float
+    }
+  ],
+
+  "harvest_patterns": [
+    {
+      "category": "skills|commands|rules|templates|patterns|snippets",
+      "name": "[pattern name]",
+      "description": "[what it does]",
+      "maturity": "beta|stable",
+      "used_in": ["project list"],
+      "content_hash": "[SHA-256 of content]"
+    }
+  ],
+
+  "pipeline_metrics": {
+    "total_cases_processed": 0,
+    "avg_phase_times": {},
+    "most_common_domain": null,
+    "bto_evaluations_run": 0
+  },
+
+  "metadata": {
+    "export_scope": "all|[specific path]",
+    "files_scanned": 0,
+    "patterns_extracted": 0
+  }
+}
+```
+
+### Step 3: Write Export File
+
+Write the JSON to: `keysarium-brain-[YYYY-MM-DD].json` in the project root.
+
+### Step 4: Generate Summary
+
+Display:
+```
+═══════════════════════════════════════════════════════
+Brain Export Complete
+
+File: keysarium-brain-[date].json
+Size: [file size]
+Skills exported: [N] (tiers: [breakdown])
+Research summaries: [N]
+Harvest patterns: [N]
+Domain patterns: [N domains]
+
+Import into another project:
+  /brain-import keysarium-brain-[date].json
+
+• "ок" — done
+• "покажи [section]" — preview section
+═══════════════════════════════════════════════════════
+```
+
+## Modular Reuse
+
+This export format is project-agnostic. Any multi-phase pipeline can:
+1. Define its own brain schema extending the base format
+2. Export domain-specific patterns
+3. Import patterns from other pipelines

package/templates/.claude/commands/brain-import.md

@@ -0,0 +1,115 @@
+---
+description: "Import a portable brain container into the current project"
+argument: "path to brain JSON file"
+---
+
+# Brain Import — Load External Knowledge
+
+Import a previously exported brain container to bootstrap knowledge in a new project.
+
+## Protocol
+
+### Step 1: Validate Brain File
+
+1. Read the JSON file from `$ARGUMENTS`
+2. Validate format:
+   - `version` field exists and is "1.0"
+   - `format` field is "keysarium-brain"
+   - Required sections present: `skills`, `harvest_patterns`, `metadata`
+3. If validation fails → show error and stop
+
+### Step 2: Selective Import
+
+Ask user what to import:
+
+```
+Brain file: [filename]
+Source project: [source_project]
+Exported: [exported_at]
+
+Available sections:
+  [1] Skills metadata ([N] skills) — trust tiers and BTO scores
+  [2] Domain patterns ([N] domains) — rules, pitfalls, strategies
+  [3] Research summaries ([N] cases) — findings and CJM choices
+  [4] Harvest patterns ([N] patterns) — reusable patterns and snippets
+  [5] Pipeline metrics — timing and performance data
+  [A] All sections
+
+Which sections to import? (comma-separated numbers or 'A' for all)
+```
+
+### Step 3: Merge Strategy
+
+For each imported section:
+
+**Skills metadata:**
+- Update trust_tier in SKILL.md files if imported tier is HIGHER than current
+- Never downgrade a tier
+- Log: "Skill [name]: tier [old] → [new] (from [source_project])"
+
+**Domain patterns:**
+- Append to existing domain knowledge (no overwrite)
+- Deduplicate by pattern name
+- Mark imported patterns with source: `[imported from: source_project, date]`
+
+**Research summaries:**
+- Store in `TOOLKIT_HARVEST.md` under "## Imported Research Summaries"
+- Read-only reference (don't create research directories)
+
+**Harvest patterns:**
+- Merge into `TOOLKIT_HARVEST.md`
+- Deduplicate by content_hash
+- Preserve maturity level from source
+
+**Pipeline metrics:**
+- Store as reference baseline
+- Don't overwrite current project metrics
+
+### Step 4: Write Import Log
+
+Create `brain-import-log-[YYYY-MM-DD].md` in project root:
+
+```markdown
+# Brain Import Log
+
+- Source: [filename]
+- Source project: [source_project]
+- Imported at: [timestamp]
+- Sections imported: [list]
+
+## Changes Made
+- [list of all changes with before/after]
+
+## Conflicts Resolved
+- [any deduplication or merge decisions]
+```
+
+### Step 5: Summary
+
+```
+═══════════════════════════════════════════════════════
+Brain Import Complete
+
+Source: [filename]
+Sections imported: [list]
+Skills updated: [N]
+Patterns merged: [N]
+Conflicts resolved: [N]
+
+Import log: brain-import-log-[date].md
+
+• "ок" — done
+• "покажи лог" — show full import log
+═══════════════════════════════════════════════════════
+```
+
+## Modular Reuse
+
+The import protocol handles:
+- Version compatibility checking
+- Selective import (user chooses sections)
+- Merge-not-overwrite strategy
+- Conflict resolution with logging
+- Audit trail via import log
+
+These patterns work for any knowledge transfer between projects.

package/templates/.claude/rules/checkpoint-protocol.md

@@ -7,14 +7,60 @@ Display a checkpoint banner and WAIT for user confirmation before proceeding.
 ```
 ═══════════════════════════════════════════════════════
 ⏸️ CHECKPOINT N: [Phase Name] Complete
+<promise>[PROMISE_TAG]</promise>
+
+[2-3 line summary of what was done]
+Files created: [list] ✅
+
+• "ок" — next phase
+• "углуби [section]" — elaborate
+• "[specific feedback]" — adjust
+═══════════════════════════════════════════════════════
+```
+
+## Semantic Completion Promises
+
+Each checkpoint MUST include the relevant promise tag to signal phase completion status.
+Promises are machine-readable markers that formalize phase gates.
+
+### Promise Tags by Phase
+
+| Phase | Promise Tag | Meaning |
+|-------|------------|---------|
+| Phase 0 | `<promise>DISCOVERY_COMPLETE</promise>` | JTBD + competitors + ROI analyzed |
+| Phase 1 | `<promise>CASE_EXPLORED</promise>` | Case fully understood, brief created |
+| Phase 2 | `<promise>RESEARCH_PARANOID_PASSED</promise>` | All claims verified, zero unverified |
+| Phase 2.5 | `<promise>CJM_VALIDATED</promise>` | CJM prototype created and variant chosen |
+| Phase 3 | `<promise>SOLUTION_DESIGNED</promise>` | Solution strategy formulated |
+| Phase 4 | `<promise>ARCHITECTURE_DEFINED</promise>` | C4 diagrams + sequence flows ready |
+| Phase 5 | `<promise>PRESENTATION_READY</promise>` | All 4 artifacts (05-08) created |
+| BTO L0 | `<promise>BTO_LAYER0_PASSED</promise>` | Deterministic checks passed |
+| BTO L2 | `<promise>BTO_LAYER2_SCORED</promise>` | Panel of 3 judges scored artifact |
+| BTO Opt | `<promise>BTO_OPTIMIZED</promise>` | Optimization converged |
+
+### Enhanced Checkpoint Format
+
+```
+═══════════════════════════════════════════════════════
+⏸️ CHECKPOINT N: [Phase Name] Complete
+<promise>[PROMISE_TAG]</promise>
+
 [2-3 line summary of what was done]
 Files created: [list] ✅
+
 • "ок" — next phase
 • "углуби [section]" — elaborate
 • "[specific feedback]" — adjust
 ═══════════════════════════════════════════════════════
 ```
 
+### Promise Validation Rules
+
+- A promise tag MUST only be emitted AFTER its conditions are verifiably met
+- If conditions are NOT met, emit `<promise>[TAG]_INCOMPLETE</promise>` instead
+- Downstream phases SHOULD check for upstream promises before starting
+- Promise tags serve as formal phase gates — they replace informal "phase done" signals
+
 ## Rules
 - NEVER skip checkpoints
 - NEVER auto-advance to the next phase without user confirmation

package/templates/.claude/rules/feedback-loops.md

@@ -0,0 +1,113 @@
+# Cross-Phase Feedback Loops
+
+## Purpose
+
+Formalize how data flows between phases in the Keysarium pipeline.
+Each loop has a name, direction, data payload, and namespace for persistence.
+
+## Named Feedback Loops
+
+### Loop 1: CJM → Solve (Critical)
+
+| Property | Value |
+|----------|-------|
+| Direction | Phase 2.5 → Phase 3 |
+| Variable | `{CHOSEN_CJM}` |
+| Payload | Selected CJM variant (A/B/C/D), pain points, conversion metrics |
+| Consumers | Phase 3 (User Flow), Phase 5 (Slide 5) |
+| Persistence | `researches/<slug>/.feedback/cjm-selection.json` |
+
+**Contract:** Phase 3 MUST NOT start without `{CHOSEN_CJM}` being set.
+
+### Loop 2: Research → Presentation
+
+| Property | Value |
+|----------|-------|
+| Direction | Phase 2 → Phase 5 |
+| Payload | Key findings, verified sources, statistics |
+| Source file | `02_research_findings.md` |
+| Consumers | Phase 5 (all slides referencing data) |
+| Usage | Presentation claims must trace back to research findings |
+
+**Contract:** Every data claim in presentation must have a source in `02_research_findings.md`.
+
+### Loop 3: Discovery → All Phases (Context)
+
+| Property | Value |
+|----------|-------|
+| Direction | Phase 0 → Phases 1-5 |
+| Payload | Domain detection, JTBD segments, competitive landscape, business case |
+| Source file | `00_product_discovery.md` |
+| Key fields | `{DOMAIN}`, `{PRIMARY_USER}`, `{AHA_MOMENT}` |
+
+**Contract:** Domain-specific rules activate based on Phase 0 detection.
+
+### Loop 4: Solve → Architecture
+
+| Property | Value |
+|----------|-------|
+| Direction | Phase 3 → Phase 4 |
+| Payload | Chosen solution strategy, AI pipeline spec, HITL design, MVP scope |
+| Source file | `03_solution_strategy.md` |
+| Key fields | `{SOLUTION_CONCEPT}`, `{AI_PIPELINE}`, `{HITL_POLICY}` |
+
+**Contract:** Architecture must implement the solution designed in Phase 3.
+
+### Loop 5: BTO Judges → Optimizer
+
+| Property | Value |
+|----------|-------|
+| Direction | BTO Layer 2 → BTO Optimize |
+| Payload | Per-dimension scores, judge feedback, weak dimensions |
+| Source | Layer 2 evaluation reports |
+| Key fields | `{BASELINE_SCORE}`, `{WEAK_DIMENSIONS}`, `{JUDGE_FEEDBACK}` |
+
+**Contract:** Optimizer mutations target weak dimensions identified by judges.
+
+### Loop 6: History → Discovery (Cross-Case)
+
+| Property | Value |
+|----------|-------|
+| Direction | Past cases → Phase 0 of new case |
+| Payload | Domain patterns, common pitfalls, successful strategies |
+| Source | `TOOLKIT_HARVEST.md`, brain export files |
+| Persistence | `keysarium-brain.json` |
+
+**Contract:** If brain file exists, Phase 0 loads historical patterns before starting.
+
+## Feedback Loop Protocol
+
+### At Phase Start
+1. Check upstream promises are met
+2. Load required source files
+3. Extract key variables from upstream outputs
+4. Apply domain-specific rules from Loop 3
+
+### At Phase End
+1. Emit phase promise tag
+2. Write key outputs for downstream consumers
+3. Validate contract fulfillment
+
+## Variable Registry
+
+All cross-phase variables in one place:
+
+| Variable | Set In | Used In | Type |
+|----------|--------|---------|------|
+| `{DOMAIN}` | Phase 0 | All phases | string (banking/retail/enterprise/healthcare) |
+| `{PRIMARY_USER}` | Phase 0 | Phase 2.5, 3, 5 | string |
+| `{AHA_MOMENT}` | Phase 0 | Phase 2.5, 5 | string |
+| `{CHOSEN_CJM}` | Phase 2.5 | Phase 3, 5 | string (A/B/C/D) |
+| `{SOLUTION_CONCEPT}` | Phase 3 | Phase 4, 5 | string |
+| `{AI_PIPELINE}` | Phase 3 | Phase 4 | structured |
+| `{HITL_POLICY}` | Phase 3 | Phase 4, 5 | structured |
+| `{BASELINE_SCORE}` | BTO L2 | BTO Optimize | float |
+| `{WEAK_DIMENSIONS}` | BTO L2 | BTO Optimize | list[string] |
+
+## Modular Reuse Note
+
+This feedback loop system is domain-agnostic. The same pattern applies to any multi-phase pipeline:
+1. Define named loops with direction and payload
+2. Set contracts (what must exist before proceeding)
+3. Register variables in a central registry
+4. Validate contracts at phase boundaries

package/templates/.claude/rules/model-routing.md

@@ -0,0 +1,65 @@
+# Model Routing Enforcement
+
+## 3-Tier Model Routing
+
+All agent spawning MUST follow the model routing table below.
+Using a higher-cost model than necessary wastes budget.
+Using a lower-cost model than required degrades quality.
+
+## Routing Table
+
+| Tier | Model | Latency | When to Use |
+|------|-------|---------|-------------|
+| Tier 1 | haiku | ~500ms | File formatting, simple transforms, Layer 0 checks, Layer 1 quick eval, BTO variant fast-ranking |
+| Tier 2 | sonnet | ~2s | Research synthesis, analysis, BTO Layer 2 judge panel, mutation workers, meta-judge escalation |
+| Tier 3 | opus (default) | ~5s | Creative CJM design, presentation storytelling, BTO crossover synthesis, complex problem solving |
+
+## Per-Task Assignment
+
+### Keysarium Pipeline
+
+| Task | Model | Rationale |
+|------|-------|-----------|
+| Phase 0 parallel agents (JTBD, Competitors) | sonnet | Research synthesis |
+| Phase 1 exploration | opus | Creative clarification |
+| Phase 2 parallel agents (Analogues, Tech, Regulations) | sonnet | Research analysis |
+| Phase 2.5 CJM variant generation | opus | Creative design work |
+| Phase 2.5 trend research agents | sonnet | Research synthesis |
+| Phase 3 solution design | opus | Complex problem solving |
+| Phase 4 architecture | opus | System design |
+| Phase 5 presentation storytelling | opus | Creative storytelling |
+| Phase 5 speaker script agents | sonnet | Structured generation |
+| Phase 5 Q&A preparation | sonnet | Analytical work |
+| File formatting, slug generation | haiku | Simple transforms |
+
+### BTO Pipeline
+
+| Task | Model | Rationale |
+|------|-------|-----------|
+| Layer 0 structural checks | haiku | Pattern matching only |
+| Layer 1 semantic baseline | haiku | Fast coherence scan |
+| Layer 2 Domain Expert judge | sonnet | Domain knowledge + nuanced scoring |
+| Layer 2 Critic judge | sonnet | Adversarial analysis |
+| Layer 2 Completeness Auditor judge | sonnet | Structured coverage check |
+| Meta-judge (disagreement resolution) | sonnet | Arbitration |
+| Optimization variant fast-eval (Round 1, 2) | haiku | Volume scoring |
+| Optimization Round 3 full panel | sonnet | Final quality assessment |
+| Optimization crossover / creative synthesis | opus | Novel combination of candidates |
+
+## Enforcement Rules
+
+1. **NEVER** use opus for Layer 0 or Layer 1 evaluation — this is wasteful
+2. **NEVER** use haiku for Layer 2 judge panel — quality will be insufficient
+3. **NEVER** use haiku for creative work (CJM design, storytelling) — output will be shallow
+4. When spawning agents with the Agent tool, ALWAYS specify the `model` parameter
+5. If model is not specified, the agent inherits the parent model (opus by default)
+6. For cost optimization, prefer haiku for any task that is primarily pattern-matching or formatting
+
+## Cost Impact
+
+Approximate cost ratios (per 1K output tokens):
+- haiku: 1x (baseline)
+- sonnet: 15x
+- opus: 75x
+
+Using haiku instead of opus for Layer 0-1 saves ~98% on those evaluation steps.

package/templates/.claude/rules/trust-tiers.md

@@ -0,0 +1,36 @@
+# Trust Tier System
+
+## Tier Definitions
+
+| Tier | Label | Requirements | Promotion Path |
+|------|-------|-------------|----------------|
+| Tier 3 | Verified | Eval test suites with deterministic validation | — (highest) |
+| Tier 2 | Validated | Passed /bto-test with Layer 2 score ≥ 7.0 | Run /bto-test, score ≥ 8.5 on Layer 2 |
+| Tier 1 | Structured | SKILL.md + references/ or modules/ | Run /bto-test, score ≥ 7.0 on Layer 2 |
+| Tier 0 | Advisory | Basic SKILL.md only | Add references/, examples/, structured output |
+
+## Current Skill Tiers
+
+| Skill | Tier | Label | Evidence |
+|-------|------|-------|----------|
+| explore | 1 | Structured | SKILL.md + references/ |
+| frontend-design | 0 | Advisory | SKILL.md only, no references |
+| goap-research-ed25519 | 1 | Structured | SKILL.md + references/ + scripts/ |
+| problem-solver-enhanced | 1 | Structured | Comprehensive SKILL.md with TRIZ framework |
+| presentation-storyteller | 1 | Structured | SKILL.md + references/ |
+| reverse-engineering-unicorn | 1 | Structured | SKILL.md + modules/ + references/ + examples/ |
+| bto | 1 | Structured | SKILL.md + modules/ + references/ + examples/ |
+
+## Tier Enforcement
+
+- Tier 0 skills: Flag with warning when loaded in production pipeline
+- Tier 1 skills: Standard usage, recommend /bto-test for promotion
+- Tier 2 skills: Full confidence, include BTO score in metadata
+- Tier 3 skills: Highest confidence, deterministic validation available
+
+## Promotion Protocol
+
+1. Run `/bto-test .claude/skills/<name>/`
+2. If Layer 2 score ≥ 7.0 → promote to Tier 2, record score in SKILL.md
+3. If Layer 2 score ≥ 8.5 + deterministic eval tests exist → promote to Tier 3
+4. Record promotion date and score in SKILL.md frontmatter

package/templates/.claude/shards/phase-0-discovery.shard.md

@@ -0,0 +1,45 @@
+# Phase 0: Discovery — Governance Shard
+
+## Time Budget
+15% of total timeline
+
+## Skill
+Load: `.claude/skills/reverse-engineering-unicorn/SKILL.md` (modules M2-M5)
+
+## Mandatory Outputs
+- `00_product_discovery.md`
+
+## Content Requirements
+- As-Is process mapping
+- JTBD segments (minimum 3)
+- Voice of Customer synthesis
+- Aha Moment identification
+- Why AI / Why Now justification
+- Competitive landscape (minimum 3 competitors)
+- Business Case with ROI projections
+- Adoption Strategy
+
+## Agent Swarm
+- Agent 1 (sonnet): JTBD + Voice of Customer + Aha Moment
+- Agent 2 (sonnet): Competitor Analysis + Business Case + Why AI Why Now
+- Synthesize results into single document
+
+## Domain Detection
+Detect domain from case description and apply domain-specific rules:
+- Banking: on-premise LLM, ФЗ-152, ЦБ, ФСТЭК
+- Retail: latency < 200ms, A/B testing
+- Enterprise: Change Management, Legacy integration
+- Healthcare: HITL mandatory, ФЗ-323
+
+## Quality Gates
+- Zero unverified competitor names
+- ROI must include concrete numbers (FTE/hours/currency)
+- JTBD format: "When [situation], I want to [motivation], so I can [outcome]"
+
+## Promise
+On completion: `<promise>DISCOVERY_COMPLETE</promise>`
+
+## Anti-Patterns to Check
+- "Just add GPT" without specific model/pipeline → BLOCK
+- No metrics/KPIs → BLOCK
+- Vague claims without numbers → FLAG

package/templates/.claude/shards/phase-1-explore.shard.md

@@ -0,0 +1,32 @@
+# Phase 1: Explore — Governance Shard
+
+## Time Budget
+5% of total timeline
+
+## Skill
+Load: `.claude/skills/explore/SKILL.md`
+
+## Prerequisites
+- Phase 0 complete: `<promise>DISCOVERY_COMPLETE</promise>`
+- File exists: `00_product_discovery.md`
+
+## Mandatory Outputs
+- `01_case_brief.md`
+
+## Content Requirements
+- 5 Whys root cause analysis
+- Data landscape analysis
+- Constraints Map: hard / soft / hidden
+- Success Criteria (measurable)
+- Key Question (single, focused)
+
+## Model Routing
+- Default model (opus) for creative clarification
+
+## Quality Gates
+- Constraints must be categorized (hard/soft/hidden)
+- Success criteria must be quantifiable
+- Key Question must be single and actionable
+
+## Promise
+On completion: `<promise>CASE_EXPLORED</promise>`