@dzhechkov/skills-bto 1.0.0

package/templates/.claude/agents/bto-judge-panel.md

@@ -0,0 +1,192 @@
+# Agent Template: BTO Judge Panel
+
+## Purpose
+Evaluates a single artifact through a 3-judge panel (extendable to 5).
+Each judge runs in isolation and scores the artifact on a shared rubric.
+Reusable for any artifact type: skills, prompts, presentations, architectures.
+
+## Spawning Pattern
+```
+Agent(
+  subagent_type="general-purpose",
+  description="BTO Judge Panel — [ARTIFACT_TYPE]",
+  prompt="""
+    Spawn 3 parallel judge agents for artifact: [ARTIFACT_PATH]
+
+    Each agent:
+    1. Reads the artifact at [ARTIFACT_PATH]
+    2. Reads the rubric at [RUBRIC_PATH]
+    3. Scores independently (NO inter-judge communication)
+    4. Writes evaluation to [EVAL_DIR]/judge-[N].md
+
+    After all 3 complete:
+    - Compute weighted average score
+    - Check disagreement threshold (max - min > 3 → escalate)
+    - Write aggregated result to [EVAL_DIR]/panel-verdict.md
+  """
+)
+```
+
+## Agents
+
+### Agent 1: Domain Expert
+```
+Agent(
+  subagent_type="general-purpose",
+  model="sonnet",
+  description="BTO Judge 1 — Domain Expert",
+  prompt="""
+    Role: Domain Expert evaluator. Weight: 0.4.
+
+    Read artifact: [ARTIFACT_PATH]
+    Read rubric: [RUBRIC_PATH]
+
+    Evaluate on:
+    - Domain accuracy: are claims correct for this field?
+    - Technical depth: does the artifact address non-obvious aspects?
+    - Practical applicability: can a practitioner use this as-is?
+
+    Scoring: integer 1–10 per criterion. No half-points.
+    Calibration: reserve 9-10 for genuinely exceptional work.
+
+    Output format (write to [EVAL_DIR]/judge-1.md):
+    ## Judge 1: Domain Expert
+    | Criterion | Score | Justification |
+    |-----------|-------|---------------|
+    | Domain accuracy | X | ... |
+    | Technical depth | X | ... |
+    | Practical applicability | X | ... |
+    **Weighted subtotal:** [score * 0.4]
+    **Strengths:** [2-3 bullet points]
+    **Critical gaps:** [2-3 bullet points]
+  """
+)
+```
+
+### Agent 2: Critic
+```
+Agent(
+  subagent_type="general-purpose",
+  model="sonnet",
+  description="BTO Judge 2 — Critic",
+  prompt="""
+    Role: Calibrated Critic evaluator. Weight: 0.3.
+    Calibration: you are instructed to be strict. If in doubt, score lower.
+
+    Read artifact: [ARTIFACT_PATH]
+    Read rubric: [RUBRIC_PATH]
+
+    Evaluate on:
+    - Logical consistency: no internal contradictions
+    - Verifiability: claims are traceable to sources or marked [ANALYSIS]
+    - Anti-pattern absence: none of the forbidden patterns from bto-quality-gates.md
+
+    Scoring: integer 1–10 per criterion. Penalize vague claims heavily.
+    If an anti-pattern is detected, cap the criterion score at 5.
+
+    Output format (write to [EVAL_DIR]/judge-2.md):
+    ## Judge 2: Critic
+    | Criterion | Score | Justification |
+    |-----------|-------|---------------|
+    | Logical consistency | X | ... |
+    | Verifiability | X | ... |
+    | Anti-pattern absence | X | ... |
+    **Weighted subtotal:** [score * 0.3]
+    **Anti-patterns detected:** [list or "none"]
+    **Blocking issues:** [list or "none"]
+  """
+)
+```
+
+### Agent 3: Completeness Auditor
+```
+Agent(
+  subagent_type="general-purpose",
+  model="sonnet",
+  description="BTO Judge 3 — Completeness Auditor",
+  prompt="""
+    Role: Completeness Auditor. Weight: 0.3.
+
+    Read artifact: [ARTIFACT_PATH]
+    Read rubric: [RUBRIC_PATH]
+    Read required structure spec: [STRUCTURE_SPEC_PATH]
+
+    Evaluate on:
+    - Section coverage: all required sections present and non-empty
+    - Depth per section: each section meets minimum depth (not a stub)
+    - Edge cases addressed: boundary conditions and failure modes mentioned
+
+    Scoring: integer 1–10 per criterion.
+    Deduct 2 points for each missing required section.
+    Deduct 1 point for each stub section (< 3 substantive sentences).
+
+    Output format (write to [EVAL_DIR]/judge-3.md):
+    ## Judge 3: Completeness Auditor
+    | Criterion | Score | Justification |
+    |-----------|-------|---------------|
+    | Section coverage | X | ... |
+    | Depth per section | X | ... |
+    | Edge cases addressed | X | ... |
+    **Weighted subtotal:** [score * 0.3]
+    **Missing sections:** [list or "none"]
+    **Stub sections:** [list or "none"]
+  """
+)
+```
+
+## Aggregation Protocol
+After all 3 judge agents complete, the orchestrator runs aggregation:
+
+```
+1. Read [EVAL_DIR]/judge-1.md, judge-2.md, judge-3.md
+2. Extract weighted subtotals: S1, S2, S3
+3. Compute panel_score = S1 + S2 + S3  (already weighted)
+4. Compute raw scores: r1, r2, r3 (average of each judge's criteria)
+5. Check disagreement: if max(r1,r2,r3) - min(r1,r2,r3) > 3 → escalate to meta-judge
+6. Write panel-verdict.md
+```
+
+### panel-verdict.md Format
+```markdown
+## Panel Verdict — [ARTIFACT_NAME]
+**Panel score:** [X.X / 10]
+**Judge scores:** Expert=[r1], Critic=[r2], Auditor=[r3]
+**Disagreement flag:** [YES/NO]
+**Decision:** [PASS / FAIL / ESCALATE]
+**Pass threshold:** [defined in rubric, default 7.0]
+**Top improvement areas:**
+- [from Critic blocking issues]
+- [from Auditor missing sections]
+```
+
+## Disagreement Escalation (Meta-Judge)
+When disagreement > 3 points:
+```
+Agent(
+  subagent_type="general-purpose",
+  model="sonnet",
+  description="BTO Meta-Judge",
+  prompt="""
+    Read all 3 judge evaluations: [EVAL_DIR]/judge-*.md
+    Read artifact: [ARTIFACT_PATH]
+    Read rubric: [RUBRIC_PATH]
+
+    Identify the source of disagreement.
+    Provide a final binding score with explicit reasoning.
+    Write to [EVAL_DIR]/meta-judge.md
+  """
+)
+```
+
+## Configuration Variables
+| Variable | Description | Example |
+|----------|-------------|---------|
+| ARTIFACT_PATH | Path to artifact being evaluated | researches/slug/03_solution_strategy.md |
+| RUBRIC_PATH | Path to scoring rubric | .claude/rubrics/skill-rubric.md |
+| STRUCTURE_SPEC_PATH | Path to required structure | .claude/specs/skill-structure.md |
+| EVAL_DIR | Directory for evaluation outputs | researches/slug/evals/round-2/ |
+| ARTIFACT_TYPE | Human-readable artifact type label | "Solution Strategy" |
+
+## Reusability Note
+Swap ARTIFACT_PATH and RUBRIC_PATH to evaluate any artifact type:
+skills, prompts, presentations, architecture documents, research findings.

package/templates/.claude/agents/bto-optimizer-worker.md

@@ -0,0 +1,181 @@
+# Agent Template: BTO Optimizer Worker
+
+## Purpose
+Generates 1-2 prompt or skill variants using an assigned mutation strategy.
+Used as one of N parallel workers in an optimization round.
+Reusable for any prompt optimization task, not Keysarium-specific.
+
+## Spawning Pattern
+```
+Agent(
+  subagent_type="general-purpose",
+  description="BTO Optimizer — [MUTATION_STRATEGY]",
+  prompt="""
+    Read the base artifact: [BASE_ARTIFACT_PATH]
+    Read the last evaluation: [LAST_EVAL_PATH]
+    Read the rubric: [RUBRIC_PATH]
+
+    Mutation strategy assigned: [MUTATION_STRATEGY]
+    Worker ID: [WORKER_ID]
+
+    Generate [1 or 2] variants using your assigned strategy.
+    Write each variant to [OUTPUT_DIR]/variant-[WORKER_ID]-[A|B].md
+
+    Then run a Layer 0 self-check on each variant before saving.
+    If Layer 0 fails, fix and retry once. If it fails again, skip that variant.
+
+    Write a brief mutation log to [OUTPUT_DIR]/mutation-log-[WORKER_ID].md
+  """
+)
+```
+
+## Mutation Strategies
+
+Assign one strategy per worker. Rotate strategies across rounds.
+
+| Strategy | Description | Good For |
+|----------|-------------|----------|
+| `expand-depth` | Add concrete examples, edge cases, non-obvious details | Thin sections |
+| `compress-clarity` | Remove redundancy, sharpen wording, improve signal/noise | Verbose artifacts |
+| `reframe-domain` | Re-express the same content through a different domain lens | Generic claims |
+| `add-metrics` | Replace vague claims with quantified statements | Abstract recommendations |
+| `invert-critic` | Address top blocking issues from last evaluation | Low Critic score |
+| `fill-gaps` | Expand missing or stub sections identified by Auditor | Low Auditor score |
+| `crossover` | Blend two highest-scoring variants from previous round | Late-stage refinement |
+
+## Worker Configuration
+
+### Standard Round: 3 Workers
+```
+Worker 1: mutation_strategy="expand-depth",    variants=2, model="sonnet"
+Worker 2: mutation_strategy="add-metrics",     variants=1, model="sonnet"
+Worker 3: mutation_strategy="invert-critic",   variants=2, model="sonnet"
+```
+
+### Crossover Round: 2 Workers (after round 3+)
+```
+Worker 1: mutation_strategy="crossover", source_A=[best_variant_path], source_B=[second_best_path], model="opus"
+Worker 2: mutation_strategy="compress-clarity", variants=1, model="sonnet"
+```
+
+## Layer 0 Self-Check (inline, before saving)
+Each worker performs this check on every variant it generates:
+
+```
+- [ ] All required sections present
+- [ ] No placeholders: [TODO], [TBD], <INSERT>, ???
+- [ ] Length in bounds: min=[MIN_TOKENS] max=[MAX_TOKENS]
+- [ ] No self-citation (variant does not reference itself)
+- [ ] Mutation is substantive (diff from base > 10% of content)
+```
+
+If any check fails → log reason to mutation-log-[WORKER_ID].md, skip variant.
+
+## Evaluation of Variants (Parallel Haiku Agents)
+After all workers complete, launch lightweight haiku agents for fast scoring:
+
+```
+For each variant file in [OUTPUT_DIR]/variant-*.md:
+  Agent(
+    subagent_type="general-purpose",
+    model="haiku",
+    description="BTO Layer 1 Fast Eval — [variant_file]",
+    prompt="""
+      Read variant: [variant_file]
+      Read rubric: [RUBRIC_PATH]
+
+      Score on 3 quick criteria (integer 1-10 each):
+      1. Relevance: does it address the rubric goals?
+      2. Coherence: is it internally consistent?
+      3. Improvement signal: does it improve on the base artifact?
+
+      Output one line: [variant_id] [r1] [r2] [r3] [average]
+      Write to [SCORES_DIR]/score-[variant_id].txt
+    """
+  )
+```
+
+## Results Collection and Ranking
+After all haiku evaluations complete, the orchestrator:
+
+```
+1. Read all [SCORES_DIR]/score-*.txt
+2. Sort variants by average score descending
+3. Select top-K variants (default K=2) for full judge panel
+4. Log ranking to [OUTPUT_DIR]/round-ranking.md
+5. Pass top-K to bto-judge-panel agent template
+```
+
+### round-ranking.md Format
+```markdown
+## Optimization Round [N] — Ranking
+| Rank | Variant | R1 | R2 | R3 | Avg | Strategy |
+|------|---------|----|----|----|----|---------|
+| 1 | variant-2-A | 8 | 7 | 8 | 7.7 | invert-critic |
+| 2 | variant-1-B | 7 | 8 | 7 | 7.3 | expand-depth |
+...
+**Selected for full evaluation:** variant-2-A, variant-1-B
+**Discarded:** [list with reason]
+```
+
+## Crossover Protocol
+When top 2 variants exist from a previous round:
+
+```
+Agent(
+  subagent_type="general-purpose",
+  model="opus",
+  description="BTO Crossover",
+  prompt="""
+    Read Variant A (higher domain score): [VARIANT_A_PATH]
+    Read Variant B (higher completeness score): [VARIANT_B_PATH]
+    Read evaluation of each: [EVAL_A_PATH], [EVAL_B_PATH]
+
+    Produce one crossover variant that:
+    - Takes structure and domain depth from Variant A
+    - Takes completeness and edge cases from Variant B
+    - Resolves any contradictions explicitly
+
+    Write to [OUTPUT_DIR]/variant-crossover.md
+  """
+)
+```
+
+## Cost Bounds and Abort Conditions
+
+| Condition | Action |
+|-----------|--------|
+| Round count > 10 | Abort optimization, deliver best-so-far |
+| Delta <= 0.5 for 3 consecutive rounds | Declare convergence, stop |
+| Score regression > 1.0 | Rollback to previous best, log regression |
+| Layer 0 fail rate > 50% in one round | Halt, human review required |
+| Total haiku evals > 50 per session | Warn, continue only with human approval |
+| Crossover score < both parents | Discard crossover, keep best parent |
+
+## Configuration Variables
+| Variable | Description | Example |
+|----------|-------------|---------|
+| BASE_ARTIFACT_PATH | Starting artifact to optimize | researches/slug/03_solution_strategy.md |
+| LAST_EVAL_PATH | Most recent panel-verdict.md | researches/slug/evals/round-1/panel-verdict.md |
+| RUBRIC_PATH | Scoring rubric | .claude/rubrics/skill-rubric.md |
+| OUTPUT_DIR | Where variants are written | researches/slug/evals/round-2/ |
+| SCORES_DIR | Where haiku scores are written | researches/slug/evals/round-2/scores/ |
+| MIN_TOKENS | Minimum variant length | 300 |
+| MAX_TOKENS | Maximum variant length | 2000 |
+| K | Top variants to promote to full panel | 2 |
+
+## Mutation Log Format
+Each worker writes a log regardless of success:
+```markdown
+## Mutation Log — Worker [WORKER_ID] — Round [N]
+**Strategy:** [MUTATION_STRATEGY]
+**Variants attempted:** [N]
+**Variants passed Layer 0:** [N]
+**Layer 0 failures:** [list with reasons or "none"]
+**Substantive changes made:**
+- [brief description of what was changed and why]
+```
+
+## Reusability Note
+This template is artifact-type agnostic. Replace BASE_ARTIFACT_PATH and RUBRIC_PATH
+to optimize any text artifact: prompts, skills, presentations, research sections, code docstrings.

package/templates/.claude/commands/bto-build.md

@@ -0,0 +1,169 @@
+# /bto-build — Generate Skill or Command from Description
+
+## Usage
+```
+/bto-build [natural language description of what to generate]
+```
+
+## Parameters
+- $ARGUMENTS — Natural language description of the skill, command, rule, or agent template to generate. Optionally include "deep" to activate DEEP mode with interactive clarification.
+
+## Protocol
+
+### Step 1: Load Skill and Module
+
+Read `.claude/skills/bto/SKILL.md`
+Read `.claude/skills/bto/modules/build.md`
+
+### Step 2: Validate Input
+
+If $ARGUMENTS is empty:
+- Ask: "Describe the skill or command you want to build. Include: what it does, who uses it, expected inputs and outputs."
+- Stop and wait.
+
+### Step 3: Detect Mode
+
+Scan $ARGUMENTS for "deep" or "углубленный":
+- If found → **DEEP mode**: load `explore` skill, run interactive clarification
+- Otherwise → **QUICK mode**: proceed directly to generation
+
+### Step 4: Detect Artifact Type
+
+Auto-detect from $ARGUMENTS using these signals:
+
+| Signal Words | Detected Type |
+|-------------|--------------|
+| "skill", "module", "capability", "protocol", "скилл" | skill |
+| "command", "slash command", "/something", "pipeline", "команда" | command |
+| "rule", "constraint", "convention", "anti-pattern", "правило" | rule |
+| "agent", "worker", "parallel", "swarm", "агент" | agent |
+
+If ambiguous — default to `skill` and note the assumption.
+
+### Step 5: DEEP Mode (if activated)
+
+Read `.claude/skills/explore/SKILL.md`
+
+Follow the explore protocol to clarify:
+1. Exact scope and boundaries — what is in scope, what is out of scope?
+2. Target consumers — which agent/user/command will load this?
+3. Input format — what $ARGUMENTS or parameters does it accept?
+4. Expected output — what files, text, or actions does it produce?
+5. Quality criteria — how will success be measured?
+6. Edge cases — what inputs could break it?
+7. Reference examples — any existing artifacts to model after?
+
+Produce a requirements brief and confirm with user before proceeding to generation.
+
+### Step 6: QUICK Mode (if activated)
+
+Extract directly from $ARGUMENTS:
+1. Parse artifact name → kebab-case slug
+2. Extract key capabilities and responsibilities
+3. Identify domain context (banking, retail, enterprise, etc.)
+4. Identify output artifacts (files, reports, diagrams)
+5. Proceed immediately to generation
+
+### Step 7: Generate Artifact
+
+Following the template from build.md for the detected type:
+
+#### For Skills:
+Create directory `.claude/skills/<name>/` with:
+- `SKILL.md` — Main orchestrator with Overview, Protocol, Output Format, Anti-Patterns, Dependencies
+- `modules/<module-name>.md` — Detailed per-module protocols (if multi-module)
+- `references/<ref-name>.md` — Supporting material, rubrics, checklists (at least one)
+- `examples/<example-name>.md` — Few-shot examples showing expected output (at least one)
+
+#### For Commands:
+Create file `.claude/commands/<name>.md` with:
+- `# /command-name — Short Description`
+- `## Usage` with invocation syntax
+- `## Parameters` documenting $ARGUMENTS
+- `## Protocol` with numbered steps
+- Skill loading instructions (Read `.claude/skills/.../SKILL.md`)
+- Agent tool usage for parallel work where applicable
+- Checkpoint banner at end
+
+#### For Rules:
+Create file `.claude/rules/<name>.md` with:
+- Title heading
+- Pattern/Detection Signal/Fix table
+- Auto-Detection section
+
+#### For Agent Templates:
+Create file `.claude/agents/<name>.md` with:
+- Purpose statement
+- Model selection with justification
+- Isolation scope (reads X, writes Y)
+- Prompt template
+
+### Step 8: Self-Review (Layer 0)
+
+Before finalizing, validate against quality checklist:
+
+**Structure check:**
+- Required sections present for artifact type?
+- No empty sections (heading immediately followed by another heading)?
+- Proper markdown formatting?
+
+**Content check:**
+- No generic placeholder content left?
+- Anti-patterns section populated with real failure modes?
+- At least one concrete example or reference included?
+
+**Convention check:**
+- File naming: kebab-case?
+- Heading hierarchy: properly nested?
+- All cross-references point to files that will exist?
+
+**Size check:**
+- SKILL.md: 2KB-30KB
+- Module files: 1KB-15KB
+- Reference files: 500B-10KB
+- Command files: 500B-20KB
+
+If any check fails — fix before outputting. Flag with [FIXED: reason].
+
+### Step 9: Create Files
+
+Write all generated files to disk. Display creation summary.
+
+**Checkpoint:**
+```
+═══════════════════════════════════════════════════════
+CHECKPOINT: BUILD Complete
+Artifact type: [skill / command / rule / agent]
+Mode used: [QUICK / DEEP]
+
+Files created:
+  [path/to/SKILL.md] (X KB)
+  [path/to/modules/module.md] (X KB)
+  [path/to/references/ref.md] (X KB)
+  [path/to/examples/example.md] (X KB)
+
+Self-review: X/Y checks passed
+[List any issues found and fixed]
+
+Next steps:
+  /bto-test [path] — evaluate quality
+  /bto [path]      — test + optimize in one pipeline
+• "ок" — done
+• "переделай [aspect]" — adjust and regenerate
+• "углуби [section]" — expand a specific section
+• "добавь пример" — add another example
+═══════════════════════════════════════════════════════
+```
+
+## Anti-Patterns
+
+| Anti-Pattern | Detection | Fix |
+|-------------|-----------|-----|
+| Generic artifact | No domain-specific terms in output | Add domain context from $ARGUMENTS |
+| Missing references | references/ empty or not created | Always include at least one reference file |
+| No examples | examples/ empty or not created | Always include at least one example |
+| Placeholder content | "[TODO]" or "[INSERT]" left in output | Generate actual content, never leave placeholders |
+| Over-scoped SKILL.md | SKILL.md > 30KB | Split into modules, keep SKILL.md as orchestrator |
+| Under-specified | SKILL.md < 2KB | Expand — artifact too thin to be useful |
+| Wrong artifact type | Description says "command" but skill generated | Re-detect and regenerate |
+| Skipping self-review | Files written before quality check | Always run Layer 0 before finalizing |