# By Design Workflow

> BY Design Workflow — Master Orchestration Skill

- Skill: `001tmf/by-design-workflow` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add 001tmf/by-design-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/001tmf/by-design-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: 001TMF (https://skillmd.com/u/001tmf)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/001tmf/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/`.

| 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 (target file, hotspots, YAML config skeleton) | protenix / pxdesign / boltzgen skill |
| `pass_rate_forecast.json` | JSON | Expected pass rate range + minimum-viable design count | by-campaign-manager (budgeting) |
| `accept_or_rerun.json` | JSON | After a campaign round: verdict (`ACCEPT` / `RERUN` / `SWITCH_TOOL` / `ESCALATE`) + reasoning | by-campaign-manager, the user |

**Key shape — `routing_decision.json`:**

```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`:**

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

| Modality | Engine | Protocol / Preset | Default Tier | Pass Rate (median) | Default Compute |
|----------|--------|-------------------|--------------|--------------------|-----------------|
| VHH (nanobody) | BoltzGen | `nanobody-anything` | Standard | 25% | local GPU |
| scFv / Fab / IgG | BoltzGen | `antibody-anything` | Standard | 20% | local GPU |
| De novo binder (well-studied) | PXDesign | `extended` | Standard | 30-50% | local GPU |
| De novo binder (feasibility) | PXDesign | `preview` | Preview | 10-30% | local GPU |
| De novo binder (fallback) | BoltzGen | `protein-anything` | Standard | 15% | local GPU |
| Structure prediction | Protenix | `base_default` | n/a | n/a | local GPU |
| Multi-seed ensemble fold | Protenix | `base_default`, 5 seeds | n/a | n/a | local GPU |

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:

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

| Identifier | Format | Used By |
|------------|--------|---------|
| `label_seq_id` | 1-indexed, sequential, per-chain integer | every BY engine (canonical) |
| `auth_seq_id` | PDB author numbering, may have gaps / insertion codes | external publications, PyMOL |
| Array index | 0-indexed Python position | internal scripts only |

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

| Provider | Cost | Latency | When to Use | When NOT to Use |
|----------|------|---------|-------------|------------------|
| `local` | $0 | None (instant) | Default — user owns the hardware | Target > local memory budget |
| `hpc` (RunPod / Modal / SLURM) | $3-5 / GPU-hr | minutes (cold start) | Local OOM, multi-GPU production runs | When local has capacity |
| `tamarind` | $5+ / GPU-hr | minutes-hours (cold-start queue) | No local GPU, no HPC account | If local or HPC is available |

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):

| Campaign Profile | Total Designs | HPC Cost (approx) | Local Wall Time | When |
|------------------|---------------|--------------------|--------------------|------|
| Preview only | 500-1000 | $5-15 | ~1 hr | Feasibility |
| Standard, 1 modality | 5K-10K | $50-100 | 3-5 hr | Exploration |
| Standard, 2 modalities | 10K-20K | $100-200 | 6-10 hr | Modality comparison |
| Production, 1 modality | 20K-40K | $250-500 | 10-20 hr | Final candidate pool |
| Exploratory, multi-modality | 50K-100K | $1000-2000 | 25-50 hr | Novel target, publication-grade |

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)`.
4. **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)`.
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:
   ```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

| Issue | Cause | Solution | Details |
|-------|-------|----------|---------|
| User says "design a binder" without modality | Ambiguous request; could be VHH, scFv, or de novo | Ask Q1 explicitly. Do NOT default to VHH silently — confirm before routing. | `references/tool-selection-matrix.md` |
| Target has no PDB structure | Sequence-only target; no experimental fold | Run Protenix fold first (single seed for preview, 5-seed ensemble for production). Crop high-pLDDT domain if full-length is disordered. | `references/quality-thresholds.md` Fold-Validation |
| Target > 1500 residues, local OOMs | BoltzGen / PXDesign exceeds 80 GB at full target | Crop to binding domain + 10 Å buffer; if still OOM, switch compute target to HPC (RunPod A100/H100 80GB) via by-deploy-compute. | `references/preset-comparison.md` Memory-by-Tier |
| Multi-chain complex target (e.g., trimer) | Hotspots span multiple chains; tools default to one target chain | Set target as the assembled complex; specify hotspots with chain prefix (`A45,B112`); pre-validate fold with Protenix multimer prediction. | `references/tool-selection-matrix.md` Multi-Chain |
| Multi-target screening request | User wants the same protocol against N targets | Sequential: one routing decision per target; share scaffold pool. Parallel: batch via by-deploy-compute HPC array job. Choose by total design count: < 5K total → sequential; ≥ 5K → batch. | `references/preset-comparison.md` Multi-Target |
| Off-target / polyspecificity concern | Therapeutic candidate must avoid binding human paralogs | Add post-design polyspecificity screen via by-screening (`screen_cross_validate`); reduce composite weight on `ipSAE_min` and add explicit cross-reactivity penalty. | `references/quality-thresholds.md` Polyspecificity |
| Low compute budget, large design space | Tier mismatch: user wants Production but budget covers Preview | Run Preview tier first, gate Production on Preview pass rate ≥ 15%; if not, escalate to user. Never silently shrink Production to Preview. | `references/preset-comparison.md` Budget-Gating |
| `compute.default_provider="local"` but local GPU absent | `.by/config.json` stale or wrong machine | Run `by-session` to re-detect compute; if no local GPU, prompt user to switch to `hpc` or `tamarind`. Never silently route to cloud. | by-deploy-compute SKILL.md |
| PXDesign fails twice in a row | CUDA / env mismatch on local install | Switch to BoltzGen `protein-anything` (de novo fallback) after 1 failed launch. Do NOT spend multiple cycles fixing PXDesign env mid-campaign. | `references/tool-selection-matrix.md` De-Novo-Fallback |
| Designs have good ipTM but low ipSAE | Interface confident but partial; ipSAE asymmetry > 0.3 | Re-run with tightened hotspots (drop 1-2 residues at the edges); if asymmetric ipSAE persists, switch modality (de novo → VHH may engage differently). | `references/quality-thresholds.md` ipSAE-Asymmetry |
| Pass rate < 10% on Preview | Hotspots too dispersed or wrong epitope | Re-run epitope analysis (`by-epitope-analysis`); narrow hotspot window to 3-5 spatially clustered residues. If second Preview also fails, escalate. | `references/quality-thresholds.md` Re-Run-Criteria |
| Modality unclear, user wants "best chance" | No modality preference, novel target | Default order: VHH (highest pass rate, simplest), then scFv, then de novo. Justify the choice in `routing_decision.json.rationale`. | `references/tool-selection-matrix.md` Modality-Selection |
| Target is a ligand / small molecule, not protein | Wrong tool family — BY engines are protein-protein interfaces | Refuse the campaign politely. Suggest small-molecule docking tools (out of scope for BY). Document refusal in `routing/notes.md`. | `references/tool-selection-matrix.md` Out-Of-Scope |
| Glycosylated surface near hotspots | BoltzGen does not model glycans by default | Implementation-engineer persona in `by-research` Phase 6 should have flagged this. Shift hotspot window or accept reduced confidence. | by-research SKILL.md Phase 6 |

---

## 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`](references/tool-selection-matrix.md) — full modality × tool × preset × hotspot × pass rate × compute matrix with per-cell rationale.
- [`references/preset-comparison.md`](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`](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`](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`](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`](../README.md) — canonical terminology, skill linkage map, end-to-end workflow.
- [`templates/CLAUDE.md`](../../../CLAUDE.md) — BY agent identity, compute provider selection, campaign workflow overview.
- [`by-research/SKILL.md`](../by-research/SKILL.md) — produces upstream `design_recommendation.json`.
- [`by-campaign-manager/SKILL.md`](../by-campaign-manager/SKILL.md) — consumes downstream `routing_decision.json`.
- [`by-deploy-compute/SKILL.md`](../by-deploy-compute/SKILL.md) — HPC dispatch details (do not re-document here).
- [`by-scoring/SKILL.md`](../by-scoring/SKILL.md) — canonical ipSAE / ipTM / composite formulas.
- [`by-screening/SKILL.md`](../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