001tmf/blatant-why/by-design-workflow

BY Design Workflow — Master Orchestration Skill

by-design-workflow is the routing brain of BY. It does not run any engine itself. Instead, it answers four questions before any GPU compute is committed:

1. Which engine? — Protenix (fold), PXDesign (de novo binder), or BoltzGen (antibody / nanobody / fallback binder).
2. Which preset / protocol / tier? — Preview vs Standard vs Production vs Exploratory; nanobody-anything vs antibody-anything vs protein-anything; PXDesign preview vs extended.
3. Which compute target? — local (default), hpc (RunPod / Modal / SLURM via by-deploy-compute), or tamarind (cloud fallback).
4. Accept or re-run? — given the screening output, do the designs clear the quality bar, or does the campaign need a second pass with new hotspots, a new modality, or a different scaffold?

This skill encodes the canonical decision tree, the modality → tool mapping, the preset comparison, the quality thresholds, and the accept-vs-re-run heuristics that other skills depend on. It is the connective tissue between by-research / by-campaign-manager (upstream) and the three tool wrappers protenix, pxdesign, boltzgen (downstream).

When to Use This Skill

Use this skill when you have:

• ✅ A new design project starting — research is done, but the tool / preset / compute target has not been chosen yet
• ✅ An ambiguous modality — user said "I want a binder against X" without specifying antibody vs nanobody vs de novo
• ✅ A target description but no plan — PDB ID or sequence in hand, need a campaign sized end-to-end
• ✅ A screening result and a decision to make — designs are scored, should we lab-submit, re-run with new hotspots, or escalate?
• ✅ A compute-target conflict — local GPU OOMs on a 1500-residue target, decide HPC vs Tamarind vs target cropping
• ✅ A novel target with no clear preset — need to pick between Standard and Exploratory tiers based on prior-art density
• ✅ A multi-target sweep request — orchestrate the same protocol over N targets and decide whether to batch or serialize

Do NOT use this skill when:

• ❌ You only need to run one engine right now — invoke the engine's skill directly (protenix, pxdesign, or boltzgen). This skill is the planner, not a substitute for invoking the tool.
• ❌ You are scoring or filtering existing designs — that is by-scoring + by-screening.
• ❌ You are managing campaign state / checkpoints / budget — that is by-campaign-manager.
• ❌ You need a PDB lookup, UniProt entry, or SAbDab query — call the database MCP server directly or use by-database.
• ❌ You are diagnosing a failed campaign in detail — that is by-failure-diagnosis → by-causal-reasoning.
• ❌ You want to skip the modality clarification step — never trust a guessed modality. Always ask if the user has not specified.

🚨 CRITICAL: Never trust the routing decision without checking .by/config.json for the compute target. If compute.fallback_allowed is false, the choice between local / HPC / Tamarind is the user's, not yours. See references/tool-selection-matrix.md and the by-deploy-compute skill.

Inputs

Required:

• Target description — exactly one of:
• PDB ID (e.g., "7S4S") — most preferred; gives structure + chains + residue numbering
• UniProt accession (e.g., "P01375") — sequence + features; structure inferred via Protenix if no PDB exists
• Bare sequence (FASTA) — least preferred; cannot resolve isoforms or residue numbering, requires Protenix fold first
• Modality preference (if known): VHH / scFv / Fab / de_novo_binder / unknown. If unknown, the skill ASKS — never guesses.

Optional:

• Hotspot residues (label_seq_id integers, per-chain) — if by-research or by-epitope-analysis already produced them, pass them through unchanged
• Budget / timeline constraint — e.g., "under $500 cloud spend", "results by Friday". Drives tier and compute-target choice.
• Compute target preference — local / hpc / tamarind / auto. Default local. Read .by/config.json first; explicit user override only on this turn.
• Existing campaign plan — campaign_plan.md from by-campaign-manager. If present, use it instead of re-deciding from scratch.
• Prior-art context — design_recommendation.json from by-research. If present, modality, scaffolds, and tier are already chosen; this skill validates and dispatches.
• Acceptance criteria override — non-default thresholds for ipSAE / ipTM / pLDDT / CA-RMSD (rarely used; default thresholds live in references/quality-thresholds.md).

See references/tool-selection-matrix.md for how each input combination maps to a routing decision.

Outputs

This skill writes routing artifacts, not design data. Place them under the active campaign directory at campaigns/{target}/campaign_{date}_{id}/routing/.

Key shape — `routing_decision.json`:

{
  "campaign_id": "tnf_alpha_20260520_001",
  "engine": "boltzgen",
  "protocol": "nanobody-anything",
  "tier": "Standard",
  "num_designs_per_scaffold": 5000,
  "scaffolds": ["caplacizumab", "ozoralizumab"],
  "compute_target": "local",
  "compute_provider_source": ".by/config.json",
  "estimated_wall_time_hours": 2.5,
  "estimated_pass_rate_range": "20-40%",
  "expected_passing_designs": 1500,
  "rationale": "VHH modality (user-specified); 2 PDB co-crystals exist; pass rate is target-bucket median for well-studied antigens; local 1xH100 sufficient at this tier.",
  "rerouting_triggers": ["local OOM (>1500 aa)", "<10% pass rate at 500 designs"],
  "fallback_chain": ["local", "hpc(runpod)", "tamarind"],
  "created_at": "2026-05-20T10:00:00Z"
}

Key shape — `accept_or_rerun.json`:

{
  "campaign_id": "tnf_alpha_20260520_001",
  "verdict": "RERUN",
  "round_index": 1,
  "metrics_summary": {
    "designs_total": 500,
    "ipsae_min_p50": 0.28,
    "iptm_p50": 0.61,
    "pass_rate": 0.08
  },
  "verdict_reasoning": "ipSAE p50 below 0.30 pass threshold; iptm acceptable. Hotspots likely too dispersed; shrink window from 8 to 4 residues centered on highest-conservation cluster.",
  "next_action": "Re-run BoltzGen nanobody-anything with narrowed hotspots; same scaffolds; budget unchanged.",
  "escalation_path": "If second round also fails, switch to PXDesign de novo (different paratope topology) before escalating to wet-lab epitope mapping."
}

Clarification Questions

⚠️ CRITICAL: ASK THIS FIRST — never proceed without an unambiguous target + modality. Guessing burns compute.

1. Target + modality (ASK THIS FIRST) — What is the target (PDB ID or sequence), and what modality do you want — antibody (scFv / Fab), nanobody (VHH), de novo protein binder, or structure-only (no design, just folding)? If the user says "binder" without qualifier, ask the modality question explicitly.
2. Compute target — Local GPU (default), HPC (RunPod / Modal / SLURM), or Tamarind cloud? Read .by/config.json first; only ask if the file is missing or compute.fallback_allowed is true and the user has not specified.
3. Tier and budget — Preview (feasibility, ~5–500 designs), Standard (~5K designs), Production (~20K), or Exploratory (~50K, novel targets)? If the user gave a dollar budget or deadline, derive the tier from references/preset-comparison.md.
4. Hotspots / epitope — Already known (from by-research or by-epitope-analysis)? Or do we need to do epitope analysis first? For de novo binders without hotspots, PXDesign will run a hotspot-free preview but pass rates drop ~3×.
5. Scaffold preference — For antibody / nanobody runs: caplacizumab default for VHH, adalimumab default for scFv. Multiple scaffolds increase diversity but multiply design count. See references/tool-selection-matrix.md for the full list.
6. Acceptance criteria — Default thresholds (ipSAE > 0.3, ipTM > 0.5, pLDDT > 70, CA-RMSD < 3.5 Å)? Or stricter (ipSAE > 0.5, etc.) for high-stakes targets? Defaults live in references/quality-thresholds.md.
7. Re-run policy — If first-round pass rate is below 10%, what is the user's tolerance for re-running with adjusted hotspots vs switching tools vs escalating to wet lab? Default is two re-runs, then switch tool, then escalate.

Decision Tree

This is the canonical routing logic. Walk it top-to-bottom; the first matching branch wins. Full matrix (with rationale per cell) is in references/tool-selection-matrix.md.

User intent
│
├─ "Design a binder against <target>"
│   │
│   ├─ Antibody / nanobody?
│   │   ├─ Nanobody / VHH / single-domain / sdAb
│   │   │     → engine: boltzgen
│   │   │       protocol: nanobody-anything
│   │   │       default scaffolds: caplacizumab, ozoralizumab
│   │   │       typical pass rate: 15-40%
│   │   │
│   │   └─ Full antibody / scFv / Fab / IgG / mAb
│   │         → engine: boltzgen
│   │           protocol: antibody-anything
│   │           default scaffolds: adalimumab, tezepelumab
│   │           typical pass rate: 10-30%
│   │           note: post-design VH-(G4S)3-VL conversion for scFv
│   │
│   └─ De novo protein binder (non-antibody, non-nanobody)?
│       ├─ Standard target (PDB exists, hotspots known)
│       │     → engine: pxdesign
│       │       preset: extended (production) | preview (feasibility)
│       │       typical pass rate: 17-82% (target-dependent)
│       │
│       └─ PXDesign env/CUDA issue OR novel topology
│             → engine: boltzgen
│               protocol: protein-anything
│               typical pass rate: 10-25%
│
├─ "Predict / validate a structure" (no design)
│       → engine: protenix
│         model: base_default (recommended) | base_20250630 (latest) | mini (fast)
│         seeds: [42] single, [42,123,456,789,1024] ensemble
│         note: ALWAYS run before designing to validate target fold
│
├─ "Score / re-rank existing designs"
│       → NOT this skill. Dispatch to by-scoring + by-screening.
│
└─ "Analyze a target / find hotspots"
        → NOT this skill. Dispatch to by-research + by-epitope-analysis.

Resolved routing — quick lookup

For full matrix (rows: VHH / scFv / Fab / de novo / ligand-binding / structure-only; columns: tool / preset / hotspot guidance / pass rate / compute), see references/tool-selection-matrix.md.

Quick Start

A typical "design a binder against TNF-alpha" request, end-to-end: