Campaign

---
name: campaign-md-orchestration
description: Drive a file-first, agent-in-the-loop computational campaign via a folder + markdown tree (no DB). Use when the user opts out of the visual workflow engine.
---

# Campaign (md-orchestration) — agent playbook

> **TL;DR:** Run multi-step HPC campaigns from a human-readable folder + markdown
> tree. You (the agent) read `plan.md` + `STATUS.md`, render inputs, submit via
> the reference scripts (plain ssh sbatch), update markdown, and check in at
> gates. No DB. Files are the source of truth.

## When to use

The user chose md-orchestration over the visual workflow engine (exploratory /
iterative / mixed-software / cross-cluster work). The visual DB engine still
exists for fixed routines + teaching — don't use this skill for those.

## Conventions

Authoring conventions (progressive md, README+INDEX pairs + keeping them current, logging
interventions to LESSONS, human-readable/never-hash names, the top→stage→calc progressive
plan, filling scaffold stubs) live in the **`catgo-campaign-conventions`** skill — follow
it whenever you create/edit campaign markdown.

## Setup gate — confirm the environment (NEVER guess)

Before submitting anything, confirm with the user and record in `cluster.md`:
cluster identity + SSH host/account + partition/walltime/ntasks, the compute
binary + load method (module/conda/full path + run command), the POTCAR root,
the python env, and the remote base dir. The user may give a reference job
script — local, or **a path on the cluster** (pull it with `fetch_ref.py`);
CatGO adapts it instead of synthesizing the preamble. Run `catgo_validate_config`
before the first submit. `submit_calc.py` **refuses** while `cluster.md` is
incomplete — this is enforced in code, not just here. Never guess cluster paths.

## Gates (default human-in-the-loop)

1. **Input-file gate (per submission).** Before each `submit_calc.py`, show the
   user the rendered `INCAR`/`POSCAR`/`KPOINTS`/`POTCAR`/`job.sb` and ask to
   confirm. Run the script only after they confirm.
2. **Stage / decision-point checkpoint.** At a stage end or a `plan.md` decision
   point, write a stage summary and ask: proceed / modify / stop.

**YOLO / autopilot opt-in** disables both gates. Set it only if the user says so
per-run ("go as you set" / "yolo") or persistently ("always skip review"). With
YOLO off and the user away, hold at the gate: keep polling running jobs but
submit nothing new and cross no stage.

## Plan creation — ask the user first

Before writing or finalizing `plan.md`, ASK the user how to create it — do not assume:

- **Brainstorm together** — read `literature/INDEX.md` first, then ask clarifying
  questions ONE at a time (goal, candidate set, descriptor, funnel thresholds,
  reference systems), propose 2-3 stage / decision-point approaches with a
  recommendation, and write `plan.md` only after the user approves.
- **Template / direct** — instantiate a template (e.g. `saa_her`) or generate
  `plan.md` from the user's stated intent, then let them review and edit it.

Default to asking. Skip the question only if the user already opted in
("just use the template" / "go as you set" / YOLO).

**Derive the full pipeline from the TARGET OBSERVABLE — before building ANY input.**
Work backward from what the user wants to measure to every calc it requires, and write
that into `plan.md` BEFORE scaffolding structures/inputs (the build order is: plan first,
inputs second). Common traps:
- **Overpotential / free-energy diagram / ΔG / Gibbs / adsorption *free* energy** ⇒ needs
  free energies, not raw DFT energies ⇒ **follow the `catgo-gibbs-pipeline` skill** (the
  per-species `geo_opt → freq → gibbs` pipeline, freq setup, gas-ref convention, CHE, η).
  Wire freq as the auto-next-step after each species' geo_opt in `plan.md`.
- **Reaction barriers / TS** ⇒ NEB/dimer + a freq to confirm one imaginary mode.
- **Band gap / DOS / COHP** ⇒ a dense-k static after relax.
Confirm the full stage list with the user before building. Do NOT jump from "scope" to
rendering inputs — discuss the plan (and its observables) first.

## The loop + resuming

Driving the ~10-min poll loop (delegate each poll to a subagent → compact summary; verify
convergence by **force**; auto-advance each converged species per-species, pipeline not
barrier; stage checkpoints) AND resuming a campaign from disk after compaction / a new
session live in the **`catgo-campaign-loop`** skill. Gates stay with the main agent.

## Scripts (in `scripts/`, see scripts/INDEX.md)

```
python new_campaign.py <dir> --name "<name>" --template saa_her|blank
python fetch_ref.py   --project <dir> --ssh <alias> --remote_path <cluster .sb>
python submit_calc.py --project <dir> --calc calc/<stage>/<candidate> --ssh <alias>
python poll.py        --project <dir> --ssh <alias>
```

Run them as-is (gates enforced), or read `scripts/campaign_lib.py` and adapt for
the unforeseen (mixed software / odd clusters / novel calc types).

## Archiving (explicit / propose — never auto-decide)

Keep the live tree clean by moving superseded/abandoned calcs into `archive/`, but
NEVER guess what is stale: `python archive.py --project <dir> --list` proposes only
`STATUS=FAILED` calcs (it does not move anything). **Funnel rejects (a DONE calc with a
high E_form) are kept** — the ranking/volcano/funnel need them as data. Move one only on
explicit user instruction: `python archive.py --project <dir> --calc calc/<stage>/<name>
--reason "..."` (leaves a tombstone `ARCHIVED.md` at the original location).

## catgo CLI during a campaign

Use the existing `catgo` CLI for the actual chemistry — see
`references/catgo-cli.md`. Build structures (`catgo slab`/`supercell`/`reticular`/
`convert`/`inspect`) and analyze results (`catgo dos`/`band`/`cohp`/`freq`). These
run offline (no viewer needed). Aggregate per-calc `result.md` files with
`scripts/aggregate.py`; draft reports with `scripts/make_report.py`; ingest
literature with `scripts/ingest_lit.py`.

## Literature -> plan -> skill

Drop papers (PDF -> MinerU md) + GitHub repos into `literature/`; ground `plan.md`
in them with citations. Mine reusable recipes into `literature/extracted-skills.md`;
promote the best into the global SKILL library.