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:

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:

   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).
4. Forecast pass rate and design count — Before launching compute, estimate budget:

   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).
5. 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.
6. After screening, compute accept-or-rerun — Once by-screening writes the per-round summary, run:

   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.
3. by-deploy-compute (if compute target is hpc) — packages the engine container, syncs target data, dispatches the job. Handles RunPod / Modal / SLURM.
4. by-screening — runs the full screening battery (ipSAE, ipTM, pLDDT, RMSD, liabilities, developability) on the design output. Writes screening_summary.json.
5. by-scoring — applies canonical formulas (composite, multi-seed aggregation, asymmetry checks) on top of screening output.
6. Back to by-design-workflow (this skill) in accept-or-rerun mode — after screening, compute the verdict (ACCEPT / RERUN / SWITCH_TOOL / ESCALATE).
7. 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