Use when building, operating, or resuming a deterministic Workflow() driver for a large autonomous multi-phase task — a full rewrite, a migration, a long audit. Triggers: design or implement a workflow driver script, translate a .agents/loops/*.md runner spec (looper output) into a Workflow() script, design phase gates or pause/resume mechanics, handle a paused driver run (retryStep bump, human arbitration, mutation suspected), harden a driver against non-deterministic agent behavior, or wrap an external CLI (e.g. codex exec) inside a workflow agent.
Use when building, operating, or resuming a deterministic Workflow() driver for a large autonomous multi-phase task — a full rewrite, a migration, a long audit. Triggers: design or implement a workflow driver script, translate a .agents/loops/*.md runner spec (looper output) into a Workflow() script, design phase gates or pause/resume mechanics, handle a paused driver run (retryStep bump, human arbitration, mutation suspected), harden a driver against non-deterministic agent behavior, or wrap an external CLI (e.g. codex exec) inside a workflow agent.
license
MIT
compatibility
Claude Code Workflow() scripts (deterministic JS driver, agent()/pipeline()/parallel(), resumeFromRunId prefix cache). Downstream of the looper skill's .agents/loops/*.md specs.
metadata
{"version":"0.1.0","author":"bengous"}
Deterministic Driver
Design, build, and operate a deterministic Workflow() driver: a plain-JS
script that owns every orchestration decision, while LLM agents are reduced
to schema-constrained executors, probes, and reviewers. The script judges
exit codes, fingerprints, and verdicts; no agent ever decides control flow.
Distilled from a real 10-phase rewrite run (bookmarker → Rust, 2026-07-15):
every rule below was paid for by an incident or measured on transcripts.
When to use
Build a driver for a big autonomous task (rewrite, migration, audit) with
phase gates, commits, and human escalation.
Translate a looper spec (.agents/loops/*.md) into a Workflow() script.
A driver run paused and you must resume it correctly.
Review or harden an existing driver.
When NOT to use: one-shot fan-outs, research workflows, anything without
durable state or resume requirements — plain Workflow() patterns suffice.
Architecture in one paragraph
The driver is invoked by scriptPath (never by name from inside the target
repo) and lives OUTSIDE the target repo whenever the repo is watched by
fingerprint — otherwise every operator edit mid-run poisons the protected-path
hash. Durable state lives in git (one driver commit per phase); the
prefix cache (resumeFromRunId) is a disposable accelerator. Agents come in
three shapes: mechanical executors (run listed commands verbatim, report
results by schema), read-only reviewers (fingerprint-sandwiched), and external
CLI wrappers (detached launch + blocking waits). Pauses are typed exceptions
carrying a mandatory retryStep and a self-sufficient howToResume — the
operator must never need to reread the script to handle a standard pause.
Git is the only durable state; the prefix cache is disposable.
A committed-check at the start of every phase (git log subject match)
makes cold restart cheap: committed phases are skipped, only the front
phase replays. Default to cold restart at inter-phase pauses; reserve
prefix resume for intra-phase pauses. A cold restart costs a handful of
probe agents — often less than a resume that replays a review cycle.
No "if X is available… otherwise" branch in any agent prompt.
That is an orchestration decision delegated to the LLM. Measured result:
with a conditional "use the code-review skill if available", agents
invoked it in 4 phases out of 9 and never even mentioned it in the others.
Impose the methodology (mandatory invocation), require invocation failure
to be reported explicitly, never allow a silent fallback. Verify required
tools by proof (transcript, modelUsage), not by trust.
Prompt rules in terms of OPERATIONS, never intentions.
"cp to scratch allowed, opening the file forbidden" — not "read-only".
Trap that forced this rule: opening a SQLite WAL database for reading
creates/touches the -shm file, so "read-only" is physically impossible
to honor on a stat-hashed profile directory. An intention rule the agent
cannot satisfy to the letter will be violated; an operation rule is
checkable and followable.
Both halves of a gate need the same temporal coverage.
A gate has a detection half (e.g. pgrep: browsers closed) and an
interpretation half (e.g. stat-hash pair: any change is the gate's
fault). If detection runs only at window start while interpretation
spans the whole window, the interpretation works from an assumption
detection no longer guarantees (TOCTOU). Check detection at both ends
of the window. Also decide what the gate actually protects: a
browsers-closed pgrep is a signal-quality device (makes the stat-hash
attributable), not the anti-corruption defense — that is the fail-closed
stat-hash pair itself.
Always bump the indicated retryStep — even when a prompt edit seems
sufficient.retryStep designates the OBSERVATION to replay, not the
faulty work: replaying only the failed step can leave a before/after
fingerprint pair incoherent (before cached, after live) and loop the
pause. One real resume worked without a bump purely by accident of
construction (an unrelated prompt change happened to break the cache
earlier); gated differently it would have replayed the cached failure
forever.
Gate mid-run prompt fixes by phase; de-gate everything on a fresh run.
The first agent() call whose prompt changes invalidates the whole cache
suffix. Mid-run, wrap any prompt hardening in p >= N so already-played
steps stay byte-identical. Phase gating is a cache artifact, not a design
feature: when writing a new driver or restarting cold, every hardening
belongs in the base prompt of every applicable phase. Fix prompt defects
EARLY — the further the resume front advances, the more a global prompt
change equals a cold restart.
The fixed per-agent overhead dominates cost — design around it.
~27K tokens of system prompt, instruction files, skills, and MCP schemas
per agent, paid on every 15-second probe. Merge fingerprint probes with
the adjacent exec where possible (one agent returns both structures);
use a lightweight agentType for mechanical executors. And probe every
external wrapper mechanism BEFORE launch — the one unprobed path
(a CLI run exceeding the Bash timeout) killed the run in phase 1.
Know your platform traps.
pgrep -x matches the kernel comm, truncated to 15 chars: a pattern
of 16+ chars can NEVER match. Truncate patterns to 15 or list real
comm values.
Schema-enforced agents die if they end their turn without output —
they can never "wait" by ending the turn. Long commands: detached
launch (setsid nohup, exit code to a known file) + repeated blocking
Bash waits under the 600 s tool cap. Give mechanical executors a
relief valve: a harness-backgrounded command is reported as a clean
failure (exitCode: -1), turning a run death into a recoverable pause.
resumeFromRunId IGNORES args: the file's top-of-script constants
are the ONLY resume channel.
Adversarially fact-check any finding about the driver itself with a
clean-context third party before recording it — and fact-check the
refuter's proposed fixes too. Real score on 3 findings: 2 corrected
(overstated impact, wrong threat model), 1 worse TOCTOU discovered, and
one refuter claim ("JS-only change, therefore cache-compatible") was
itself false.
Decide at design time which human gates are delegable to the
orchestrator, and write it down. An explicit delegation note turned
47 minutes of dead waiting into an automatic unblock.
Warn the operator: edit the target repo only between phases. The
driver cannot distinguish a legitimate user edit from an agent mutation
inside a fingerprint window — both pause the run. Before resuming after
any mutation-suspected pause, establish which one it was (diff against
backup, integrity checks), then acknowledge explicitly through the
resume channel so the driver re-baselines on purpose, not by accident.
Operating a paused run — checklist
Read the pause payload: reason, detail, retryStep, howToResume.
It must be self-sufficient; if it is not, that is a driver bug to fix.
Treat the cause (close browsers, restore state, decide arbitration…).
Edit the script's top constants — the only resume channel:
RETRY_TOKENS[retryStep] += 1 — ALWAYS, rule 5. No exceptions for
"the prompt change will break the cache anyway".
HUMAN_ARBITRATION[findingId] = {verdict, requiredOutcome?} for
escalated findings.
mutation-suspected pauses: record the verification you performed in
the acknowledgment constant (e.g. MUTATION_ACK) so the driver
re-baselines explicitly.
Any prompt fix riding along must be phase-gated (rule 6).
Workflow({scriptPath, resumeFromRunId}). args will be ignored.
Inter-phase pause with a messy cache? Prefer cold restart: new run,
committed-check skips finished phases (rule 1).
Build checklist
Spec read (looper .agents/loops/*.md or equivalent); every gate
mapped to a command, a fixed-path deliverable script, or a review
judgment — and the mapping decisions documented at the top of the
script (paid once at first read, available at every reopen).
CONFIG section isolates everything project/machine-specific; the body
references only CONFIG.
Resume constants (RETRY_TOKENS, HUMAN_ARBITRATION, acknowledgment
constants) empty/null at the top, above CONFIG.
Every pause has a retryStep pointing at the observation to replay,
and a hint saying exactly what to edit.
Fingerprint sandwich around every non-mechanical agent call.
Commits judged on observed state (head moved + worktree clean), never
on reported exit codes; committed-check at every phase start.
External CLI wrappers probed for: >600 s runs, effective model/effort
reporting, session resume semantics (per-flag inheritance!), unknown
session id behavior.
No conditional tool/skill branches in prompts (rule 2); rules stated
as operations (rule 3).
Human-gate delegation decided and written down (rule 10).
Script located outside the target repo; operator warned about
mid-phase edits (rule 11).
Common mistakes
Mistake
Consequence
Resuming without bumping retryStep
Cached failure replays; pause loops forever
Prompt fix without phase gating mid-run
Cache invalidated from that step; effectively a cold restart you didn't choose
"Read-only" instruction on a WAL SQLite path
Agent touches -shm by merely opening it; mutation pause with wrong attribution
pgrep -x pattern longer than 15 chars
Dead entry, never matches; blind spot in the gate
Trusting reported exit codes for commit decisions
Double-commit or missed commit on executor misreport
Letting a schema-enforced agent wait by ending its turn
Agent killed by StructuredOutput enforcement; whole run dies
Resume channel via args
Silently ignored on resume; run replays original args
Live guard at the top of the script
Invalidates the entire prefix cache; re-verify where it matters (start of destructive phases) instead
