/by-design-workflow

id: "skill_30755445e07649dbb29c836632a0417a"
name: "by-design-workflow"
display-name: "BY Design Workflow — Master Orchestrator"
short-description: "Master orchestration skill that decides which design engine (Protenix, PXDesign, BoltzGen) runs, with which preset, on which compute target, and how to evaluate the result. Use when starting any new design project, deciding between modalities, planning a campaign end-to-end, setting quality thresholds, or deciding accept vs re-run."
category: "orchestration"
keywords: "orchestration, routing, decision tree, modality, antibody, nanobody, VHH, scFv, de novo, binder, Protenix, PXDesign, BoltzGen, preset, tier, compute target, pass rate, quality threshold"
version: "1.0"
last-updated: "2026-05-20"

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/`.

| File | Format | Purpose | Consumer | |------|--------|---------|----------| | `routing_decision.json` | JSON | Engine + preset + compute target + rationale | by-campaign-manager, the engine skill | | `handoff_package.json` | JSON | Bundle of inputs the engine skill needs