catgo-campaign — run a file-first computational campaign

A "campaign" = a coordinated multi-step study (many calculations → analysis → report) toward one research goal. This skill drives it via the portable catgo campaign CLI, which dispatches to CatGo's campaign reference scripts.

Launcher (works from any directory)

Run via the catgo CLI:

catgo campaign <action> ...

With an editable install (pip install -e <repo>/server) the CLI reflects the LIVE repo source, so edits to the campaign scripts/SKILL take effect immediately, no reinstall. If catgo is not on PATH (env not activated), use the entry point inside its python env directly: <env-prefix>/bin/catgo campaign .... In the steps below, catgo campaign means that launcher.

Before anything: confirm the environment (NEVER guess)

Ask the user and record in cluster.md: which cluster + SSH host/account + partition/walltime/ntasks, the compute binary + load method (module/conda/full path + run command), the POTCAR/pseudopotential 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 catgo campaign fetch-ref). catgo campaign submit REFUSES until cluster.md is complete. A wrong path fails every job — if unsure, STOP and ask.

Steps

1. Scaffold at the user's chosen location: catgo campaign new /path/to/Project --name "<name>" --template saa_her|blank

2. Plan — ASK the user: brainstorm the plan together (literature-grounded, one question at a time, propose approaches) OR use the template / generate directly.

3. Reference script (optional): catgo campaign fetch-ref --project <dir> --ssh <alias> --remote_path <.sb>

4. Per calc: build inputs into the LOCAL calc folder, then the input-file gate (below), then catgo campaign submit --project <dir> --calc calc/<stage>/<candidate> --ssh <alias> (skip the gate only on explicit YOLO opt-in).

   ⛔ INPUT-FILE GATE (hard rule — catgo-campaign + autochem). Before ANY submit (and after a calc converges, before building the NEXT step's inputs): sync the CONTCAR and the INCAR to the LOCAL campaign folder, and tell the user the exact LOCAL file paths of the INCAR + CONTCAR. The user reviews / edits / confirms the files THEMSELVES on disk. Submit ONLY after the user explicitly confirms. Do NOT push structures to the CatGO viewer as a substitute for local-file review of inputs, and NEVER auto-submit. (Waived only by explicit YOLO.)

5. Loop (~10 min, user-triggered): catgo campaign poll --project <dir> --ssh <alias> marks DONE/FAILED via squeue→sacct. A scheduler DONE != converged — open the work_dir outputs to confirm, write numbers into the calc's result.md, log gotchas in LESSONS.md.

6. At a stage / decision point: catgo campaign aggregate --project <dir> --plot (ranking / volcano / funnel), then checkpoint with the user.

7. Report: catgo campaign report --project <dir> --occasion groupmeeting

8. Literature: catgo campaign ingest --project <dir> --pdf <p.pdf> (MinerU) or --repo <url> --purpose "…".

9. Archive (clean the tree, never auto-decide): catgo campaign archive --project <dir> --list proposes FAILED calcs (funnel rejects are kept as data); move one only on the user's explicit OK: catgo campaign archive --project <dir> --calc calc/<stage>/<name> --reason "…".

Notes

• Default to a review gate (user-in-the-loop); only auto-advance on explicit opt-in.
• Full conventions live in the in-repo skill server/catgo/workflow/skills/campaign/SKILL.md (read it for the folder layout, progressive-md rules, two-level plan, gate details).