Workflow

---
name: workflow
description: Build an LLM-era feature as a WORKFLOW, not an agentic loop — the composition skill that drives the whole toolset end-to-end. Design the stages along the data flow with the user (each failure either bends back to ONE named stage carrying its exact signal under a bounded budget, or escalates to a human), front-load the contract and the never-happens invariants, author the machine with polygen, declare effects (determinism at the edges, the model as one well-scoped handler), prove the anti-loop rules with check-effects, run it durably under polyrun, and later evolve it with polyvers. Use when the user wants to "avoid the loop", de-loop an agent design, build a pipeline/workflow with an LLM step, replace a cron-scan or plan-act-reflect architecture, or asks how to apply the workflows-not-loops method to a new project. Trigger phrases: "workflow not a loop", "build this as a workflow", "de-loop this agent", "no agentic loop", "event-driven pipeline", "apply the manual".
---

# workflow — build it as a workflow, not a loop

The composition skill: where `polygen` authors one machine, this skill builds
the whole feature the workflows-not-loops way, driving the other engines in
order. The method's premise (after Adron Hall's "Loop Engineering" critique):
an agentic loop exists to compensate for starved context, missing
decomposition, and clock-driven correction — remove each reason and the loop
collapses into a directed, checkable workflow. Each of those removals is an
ARTIFACT here, not advice.

The full worked recipe with rationale is
`${CLAUDE_PLUGIN_ROOT}/examples/workflows-not-loops/MANUAL.md`; the two
reference builds are `${CLAUDE_PLUGIN_ROOT}/examples/workflows-not-loops/`
(document pipeline, incl. the v1→v2 polyvers evolution) and
`${CLAUDE_PLUGIN_ROOT}/examples/todo-machine/` (an ordinary app: durable
per-item timers replacing the cron scan, plus an HTTP shell). Read the
MANUAL before Step 1; crib file shapes from the examples, not from memory.

> Same disclosure as every engine: the checks are exhaustive over the
> contract's DECLARED finite domains — a consistency check, not a proof. The
> contract and invariants are a reading of intent and need the user's review.

## Step 1 — Draw the pipeline as data flow (WITH the user, no tools)

One line per stage: what comes in, what goes out, what can go wrong. Then
force the two-answer rule — for EVERY failure the user must pick exactly one:

- **bend back** to ONE named stage, carrying the exact signal (violation,
  reason) verbatim, under a bounded budget (pick the number now); or
- **escalate** to a human, terminal, with the reason recorded.

"Retry the whole thing" / "re-plan" is not an option — that is the loop
sneaking back in. If the user cannot name the target stage and the signal,
the design is not done. Also decide the fuzzy middle now: which single
stage(s) does a model own? Everything else must be a deterministic function.

## Step 2 — Contract + invariants (front-loaded context)

Write `contract.json` before any code: observable state (the stage enum, the
correction counters, the recorded signal), one event per stage completion,
`dataDomain` with concrete values for every field (a field without a domain
is invisible to every checker downstream), terminal states including the
escalation terminal, special rules naming the anti-loop intent, and the
`noOpRule` (unexpected events are observable rejects — this is what makes
duplicates and stale deliveries safe).

Then the never-happens list in `invariants.mjs`. The four anti-loop rules
are standard — instantiate all four every time:

1. the pipeline is directed: only the named bend(s) may move backward;
2. correction counters move ONLY by exactly +1 under their signal
   (reflect-every-turn becomes unrepresentable);
3. the signal is recorded VERBATIM (post state carries data.violation);
4. budget exhaustion escalates — never another lap.

Plus the two hygiene rules: terminals frozen; stale/duplicate events are
byte-for-byte no-ops. If the user cannot articulate invariants, run the
`polynv` skill first — that is exactly what it elicits.

## Step 3 — Author and check the machine

Author with the `polygen` skill (supply the Step-2 contract via
`--contract` — do not let it redraft what the user already reviewed). No API
key is required: per that skill's Step 0 the user chooses the scripted keyed
path (CI-grade, pinned model) or the keyless in-session path — you author
`next.cjs` in the strict-profile artifact style (copy the shape from the
examples) and gate it yourself:

```
node ${CLAUDE_PLUGIN_ROOT}/scripts/check.mjs --spec next.cjs \
  --contract contract.json --invariants invariants.mjs
```

Do not proceed past a reachable violation: fix the CODE at the
counterexample (or fix a wrong contract and re-run) — never weaken an
invariant to make it pass.

## Step 4 — Effects: determinism to the edges

Three artifacts (shapes in the examples): `effects.cjs` — a pure,
edge-triggered mapper (entering a stage emits its intent; the bend-back
payload carries the violation verbatim — that is the "fix this, not a
re-plan" routing); `effects.manifest.json` — completion wiring as data
(onSuccess/onFailure/onExhausted, retry policy; a DOMAIN failure is a
permanent named error that becomes the signal, an INFRASTRUCTURE failure
retries then escalates); and `effect-invariants.mjs` — the emission rules:
no correction without a signal (stage runs ≤ 1 + failure-signal count),
blast-radius containment (a bend never re-emits upstream stages), ordering
(no render before its gate), bounded totals. Timers (due dates, timeouts)
are effect intents carrying enough data for the machine to reject stale
firings — never app-side cancellation logic. Check the composition:

```
node ${CLAUDE_PLUGIN_ROOT}/polyrun/bin/polyrun.mjs check-effects --config polyrun.config.mjs
```

If exploration reports BOUNDED, raise `--depth` until it says exhaustive —
a bounded pass is not a pass.

## Step 5 — Run it under polyrun

Write `polyrun.config.mjs` (machine, contract, effects, invariants paths +
handlers) and a demo script — crib both from the examples. Handlers are
plain async functions; the model step is just one more handler under an
idempotency key. The integrator writes ZERO orchestration code. Gate with
`polyrun.mjs deploy --config …`, then run the demo and read the journal
aloud with the user: count the laps. The journal should show a directed
pass, bends only where signals demanded them, and stale/duplicate events as
observable rejects. The journal is also a Polygraph trace corpus — name
that: `/polygraph:verify` over real captured traces is the drift check after
integration.

## Step 6 — Evolution (later, but say it now)

When the workflow changes shape, that is the `polyvers` skill: classify →
migrate scaffold → check over fleet snapshots → `polyrun.mjs migrate
--apply` → deploy gate. Tell the user this exists at handoff so the first
schema change doesn't get hand-rolled.

## The two loops that legitimately survive

Name these in the handoff, so "no loops" is never overclaimed: the runtime
correction bend (bounded, signal-driven, then a human) and polygen's
self-repair at authoring time (iterates only on a concrete model-checker
counterexample, budgeted). Any third loop in the design must answer "what
signal triggers it and what bounds it" — no answer means it is ceremony, and
the Step-2 invariants should be making it unrepresentable.