001tmf/blatant-why/by-campaign-manager

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

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.

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

1. 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 for trade-offs.

1. Tier / budget:

• Preview (5–10 designs), Standard (20–50), or Production (100+)?
• Default = Standard. Recommend Preview first for novel targets.

1. Epitope / hotspots:

• Specific residues to target, or let the research agent derive from structure?

1. Resume vs new campaign:

• Is there an existing campaign directory to resume? Run /by:resume first.

1. Success criteria weighting:

• Hit rate, diversity, confidence, or balanced? Affects composite score in screening.

Standard Workflow

🚨 MANDATORY: USE SCRIPTS EXACTLY AS SHOWN — DO NOT WRITE INLINE CODE 🚨

This skill orchestrates other agents. The campaign-manager itself runs two CLI scripts (estimate, track) and dispatches sub-agents via Task(). Do not inline cost math or progress polling — the scripts are the source of truth.

0. Pre-Campaign Discussion

Before any campaign planning begins, run /by:plan-campaign to capture user preferences. This command produces campaign_context.json in the active campaign directory.

What campaign_context.json Controls

When campaign_context.json Exists

All downstream agents read it:

• by-research focuses on user-specified epitope regions and target features relevant to the chosen modality.
• by-design uses the specified modality, scaffolds, and compute tier without guessing.
• by-screening applies success criteria to weight composite scoring (e.g., diversity mode promotes cluster variety over raw scores).

When campaign_context.json Does Not Exist

Fall back to auto-detection: modality from keywords, scaffolds from modality defaults, compute tier standard, epitope from structure analysis.

✅ VERIFICATION: campaign_context.json exists in campaign directory; modality, tier, scaffolds populated.

1. Campaign Planning

1.1 Assess Target Difficulty

Before sizing a campaign, classify the target:

For well-studied targets, a preview campaign often suffices. For novel targets, plan at least two rounds with parameter variation.

1.2 Choose the Right Tool

If the user wants an antibody or nanobody scaffold, always use BoltzGen. For general protein binders (non-immunoglobulin), use PXDesign. Use Protenix for independent structure validation of top candidates.

1.3 Size the Campaign

Always start with preview before committing to standard or production.

1.4 Estimate Cost on Each Compute Target

🚨 MANDATORY: Run the estimator BEFORE launching any GPU job.

python scripts/estimate_campaign.py \
  --target <target_name> \
  --modality <vhh|scfv|denovo> \
  --tier <preview|standard|production> \
  --scaffolds <N> \
  --provider <local|hpc|tamarind|all>

✅ VERIFICATION: Output shows three rows (local, HPC RunPod, Tamarind) with wall-clock hours, cost USD, and a confidence interval. Cost JSON written to cost_estimate.json.

See references/cost-model.md for the full per-engine hours/cost breakdown.

1.5 Campaign Directory Structure

campaigns/{target_name}/campaign_{YYYYMMDD}_{NNN}/
  campaign_context.json      # User preferences (from /by:plan-campaign)
  campaign_log.json          # Top-level state (updated every transition)
  cost_estimate.json         # Pre-launch cost breakdown
  config.yaml                # Engine parameters (passed to BoltzGen/PXDesign)
  checkpoints/
    00_draft.json
    01_configured.json
    02_designing.json
    ...
  research/                  # by-research outputs
  run_001/                   # Individual run output
    designs/
    scores/
    summary.csv
  run_002/...
  aggregated_results.csv     # Cross-run merged ranking

2. State Tracking

2.1 Campaign State Machine

draft → configured → designing → screening → ranked → submitted
                          ↘ failed     ↘ failed   ↘ iterated → designing

See references/state-machine.md for the full diagram, transition triggers, and required artifacts at each state.

2.2 Run Lifecycle (within a round)

pending → running → screening → complete
            ↓                      ↓
            failed                 complete_with_warnings

• pending: Config written, awaiting GPU resources.
• running: Engine process active (backbone generation, sequence design, refolding).
• screening: Designs generated; running ipSAE, liability, developability checks.
• complete: All scores computed, results ranked, summary written.
• failed: Engine process crashed or timed out. Check stderr logs.
• complete_with_warnings: Finished but fewer designs passed than requested.

2.3 Tracking State