/by-campaign-manager

id: "skill_d4e763ef03f044248cc5202d582f28d7"
name: "by-campaign-manager"
display-name: "BY Campaign Manager"
short-description: "Plan, size, monitor, checkpoint, and assess protein/antibody design campaigns end-to-end. Use when starting a campaign, tracking run state, estimating cost/time, resuming after interruption, or evaluating campaign health mid-run."
category: "orchestration"
keywords: "campaign, planning, state machine, checkpoint, resume, cost estimate, health, multi-run, orchestration, tier, modality"
version: "1.0"
last-updated: "2026-05-20"
mcp_tools: ["mcp__by-campaign__campaign_get", "mcp__by-campaign__campaign_create", "mcp__by-campaign__campaign_update", "mcp__by-campaign__campaign_list", "mcp__by-knowledge__knowledge_query_similar", "mcp__by-knowledge__knowledge_scaffold_rankings", "mcp__by-knowledge__knowledge_get_recommendations", "mcp__by-knowledge__knowledge_store_campaign", "mcp__by-knowledge__knowledge_store_failure", "mcp__by-cloud__cloud_get_batch_status"]

BY Campaign Manager

Plan, execute, monitor, and assess protein/antibody design campaigns. This skill governs how to size a campaign, track run state, coordinate multi-run efforts, estimate cost and time on each compute target (local GPU, HPC, Tamarind), monitor progress, and evaluate campaign health.

---

When to Use This Skill

Use this skill when you need to:

• ✅ **Start a new design campaign** — size designs/scaffolds, pick modality, choose compute tier
• ✅ **Track run state** through the campaign state machine (draft → configured → designing → screening → ranked → submitted)
• ✅ **Estimate cost and time** before launching (local GPU hours, HPC $/hr, Tamarind credits)
• ✅ **Resume an interrupted campaign** from the last checkpoint without re-doing work
• ✅ **Assess mid-run health** — pass rate trajectory, score distributions, abort/continue decisions
• ✅ **Coordinate multi-run efforts** — vary one parameter axis at a time, aggregate cross-run results
• ✅ **Decide when to iterate** — low pass rate, poor scores, insufficient diversity

**Don't use this skill for:**

• ❌ Target research and epitope mapping → use `by-research`
• ❌ Submitting individual jobs or scoring single designs → use `by-design` / `by-screening`
• ❌ Lab submission gating → use `by-lab` (triple-gated)
• ❌ HPC infrastructure setup → use `by-deploy-compute`
• ❌ Sequence/structure clustering for diverse panels → use `by-diversity`

---

Quick Start

A typical campaign launch from the planner sub-agent:

# 1. Capture user preferences (modality, tier, scaffolds)
/by:plan-campaign

# 2. Estimate cost on each compute target before approval
python scripts/estimate_campaign.py \
  --target PD-L1 \
  --modality vhh \
  --tier standard \
  --scaffolds 2

# 3. Initialize campaign state and launch design phase
#    (delegate via Task(by-design, ...))

# 4. Monitor mid-run
python scripts/track_progress.py \
  --campaign-dir campaigns/pdl1/campaign_20260520_001

Expected `estimate_campaign.py` output: cost table for local / HPC RunPod / Tamarind, with wall-clock hours and confidence intervals.

Expected `track_progress.py` output: designs submitted / scored / passed counts, running pass rate, ETA, and spend-to-date.

---

Inputs

**Required:**

• **`campaign_context.json`** — captured by `/by:plan-campaign`; contains modality, tier, scaffolds, epitope, success_criteria
• **`research/recommended_hotspots.json`** — from `by-research`; residue list for design agent
• **`research/design_recommendation.json`** — from `by-research`; modality, scaffolds, tier rationale

**Alternative inputs:**

• **User-supplied target name and PDB ID only** — falls back to auto-detection (modality from keywords, scaffolds from modality defaults, tier=standard)

**Optional:**

• **`.by/config.json`** — compute provider, model profile, fallback policy. If missing, defaults to `local` provider, `balanced` profile.
• **Prior campaign IDs** — queried via `mcp__by-knowledge__knowledge_query_similar` to bias scaffold and parameter choices.

See [references/state-machine.md](references/state-machine.md#required-artifacts) for the full artifact contract at each state.

---

Outputs

**Primary results:**

• **`campaign_log.json`** — top-level campaign state (campaign_id, target, tool, status, rounds, costs, history). Updated at every state transition.
• **`checkpoints/NN_<state>.json`** — one file per phase transition. Resume reads the highest numeric prefix. See [references/state-machine.md](references/state-machine.md#checkpoint-file-format).

**Per-run outputs (under `run_NNN/`):**

• `designs/` — generated structures
• `scores/` — ipSAE, ipTM, liability JSON
• `summary.csv` — per-design metrics

**Cross-run outputs:**

• `aggregated_results.csv` — merged ranking across rounds with composite score
• `cost_estimate.json` — pre-launch breakdown by compute target (local/HPC/Tamarind)
• `progress_snapshot.json` — written by `track_progress.py` on demand

**Reports:**

• `campaign_plan.md` — approved plan with rationale, written by the `by-campaign` agent
• `verification_report.md` — final independent verification by `by-verifier`

---

Clarification Questions

⚠️ **CRITICAL: ASK THIS FIRST** — confirm the user has an approved plan before any compute is spent.

1. **Plan approval (ASK THIS FIRST):**

• Has `/by:plan-campaign` been run, and has the user approved the resulting plan?
• If no: route to plan capture first. Do not estimate costs against a plan that does not exist.

2. **Target and modality:**

• What is the target (name, PDB ID or UniProt accession)?
• Antibody, nanobody (VHH), or de novo protein binder?
• Example: "PD-L1 (PDB 7S4S), VHH" → triggers `nanobody-anything` protocol.

3. **Compute provider:**

• Local GPU (default), HPC (RunPod), or Tamarind cloud?
• Read `.by/config.json` `compute.default_provider`. Confirm with the user before overriding.
• See [references/cost-model.md](references/cost-model.md#provider-selectio