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

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:

User: "I want a nanobody against TNF-alpha. Use local GPU. Standard tier."
 
Agent (this skill):
  1. Read .by/config.json → compute.default_provider="local", local engine paths.
  2. Load research/design_recommendation.json (if exists) → modality=VHH, scaffolds=[caplacizumab, ozoralizumab].
  3. python3 scripts/route_intent.py --mode route \
         --intent-json intent.json --config-json .by/config.json \
         --out-dir campaigns/tnf_alpha/.../routing/
     ✓ Routing decision written: routing/routing_decision.json
       (engine=boltzgen, protocol=nanobody-anything, tier=Standard, compute=local)
     ✓ Handoff package written: routing/handoff_package.json
       (scaffolds=2, designs_per_scaffold=5000)
  4. python3 scripts/estimate_design_space.py \
         --modality VHH --tier Standard --num-scaffolds 2 \
         --target-class well_studied --compute-target local \
         --out-dir campaigns/tnf_alpha/.../routing/
     ✓ Forecast written: routing/pass_rate_forecast.json
       (total_designs=10000, expected_passing=3500, wall_hours=5.0, cost=$0.00)
  5. Hand off to by-campaign-manager → writes campaign_plan.md
  6. Hand off to boltzgen skill → runs the actual design
  7. (Later) After by-screening completes:
     python3 scripts/route_intent.py --mode accept-or-rerun \
         --screening-summary screening_summary.json \
         --routing-decision routing/routing_decision.json \
         --out-dir campaigns/tnf_alpha/.../routing/
     ✓ Accept-or-rerun verdict written: routing/accept_or_rerun.json
       (verdict=ACCEPT, pass_rate=24.0%)

Expected total time for the routing step (this skill): under 30 seconds. The actual design compute is handled by the engine skill that follows.

Residue Numbering Convention

All BY tools use `label_seq_id`: 1-indexed, sequential, per-chain, no gaps. This differs from auth_seq_id (the PDB author numbering with gaps and insertion codes) and from 0-indexed array positions.

Tool-specific encoding:

• PXDesign hotspot_residues: list of "<chain><label_seq_id>" strings, e.g. ["A45", "A50"].
• BoltzGen epitope_residues: list of label_seq_id integers per chain, e.g. [45, 50, 52].
• Protenix: full sequences in JSON; no residue-level specification needed.

Common pitfall: users frequently paste residue numbers from a publication or PyMOL session (auth_seq_id). Wrong hotspot numbering wastes the entire campaign. This skill's handoff package stores the mapping auth_seq_id_map so the engine skill can validate against the target structure before launching.

Compute Target Selection

The compute target is read from .by/config.json → compute.default_provider. The skill never silently overrides this — even if the requested target appears unavailable, it ASKS the user before switching.

When compute.fallback_allowed=true in config, the skill may auto-promote local → hpc → tamarind in the order specified by compute.providers_priority. When fallback_allowed=false, ANY switch requires the user's explicit approval — this is a budget-protection property and must not be bypassed.

See by-deploy-compute/SKILL.md for the canonical HPC dispatch logic. This skill does NOT re-document compute setup — it only decides which provider to use.

Campaign Cost Quick Reference

Rough budget envelopes (HPC pricing; local is $0 cash but consumes wall time):

Adaptyv Bio lab follow-up adds $119-$215 per design; budget 5-20 lab tests for a Standard campaign, 30-50 for Production. Turnaround 2-4 weeks.

Standard Workflow

🚨 MANDATORY: USE THE SCRIPTS BELOW TO PRODUCE ROUTING ARTIFACTS — DO NOT IMPROVISE INLINE DECISIONS 🚨

Every routing decision must produce a routing_decision.json written by the script, not free-text. Every accept-vs-re-run verdict must produce an accept_or_rerun.json.

1. Read `.by/config.json` — Pull compute.default_provider, compute.fallback_allowed, compute.providers_priority, and the local engine paths. If the file is missing, prompt for by-session first.
2. Load upstream artifacts — campaigns/{target}/.../research/design_recommendation.json (from by-research) and campaigns/{target}/.../research/recommended_hotspots.json (from by-epitope-analysis). If present, modality and scaffolds are already chosen.
3. Resolve the routing decision — Run scripts/route_intent.py with the merged inputs:

``bash python3 scripts/route_intent.py \ --intent-json /path/to/intent.json \ --config-json /path/to/.by/config.json \ --out-dir campaigns/{target}/.../routing/ ` Writes routing_decision.json. Verification: ✓ Routing decision written: routing/routing_decision.json (engine=boltzgen, protocol=nanobody-anything)`.

1. Forecast pass rate and design count — Before launching compute, estimate budget:

``bash python3 scripts/estimate_design_space.py \ --modality VHH \ --tier Standard \ --num-scaffolds 2 \ --out-dir campaigns/{target}/.../routing/ ` Writes pass_rate_forecast.json. Verification: ✓ Forecast written: routing/pass_rate_forecast.json (expected_passing=1500, wall_hours=2.5)`.

1. Hand off to the engine skill — The engine skill (protenix, pxdesign, or boltzgen) reads routing_decision.json + handoff_package.json and produces the actual designs. This skill does NOT invoke the engine directly.
2. After screening, compute accept-or-rerun — Once by-screening writes the per-round summary, run:

``bash python3 scripts/route_intent.py \ --mode accept-or-rerun \ --screening-summary /path/to/screening_summary.json \ --routing-decision /path/to/routing_decision.json \ --out-dir campaigns/{target}/.../routing/ ` Writes accept_or_rerun.json with verdict ∈ {ACCEPT, RERUN, SWITCH_TOOL, ESCALATE`}.

Discipline:

• ✅ Always write routing_decision.json before any compute is submitted
• ✅ Always re-read .by/config.json at the start — provider can change between sessions
• ✅ Always pass the resolved compute_target to the engine skill in the handoff package (do not let the engine guess)
• ❌ Do NOT silently switch compute providers when compute.fallback_allowed=false
• ❌ Do NOT skip the pass-rate forecast — it is what by-campaign-manager uses for budget gating
• ❌ Do NOT make the accept-vs-rerun call from memory — run the script so the verdict is auditable

When Scripts Fail

Both scripts are stdlib-only Python (json, argparse, pathlib). Failure modes:

1. Fix and Retry (90%) — Almost always a missing input file or wrong path. Re-check the --config-json and --intent-json paths. Confirm .by/config.json exists by running by-session.
2. Modify Script (5%) — If the engine catalog changes (new protocol, new preset), edit the lookup tables at the top of scripts/route_intent.py and references/tool-selection-matrix.md together. Keep CLI signatures stable.
3. Use as Reference (4%) — If the routing decision needs custom logic (e.g., multi-target sweep), read the script for the canonical heuristics, then write the JSON by hand following the schema in routing_decision.json. Cite the source script in rationale.
4. Write from Scratch (1%) — Only if the inputs cannot be reconciled with the existing schema (rare). Document why in routing/notes.md and submit the new schema for review.

If the upstream artifacts (design_recommendation.json, recommended_hotspots.json) are missing, the correct response is to invoke by-research first — not to invent values.

Common Issues

Best Practices

1. 🚨 CRITICAL: Always read `.by/config.json` first. The compute provider is the user's choice, not yours.
2. 🚨 CRITICAL: Never silently default a modality. Ask Q1 if the user said "binder" without qualifier.
3. ✅ REQUIRED: Write `routing_decision.json` before any compute is submitted. It is the audit trail.
4. ✅ REQUIRED: Pass `compute_target` explicitly to the engine skill. Do not let boltzgen / pxdesign / protenix guess from environment.
5. ✅ Run Preview before Production for any novel target. Cheaper to fail at 500 designs than 20,000.
6. ✅ Validate target fold with Protenix before any design run on a target with no experimental structure.
7. ✅ Use label_seq_id (1-indexed, sequential, per-chain) for hotspot residues. Convert from auth_seq_id if user provides PDB numbering.
8. ✅ Prefer local compute when available — fastest, free, and the user already paid for the hardware.
9. ✨ Optional: Run a hypothesis-debate (by-hypothesis-debate) when multiple modalities are viable. A few minutes of reasoning saves hours of compute.
10. ❌ Do NOT skip the pass-rate forecast even on "obvious" campaigns — it is the budget gate.
11. ❌ Do NOT bypass by-campaign-manager for the actual campaign plan. This skill makes the routing decision; by-campaign-manager owns the plan and state machine.
12. ❌ Do NOT improvise new presets / protocols / scaffolds. If the catalog needs an addition, update references/tool-selection-matrix.md and scripts/route_intent.py together.

Suggested Next Steps

After this skill produces routing_decision.json and handoff_package.json, chain into:

1. `by-campaign-manager` — write the canonical campaign_plan.md from the routing decision and the pass-rate forecast. Required before any compute is committed; manages state machine + budget + checkpoints.
2. The engine skill — one of:

• `protenix` — for structure prediction / fold validation. Always run this first if the target has no experimental structure.
• `pxdesign` — for de novo protein binder design. Write YAML → pxdesign pipeline → read summary.csv.
• `boltzgen` — for antibody / nanobody design (or de novo fallback). Write entities YAML → boltzgen run → read final_designs_metrics_*.csv.

1. `by-deploy-compute` (if compute target is hpc) — packages the engine container, syncs target data, dispatches the job. Handles RunPod / Modal / SLURM.
2. `by-screening` — runs the full screening battery (ipSAE, ipTM, pLDDT, RMSD, liabilities, developability) on the design output. Writes screening_summary.json.
3. `by-scoring` — applies canonical formulas (composite, multi-seed aggregation, asymmetry checks) on top of screening output.
4. Back to `by-design-workflow` (this skill) in accept-or-rerun mode — after screening, compute the verdict (ACCEPT / RERUN / SWITCH_TOOL / ESCALATE).
5. `by-failure-diagnosis` (conditional) — invoked when the verdict is RERUN or SWITCH_TOOL; identifies the specific failure mode driving low pass rate.

This chain works because every downstream skill expects exactly the JSON shapes this skill writes. The handoff package is the contract; bypassing it forces the next skill to re-derive routing context from scratch.

Related Skills

Upstream (run before this):

• by-session — initializes config, ensures .by/config.json exists with compute provider.
• by-research — produces design_recommendation.json (modality, scaffolds, tier).
• by-epitope-analysis — produces recommended_hotspots.json (residue list with confidence).
• by-hypothesis-debate — produces adversarial-ranked strategy when multiple modalities are viable.

Downstream (run after this):

• by-campaign-manager — writes campaign_plan.md from routing decision + forecast.
• protenix, pxdesign, boltzgen — the three engine wrappers that actually run the design.
• by-deploy-compute — HPC dispatch for hpc compute target.
• by-screening + by-scoring — evaluate the design output.
• by-failure-diagnosis — diagnose RERUN / SWITCH_TOOL verdicts.

Alternative / complementary:

• by-database — direct PDB / UniProt / SAbDab lookups without the campaign overhead.
• by-display — render the routing decision + forecast as a user-facing table.

References

Detailed documentation (this skill):

• `references/tool-selection-matrix.md` — full modality × tool × preset × hotspot × pass rate × compute matrix with per-cell rationale.
• `references/preset-comparison.md` — Preview vs Standard vs Production vs Exploratory comparison across BoltzGen + PXDesign; cost, time, diversity, recommended use case for each.
• `references/quality-thresholds.md` — acceptance criteria by modality (ipSAE / ipTM / pLDDT / CA-RMSD); when to ACCEPT, RERUN, SWITCH_TOOL, ESCALATE.

Scripts:

• `scripts/route_intent.py` — CLI: input intent JSON (target, modality, budget, compute pref) → output routing_decision.json + handoff_package.json; also handles accept-or-rerun mode after screening.
• `scripts/estimate_design_space.py` — CLI: input modality + tier + scaffold count → estimate total design count, wall time hours, expected passing designs based on canonical pass-rate buckets.

Cross-skill canonical sources:

• `templates/.claude/skills/README.md` — canonical terminology, skill linkage map, end-to-end workflow.
• `templates/CLAUDE.md` — BY agent identity, compute provider selection, campaign workflow overview.
• `by-research/SKILL.md` — produces upstream design_recommendation.json.
• `by-campaign-manager/SKILL.md` — consumes downstream routing_decision.json.
• `by-deploy-compute/SKILL.md` — HPC dispatch details (do not re-document here).
• `by-scoring/SKILL.md` — canonical ipSAE / ipTM / composite formulas.
• `by-screening/SKILL.md` — full screening battery + PASS / FAIL gates.

External documentation:

• BoltzGen: project README in the local install (see compute.local.boltzgen.path in .by/config.json).
• PXDesign: project README in the local install (see compute.local.pxdesign.path).
• Protenix: https://github.com/bytedance/Protenix