Walsworth-Group/physkit / skills/run-campaign
run-campaign
VerifiedLaunch, monitor, and steer a campaign's supervised loop, and stop it gracefully. A concierge, never an experiment executor.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 17.3 KB |
SKILL.md
View on GitHub---
name: run-campaign
description: >-
Launch, monitor, and steer a campaign's supervised loop, and stop it gracefully. A concierge,
never an experiment executor.
---
# run-campaign — the loop's cockpit
The loop is executed by the deterministic driver, not by this session. An interactive session that runs
the loop itself accumulates context until the campaign definition falls out of the window, stops re-reading the
docs, stops prematurely in ways prompting does not reliably fix, and uses verification sparingly
unless the gates are enforced in code. Hence the division of labor: the driver executes the loop with
fresh-context workers, and this session is the cockpit around it — launcher, monitor, and intermediary.
**Concierge, never executor.** Your write surface, in full: (1) `results/inbox/` notes; (2) the
launch/stop controls (the `--supervise` process and `results/STOP`); (3) launch-config repairs only
(`configs/loop.json` knobs, the harness executable override, a missing tool on PATH), because configs are
user-owned and are not ledgers. Never run a loop unit. Never edit the ledgers (the scoreboard
incl. its `finding` cells, logbook, journal) or anything FROZEN on your own judgment. Where a repair to
one of those is needed (a corrupt `results/driver_state.json`, a resolved ESCALATE), propose the exact edit and apply it only
on the user's explicit go-ahead. The science happens in the driver's workers, and everything you relay
travels through artifacts, so this session holds no scientific state and is disposable by design. While
the driver runs, idle cheaply: watch, relay, answer. Manufactured filler work burns agent budget without
buying the campaign anything. Two metric-epoch writes are the user's decisions relayed through you, on
their explicit word only: setting a pending epoch's `status` in `configs/loop.json`
`campaign.metric_epochs` (`ratified` / `rolled-back`), and moving the `campaign.metric_revision` dial
(`python scripts/run_campaign.py --set-metric-revision <mode>`). You never open an epoch yourself and
never judge one; `roles/REFERENCE.md` §Metric epochs is the loop's procedure, not yours.
**Where this runs.** A session opened in the campaign root. The campaign's managed instruction file
(`CLAUDE.md` in Claude, `AGENTS.md` in Codex) and hooks bind only there (`new-campaign` Step 5's
fresh-session rule). While the driver's `results/.driver_alive` sentinel
is fresh, the Stop hook stands down for attended sessions like this one; campaign-level loop persistence
is the driver's job.
## When to invoke
- Right after `new-campaign` finishes — it hands off preflight-green (metric implemented, selftest
passing, exp 000 run and recorded). This is the handoff's destination.
- "Start / launch / restart the loop", "resume the campaign."
- Process questions mid-run: "is it still running?", "what is it doing?", "why did it stop?"
- "Tell the loop to …" — any steering the user wants relayed without killing the run.
- Not for substance ("where do we stand", plateau, hygiene): compose `campaign-status` for those. It
reads the ledgers; you read the process.
## Step 0 — learn the campaign
Read the active harness's instruction twin and follow its **§Where things live** table to the loop contract this
cockpit operates (`roles/worker.md` §Long solves, escalation, and your exit, and its HARD GATE 5
for how the loop ends), `configs/loop.json`
(the knobs: timeouts, retries, `driver.*`, user-owned and hot-reloaded by the driver), and the current
state: `results/JOURNAL.md` (the **NEXT:** line and §What to try next and why — the campaign's only
forward-looking record, and what the next worker chooses its unit from) and
`results/driver_state.json` (the driver's counters: `accepted_units`, `last_accept_utc`,
`consecutive_operational_failures`), the newest `results/diagnostics/supervise_*.log` if one exists (how the last run ended),
and `results/ESCALATE.md` if present. An `ESCALATE.md` means a fork already awaits the user: surface it
first.
## Procedure
### 0.5 Confirm launch settings
Before every stopped-campaign start, restart, or resume, show the user the task's active harness and the
campaign's selected backend plus the worker and verifier model/effort settings in `configs/loop.json`.
Render a blank setting as **default/inherited**. If this harness exposes trustworthy live concierge model
or effort metadata in the current session, compare it; otherwise say the live value is unavailable and
ask the user to confirm it from the app's model/effort picker. Never guess from a stale session-start value
or edit the app's own setting. A difference is informational, not a preflight failure: campaign roles may
intentionally differ from the concierge.
Offer four choices: keep the campaign settings; copy the concierge model/effort to both roles; choose
worker and verifier separately; or blank the role overrides so they inherit harness defaults. Change only
the active harness's fields (`model` + `claude_effort`, or `codex_model` +
`codex_reasoning_effort`), only with the user's explicit approval, and only while no supervisor is running.
Then run preflight, whose read-only launch-settings line is the final confirmation of what will spawn.
### 1. Preflight
Run the driver's own checks and translate them; never reimplement them. Select the backend matching this
task (`codex` in Codex, `claude` in Claude), and use the campaign's python:
```
python scripts/run_campaign.py --preflight --backend <codex|claude>
```
Every failure line names its fix. Apply the launch-config ones yourself (an unfilled `loop.json` knob, a
stale backend/model setting, `AUTORESEARCH_AGENT_CMD` for Claude/custom, or
`AUTORESEARCH_CODEX_EXE` when a Windows Codex alias cannot be probed). Surface substantive ones to the user: an
unimplemented metric or hook means scaffolding stopped short of its preflight-green gate (or the tree
was imported/hand-built) — point back at the `new-campaign` handoff list, and a missing
`results/`/`campaign.md`/`roles/worker.md`/`scoreboard.tsv` (the names the preflight itself reports — quote what it
printed, don't translate it) means you are not in a scaffolded campaign root at all. Fix the
directory; do not fabricate the tree. `--smoke` adds one real spawn when the user wants the full dress
rehearsal, at the cost of a model call. Green preflight → launch. Preflight also names the campaign's
metric epoch and, when `campaign.metric_revision` is not `cautious`, prints a NOTICE that the loop may
revise the metric without asking; read that line to the user before launching.
**A mechanics-class preflight failure** — the metric selftest red, a scorer or hook still a stub, a
wiring error the first experiment would trip — is handed back as above when the dial is `cautious`. When
it is `autonomous`, spawn a bounded repair agent instead: a fresh session in the campaign root, told to
follow `roles/REFERENCE.md` §Metric epochs as a `mechanics` fix (declare the epoch, fix, selftest and suite
green), then re-run preflight; a substantive failure (an unimplemented specification, data only the user
can stage) still hands back. You launch and narrate; you do not edit the scorer.
### 2. Launch
Start the driver as a background shell process from the campaign root and note its log file:
```
python scripts/run_campaign.py --supervise --backend <codex|claude>
```
Codex uses `codex exec` with a workspace-write sandbox, UTF-8 prompt stdin, and JSONL events; Claude keeps
its established `claude -p` command. Each role has independent harness settings in `configs/loop.json`:
Claude reads `model` + `claude_effort`, while Codex reads `codex_model` + `codex_reasoning_effort`; a blank
value inherits that harness's configured default. With `verify.strategy: auto`, Codex uses a fresh
driver-spawned thread at the worker's Codex model and effort as the refuter and validates its verdict schema,
evidence subject, and recorded thread identity; Claude keeps its established nested-refuter flow at the
`verifier` block's Claude model and effort. Stop the current supervisor before changing harness; the process-held lock
rejects an overlapping launch.
This is an OS process you background in your shell, not a background subagent. The worker role's
never-background-a-solve rule covers solver and agent work losing its heartbeat; the driver is the
process that watches heartbeats, and it keeps its own decision trace at
`results/diagnostics/supervise_<ts>.log`. Confirm liveness (the launch banner and `results/.driver_alive`
appearing), tell the user the loop is running and where the log lives, then go quiet.
New or migrated campaigns whose runner includes `scripts/supervisor_lock.py` hold
`results/.supervisor.lock` for the whole supervised run. A second launch refuses before preflight,
logging, state access, or spend and prints best-effort owner metadata. The file is persistent diagnostic
metadata: its existence alone does not mean the lock is held, so never delete it to recover or switch.
Stop the first supervisor and wait for it to exit, then launch the other harness normally. Legacy campaigns
without that helper have no automatic exclusivity: stop and confirm the current supervisor has exited before
switching, or migrate the campaign first. A hard supervisor crash with a possibly surviving detached child is
not proven safe by kernel-lock release; inspect and stop that child before relaunching.
### 3. Monitor
On request, or at a periodic check-in, read; never re-derive:
- the driver log tail: current unit, rendered worker feed, accepted-unit count, the
`brief[role]` size line before each spawn (a `(TRUNCATED)` section, or a `preflight WARN: brief` at
launch, is the driver reporting the JOURNAL over its cap — relay it), the one check each result is
owed (`verification owed (preset light): peer (survival) - …` on the unit's record; then
`<exp> is a new best: its peer check waits until the next unit does not beat it`, `peer check owed for
<exp> (survived <exp>): the next worker runs it first`, `verifier check owed for <exp> (…)`, or
`<exp> was beaten by <exp> before its … check - no check of its own`), the `verifier[...]` lines
that follow, the `suite demotions changed` line when a slow check is metered out of the every-set, and
the `capstone` spawn when the loop ends — a `STOP` file, or a worker's `**NEXT:** STOP - <why>`
judgement (the claim audit, which re-checks the final best, under every preset but `none`; then a
halt: relay the worker's reason as a stopping decision the user now owns);
- `results/driver_state.json`: `accepted_units`, `last_accept_utc`, `consecutive_operational_failures`,
and the owed checks — `awaiting_survival` (a new best waiting on the next unit), `peer_due` (peer
checks the next worker runs first) and `pending_verification` (verifier checks the driver is still
obtaining); a list that keeps growing means verification is failing while the loop runs — surface it;
- `results/inbox/`: notes awaiting the next spawn — the user's, and the driver's own after a REFUTED or
INCONCLUSIVE verdict named a follow-up (`verifier_<exp>.md`), or after a worker's contest of its own
result's gate outcome was decided (`contest_<exp>.md`: the verdict, whether the driver promoted, the
follow-up). A `results/contests/<exp>.json` still `pending` with nothing in `pending_verification`
behind it is a fact to surface: the independent check the worker asked for never got owed.
Report process facts in plain language ("worker on exp007, third unit this run; one unit failed
operationally overnight, spawn timeout, the loop continued"). A `[supervise] campaign.metric_epochs:` or
`campaign.metric_version:` line is a metric epoch opening or a ratification — relay it as such, with
the epoch's kind and direction. You own the progress alarm. CORE requires
monitoring progress rather than liveness, because a loop can be alive, logging, and doing zero science:
if `accepted_units` sits flat across real wall-clock (`configs/loop.json` `unit_cost` sets the scale), raise
it unprompted, since no other session is watching. For anything about the science (is the best real, has
progress plateaued for a physics reason, journal hygiene) invoke `campaign-status`. Do not answer
substance from a process log.
### 4. Relay (the inbox)
A user request for the loop becomes a note in `results/inbox/` (any `.md` filename):
- Steering, corrections, context, priorities → inbox (create the folder if the campaign lacks it).
The driver injects it verbatim into the next worker prompt and archives it; workers must
acknowledge it in the journal. Check that they did, and tell the user when their note has been picked
up.
- Write the user's intent, attributed and dated. Do not editorialize. One note per topic.
- Escalation-worthy content is different. If the user is answering an ESCALATE fork, relay their
decision; on their explicit instruction, record it and delete `results/ESCALATE.md`, then relaunch.
If the user wants the loop stopped, that is Step 6, not a note.
### 5. Halts
The driver halts loudly and says why. Classify from the log tail and `results/driver_state.json` before
proposing anything:
- **Operational failures** did not halt the loop. Mention them with what the log says failed; a unit
worth re-running is a note in the inbox, never an edit of yours.
- **SYSTEMIC halt** (N consecutive operational failures): an environment problem. Check the agent CLI,
credentials, disk, and what the log says each failed spawn did; fix, then relaunch on the user's
go-ahead.
- **Disk-floor halt**: free space fell below this campaign's floor, so the driver stopped before a unit
could write half a save-set. Report how much is free and what one unit costs (`configs/loop.json`
`unit_cost.typical_disk_mb`), then offer the options: free space, move the tree to a larger volume, or
apply the retention plan in `roles/worker.md`. That plan drops regenerable bulk artifacts,
never the permanent record, and only with the user's confirmation.
- **Metric-revision proposal**: `ESCALATE.md` carrying a `## METRIC-REVISION PROPOSAL` block (the loop
believes the FROZEN metric is wrong and the dial is `cautious`). Surface it verbatim — the claim, the
verdict artifact, the proposed specification and scorer change, its kind and direction (an `easier`
ruler is the one to scrutinize), and the re-baseline cost. The user decides. On their explicit go:
bump `campaign.metric_version`, add the `campaign.metric_epochs` entry exactly as proposed with
`status: "pending"` and `opened_by: "user"`, delete `ESCALATE.md`, and relaunch — the relaunched
worker enacts the specification and scorer change under the declared epoch *before its first unit*
(`roles/REFERENCE.md` §Metric epochs says so; the runner binds an epoch's scorer hash on the first
experiment, so a unit run first would bind the new epoch to the old scorer) and lists the
re-baseline under the JOURNAL's *What to try next and why*. On a decline: note it in the JOURNAL, delete the file, relaunch. A pending epoch opened in `autonomous` mode reaches you
the same way, later: `campaign-status` lists pending epochs, and the user ratifies through you.
- **Integrity halt**: `ESCALATE.md` (surface the fork verbatim; this is the user's decision, not
yours), or a corrupt `results/driver_state.json` (diagnose, propose the exact JSON repair, apply it only
on the user's go-ahead; it holds the driver's counters, never the science).
- **The worker judged the campaign done**: a JOURNAL whose `**NEXT:**` line reads `STOP - <why>`. The
driver ran the claim audit and halted. This is a stopping decision for the user, not a failure —
relay the worker's reason and the audit artifact verbatim, and suggest `campaign-status` for the
evidence. Relaunching without changing the JOURNAL's NEXT line just re-derives the same STOP.
- A driver that died with no halt message (crash, reboot): the log just stops, `.driver_alive` goes
stale, and the Stop hook re-arms. Relaunch is safe; the next worker picks the campaign up from the
JOURNAL.
### 6. Stop
Graceful stop: create `results/STOP`. The driver honours it at the campaign level, and the current unit
finishes and logs first. Confirm the driver exited, then remind the user that deleting the file re-arms
the loop for the next launch. `Ctrl-C`, or killing the process, is the immediate stop: the current unit
is killed and unsaved, and the next worker re-chooses from the JOURNAL. Stopping is the user's call. Never stop
the loop on your own judgment; if you believe it should stop, say so and ask.
## Notes
- This skill runs no experiments and interprets no results. A mid-tier model is sufficient for watching
and relaying. Halt classification and ESCALATE surfacing are judgment calls; do not push those to the
cheapest tier.
- If the campaign's Stop hook blocks your end-of-turn (it stands down while the driver runs, but the
campaign is armed and the driver may be down: before launch, after a halt, after a crash), do not
start executing loop units. The remedy is the block message's own first option: launch or relaunch
the driver. If the user's intent is to stop, make the stop official (`results/STOP`) instead.
- Composition: `campaign-status` for substance (health, plateau, hygiene, the JOURNAL's boundedness and
currency);
`campaign-review` after the loop is finished; `verify` is the workers' tool, not yours.
- If this session dies, nothing is lost. The driver does not notice, and any fresh session in the
campaign root can pick the cockpit back up with this skill.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |