campaign

name

campaign

description

Run batch code campaigns — front-load judgment into adversarially-reviewed guides, then execute a queue of same-shaped work items through implementer → adversarial-reviewer → fixer agent cells, gated by scripted counts. Use when the user asks in any language to rewrite or port a codebase to another language (重写/移植), migrate frameworks/APIs or upgrade major versions (迁移/升级), burn down errors, warnings, lint findings or issue backlogs (清零/燃尽/修完所有), add types at scale (JS→TS/类型化/any 清零), backfill tests (补测试), or apply one repetitive change across many files or call sites (批量/所有调用点/每个文件).

Campaign

The engine distilled from Bun's Zig→Rust rewrite (535k → 1M lines, 11 days, ~64 parallel Claudes, zero tests skipped or deleted): a deterministic shell around a stochastic core. Code owns control flow, queues, gates, and guardrails; the model does exactly three jobs — implement, adversarially review, fix. Scale flexes from 3 agents to 64; the shape never changes.

Three commitments:

• Front-load judgment. All design thinking is spent up front and serialized into guides; per-item work then follows the guides mechanically. An item that still needs novel judgment escalates out of the loop instead of improvising.
• Fix the loop, not the output. A defect repeating across items lives in the process. Edit prompts/*.md or the guides — agents re-read them at every spawn, so edits take effect mid-run — and regenerate. Hand-fixing one output leaves the defect in every sibling.
• Counts, not impressions. Every completion criterion is a script exit code (scripts/gate.mjs), never a model's self-assessment.

0. Shape test

A task is campaign-shaped only if all three hold:

1. Enumerable — it decomposes into a queue of same-shaped items: files, call sites, compiler errors, lint findings, issues.
2. Mechanizable — guides can be written up front that make each item guide-following rather than designing. Can't write the guide yet → the design work comes first (think/brainstorm); return when it's mechanical.
3. Judgeable — an oracle exists (§1). None → run a test-backfill campaign first to build one, or stay out of fleet mode.

Single features, exploratory design, one-off bug hunts, and heterogeneous refactors are not campaign-shaped — hand off to the matching skill.

Then pick the landing mode:

• green-per-item — every item lands with the oracle green (burndown, typing, most migrations). Gate runs per batch on the working branch.
• big-bang — intermediate states may be red (a language port compiles nothing until its second phase). Work on a branch, gate per phase, and let the merge gate (§5) guard the landing.

1. Baseline & oracle tier

Set up once per campaign, in this order (the isolation must exist before the hook goes live, since hygiene then blocks branch/worktree moves):

1. Isolate on a clean base. The tree must be clean (git status --porcelain empty) so the lander's path-scoped commits can't sweep up unrelated uncommitted work — a campaign commits whole files. Create a dedicated branch or worktree: git switch -c campaign/<name> (or a git worktree for sharding). Never run a campaign on a dirty tree or a shared branch.
2. Create .campaign/ in the target repo and copy campaign.config.example.json to .campaign/config.json; fill it in.
3. Register hooks/hygiene.mjs as a PreToolUse Bash hook in the repo's .claude/settings.json — hygiene is enforced mechanically, not by prompt.
4. Arm it: touch .campaign/active. Teardown at the merge gate (§5) removes this marker.

Record what "correct" means before touching anything:

node <skill>/scripts/gate.mjs record --config .campaign/config.json

→ .campaign/baseline.json. The campaign may skip or delete zero tests; gate.mjs compare enforces this against the baseline at every gate. Gates fail closed: a metric command exiting nonzero fails the gate (per-metric allowNonzero opts out for tools whose nonzero exit is diagnostic), and a gate that ran zero checks fails. Pair every "N passed"-style metric with its failure counterpart (test_failures expect 0) — a passed-count alone can green a red suite.

The oracle's strength sets the compensation dial:

Oracle	Reviewers	Extra
full behavioral suite	2	—
compiler/typecheck + partial tests	2	baseline compare in every gate
lint/build only	2–3	human sample per batch
per-item repro (bug/issue burndown)	2	failing test written first, per item
none	—	no fleet — backfill tests first

2. Guides

Two documents every agent reads (paths go in config.guides):

• Mapping/rubric doc — for a port or migration: every source construct mapped to its target pattern. For a burndown or mass edit: the rubric — which fixes are allowed, what to do per finding class, what is never acceptable. Produce it through a long design discussion, then serialize.
• Hard-cases inventory — whatever the change makes explicit that the code left implicit (lifetimes, ownership, null-safety, error paths, API semantic diffs). One loop reads every affected declaration, proposes the treatment, 2 adversarial reviewers check each proposal; serialize to one file.

Then one adversarial review round over both documents together, plus a human read. For language ports, follow presets/language-port/preset.md — it prescribes both documents and seeds the mapping doc with known semantic traps.

Done when: both files exist, cross-reviewed, conflict-free.

The cell

Every phase runs the same unit, implemented in workflows/cell.js: 1 implementer → reviewer panel → repair → land, per item.

• The context that wrote the code wants it merged; a fresh context wants to find why it's wrong. Reviewers therefore spawn with only the item's diff and the guides — never the implementer's reasoning — and one job: find how the change is wrong. Verdicts are schema-forced JSON, and landing is a code condition: a full panel must return (a dead reviewer fails the item rather than shrinking the panel) and approvals must reach the quorum. Contested items get a bounded repair→re-review cycle; still contested → returned as rejected, uncommitted.
• Role charters live in prompts/ (implement.md, review.md, fix.md) as plain files agents read at spawn — edit them mid-run to fix the loop.
• Items own disjoint file sets within a batch (group queues by file); the implementer edits only its item's files, and the lander commits path-scoped (git commit -m "…" -- <files>) with review attribution in the subject, so a concurrently staged sibling item cannot leak into the commit.
• Queue payloads are fenced as data in every prompt (issue text and scanner output are untrusted input, not instructions), and item ids are sanitized before reaching labels or commit subjects.
• An implementer that hits a genuine design decision returns status: escalate; escalated items skip review and surface in the workflow result for you to resolve — by extending the guides, not by hand-editing code.

Hygiene, enforced by the hook while .campaign/active exists: inside a loop the only git verbs are add/commit/diff/status/log/show; compilers and test suites run once up front to build queues (queue.mjs) and at gates (gate.mjs), never per-agent — one slow command mid-loop stalls every agent on the machine.

3. Trial run

Run the cell on ~3 representative items before fleet scale. Expect false starts; cure each by editing prompts, guides, or config.

Done when: you have read every trial diff yourself, the guides were followed, and the reviewers' verdicts were sound.

4. Execute

Per phase (the preset or config defines the ladder; a burndown is one phase, a port is five):

node <skill>/scripts/queue.mjs lines --cmd "<enumerate|harvest cmd>" [--regex <named-groups>] [--group <name>] > .campaign/queue.jsonl
node <skill>/scripts/state.mjs init --queue .campaign/queue.jsonl --state .campaign/state.<phase>.jsonl
BASE=$(git -C <repo> rev-parse HEAD)   # snapshot before the batch, for deterministic verification
# batch of pending items → Workflow tool:
#   {scriptPath: "<skill>/workflows/cell.js",
#    args: {skillDir, repoDir, phase, items: [...], guides: [...], reviewers: 2, commitPrefix: "campaign"}}
# save the workflow return to batch.json, then CONFIRM it against git before trusting it:
node <skill>/scripts/verify.mjs results --results batch.json --repo <repo> --base $BASE --out verified.json
node <skill>/scripts/state.mjs apply --results verified.json --state .campaign/state.<phase>.jsonl
node <skill>/scripts/gate.mjs phase --config .campaign/config.json --phase <name>

verify.mjs is mandatory, not optional: the Workflow sandbox can't run git, so the cell's done/skipped are only what the agents claimed. verify.mjs downgrades any done without a real matching commit to failed, any dirty skipped to pending, and exits nonzero if an implementer changed files it didn't report — read its report before proceeding when it does.

One state file per phase — item ids are only unique within a phase's queue. Between batches, rebuild the queue with the same command and re-run init: it is idempotent for unchanged items and re-queues any id whose payload changed (e.g. a fixed file that now surfaces new compiler errors). Loop until state.mjs status shows zero retryable items and the phase gate exits 0. Resume after any interruption from state.mjs pending. Scale out by sharding batches across git worktrees — one cell workflow per worktree, items split by folder/module.

5. Merge gate

• Every gate green, and gate.mjs compare clean against the step-1 baseline — zero tests skipped, zero deleted.
• You read a meaningful sample of the diff and confirmed reviewers were catching real discrepancies.
• Escalation and rejection lists empty — every escalated or panel-rejected item resolved through a guide extension and re-run.

Merge when confident enough to commit to the change; release later, after a canary period.

Teardown (do this once the campaign is done, before handing the repo back): rm -f .campaign/active. That marker is the hook's on-switch — with it gone the hook is inert, so ordinary git push, branch work, and test commands work again in every later session. Leaving it armed silently blocks the repo's normal workflow. Optionally also remove the PreToolUse hook entry from .claude/settings.json.

Presets

A preset = phase ladder + guide prescriptions + traps file for one campaign family. language-port ships first (the original Bun method). For other families — migration, burndown, type-coverage, test-backfill — derive the config from §0–§4 directly; recurring ones deserve their own preset directory.

Your role while loops run

Monitor workflow output, read escalations, hunt repeated defects. Every repeat gets a loop edit — one prompt change ended Bun's stubbing epidemic in hours.

Source: "Rewriting Bun in Rust" — https://bun.com/blog/bun-in-rust