@dzhechkov/skills-bto 1.0.0 → 1.1.0

package/README.md

@@ -0,0 +1,160 @@
+# @dzhechkov/skills-bto
+
+**Build-Test-Optimize skill pack for Claude Code**
+
+Multi-agent evaluation and iterative optimization pipeline for Claude Code skills, commands, and prompts. Part of the [Keysarium](https://www.npmjs.com/package/@dzhechkov/keysarium) ecosystem.
+
+---
+
+## Quick Start
+
+```bash
+# One-command install via npx
+npx @dzhechkov/skills-bto
+
+# Or install globally
+npm install -g @dzhechkov/skills-bto
+skills-bto init
+
+# Install into a project that already has @dzhechkov/keysarium
+npx @dzhechkov/skills-bto init
+```
+
+After installation, open Claude Code in your project directory and start using BTO commands.
+
+---
+
+## What You Get
+
+| Component | Count | Description |
+|-----------|-------|-------------|
+| **Skill** | 1 | `bto` — core Build-Test-Optimize skill with modules (build, test, optimize) |
+| **Commands** | 4 | `/bto`, `/bto-build`, `/bto-test`, `/bto-optimize` |
+| **Rules** | 1 | `bto-quality-gates` — quality gate enforcement |
+| **Shards** | 1 | `bto-evaluation` — context shard for BTO evaluation pipeline |
+| **Agent Templates** | 2 | `bto-judge-panel`, `bto-optimizer-worker` |
+| **References** | 4 | Eval patterns, judge rubrics, optimization methods, quality checklist |
+| **Examples** | 1 | Sample evaluation report |
+
+Everything is installed into your project's `.claude/` directory and works natively with Claude Code.
+
+---
+
+## Commands
+
+```bash
+npx @dzhechkov/skills-bto                    # Full install (interactive, same as init)
+npx @dzhechkov/skills-bto init               # Install all components
+npx @dzhechkov/skills-bto init --force       # Overwrite existing files
+npx @dzhechkov/skills-bto init --dry-run     # Preview without making changes
+npx @dzhechkov/skills-bto update             # Update to latest version
+npx @dzhechkov/skills-bto remove             # Clean uninstall
+npx @dzhechkov/skills-bto list               # Show installed components
+npx @dzhechkov/skills-bto doctor             # Health check
+```
+
+---
+
+## BTO Pipeline
+
+```
+BUILD ──→ TEST ──→ OPTIMIZE
+  │         │         │
+  │         │         └── Evolutionary mutation + re-evaluation (3 rounds)
+  │         └── Multi-layer evaluation: Layer 0 → Layer 1 → Layer 2
+  └── Generate skill/command from description
+```
+
+### Usage in Claude Code
+
+```bash
+# Full BTO cycle: build → test → optimize
+/bto Create a skill for code review automation
+
+# Build only — generate a new skill or command
+/bto-build Create a skill that analyzes git commit patterns
+
+# Test only — evaluate an existing artifact
+/bto-test .claude/skills/my-skill/SKILL.md
+
+# Optimize only — iteratively improve an artifact
+/bto-optimize .claude/skills/my-skill/SKILL.md
+```
+
+---
+
+## Evaluation Architecture
+
+### Layer Model
+
+| Layer | Agents | Model | Purpose |
+|-------|--------|-------|---------|
+| **Layer 0** | 0 | — | Deterministic pre-checks (structure, completeness, encoding) |
+| **Layer 1** | 1 | haiku | Fast semantic evaluation across 5 dimensions |
+| **Layer 2** | 3 | sonnet | Full judge panel: Domain Expert + Critic + Completeness Auditor |
+| **Meta** | 1 | opus | Disagreement resolution (triggered when score delta > 3) |
+
+### Judge Panel
+
+- **3 independent judges** evaluate each artifact in isolation
+- Judges never see each other's scores before submitting
+- Standard weights: Domain Expert (0.4) / Critic (0.3) / Completeness Auditor (0.3)
+- If `max_score - min_score > 3` → meta-judge escalation
+
+### Quality Gates
+
+- Layer 0 must pass before Layer 1
+- Layer 1 must pass before Layer 2
+- Optimization accepted only if `new_score - prev_score > 0.5`
+- 3 consecutive iterations with delta ≤ 0.5 → convergence declared
+- Score decrease > 1.0 → automatic rollback to previous best
+
+---
+
+## Optimization Process
+
+The optimizer runs up to 3 rounds of evolutionary improvement:
+
+1. **Round 1** — 5 parallel haiku agents generate mutations, fast-rank variants
+2. **Round 2** — Top variants evaluated by sonnet judge panel
+3. **Round 3** — 3×3 parallel sonnet agents for full Layer 2 evaluation of finalists
+
+Each round selects the best-performing variant and uses it as the base for the next iteration.
+
+---
+
+## Integration with Keysarium
+
+BTO works standalone but integrates seamlessly with `@dzhechkov/keysarium`:
+
+```bash
+# Install Keysarium first (optional)
+npx @dzhechkov/keysarium init
+
+# Then add BTO — it detects Keysarium automatically
+npx @dzhechkov/skills-bto init
+```
+
+When installed alongside Keysarium, BTO can evaluate and optimize any skill or command in the Keysarium toolkit.
+
+---
+
+## Requirements
+
+- **Claude Code CLI** — installed and configured ([installation guide](https://docs.anthropic.com/en/docs/claude-code))
+- **Node.js >= 16.0.0** — required for the npm install method
+
+---
+
+## License
+
+[MIT](https://opensource.org/licenses/MIT)
+
+---
+
+## Links
+
+- **GitHub:** [https://github.com/dzhechko/product-keysarium-2026](https://github.com/dzhechko/product-keysarium-2026)
+- **Issues:** [https://github.com/dzhechko/product-keysarium-2026/issues](https://github.com/dzhechko/product-keysarium-2026/issues)
+- **npm:** [https://www.npmjs.com/package/@dzhechkov/skills-bto](https://www.npmjs.com/package/@dzhechkov/skills-bto)
+- **Keysarium:** [https://www.npmjs.com/package/@dzhechkov/keysarium](https://www.npmjs.com/package/@dzhechkov/keysarium)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/skills-bto",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Build-Test-Optimize skill pack for Claude Code — structured BTO pipeline with quality gates, testing strategies, and optimization workflows",
   "main": "src/cli.js",
   "bin": {

package/templates/.claude/shards/bto-evaluation.shard.md

@@ -0,0 +1,48 @@
+# BTO Evaluation — Governance Shard
+
+## Skills
+Load: `.claude/skills/bto/SKILL.md` + relevant module
+
+## Layer Architecture
+
+| Layer | Model | Gate | Action on Fail |
+|-------|-------|------|----------------|
+| Layer 0 | — (deterministic) | ≥ 80% checks pass | STOP, auto-retry up to 3x |
+| Layer 1 | haiku | avg ≥ 7.0 | NEEDS WORK (flag) |
+| Layer 2 | sonnet × 3 judges | weighted avg ≥ 7.0 | FAIL |
+| Meta | sonnet | disagreement > 3 | Arbitrate |
+
+## Judge Isolation — INVARIANT
+- Each judge reads the SAME artifact
+- Each judge writes to a SEPARATE evaluation
+- Judges do NOT see each other's scores before submitting
+- Generator and judge models MUST differ
+
+## Weights
+- Domain Expert: 0.40
+- Critic: 0.30
+- Completeness Auditor: 0.30
+
+## Optimization Delta Gate
+- Accepted if: new_score - prev_score > 0.5
+- 3 consecutive iterations ≤ 0.5 delta → convergence, stop
+- Score decrease > 1.0 → rollback to previous best
+
+## Model Routing
+- Layer 0: deterministic (no LLM)
+- Layer 1: haiku
+- Layer 2 judges: sonnet
+- Meta-judge: sonnet
+- Crossover synthesis: opus
+- Variant fast-eval: haiku
+
+## Promises
+- `<promise>BTO_LAYER0_PASSED</promise>` — after Layer 0
+- `<promise>BTO_LAYER2_SCORED</promise>` — after Layer 2
+- `<promise>BTO_OPTIMIZED</promise>` — after optimization converges
+
+## Anti-Patterns
+- Score inflation (all > 8.5 first attempt) → add calibration
+- Conformity collapse (identical scores) → enforce isolation
+- Runaway optimization (> 10 iterations) → abort
+- Judge-generator collusion (same model) → BLOCK

package/templates/.claude/skills/bto/SKILL.md

@@ -1,5 +1,7 @@
 # BTO — Build · Test · Optimize
 
+<!-- Trust Tier: 1 — Structured | Path to Tier 2: Run /bto-test for self-evaluation -->
+
 > Multi-agent evaluation and prompt optimization system for Claude Code artifacts.
 
 ## Overview