Skip to content

Orchestration (bullets) ​

the pitch

  • nine orchestration workflows that decide how to run at runtime, not one fixed pipeline
  • each picks its strategy, its effort, or its work breakdown from the task in front of it
    • a one line lookup doesnt pay for a research fan out
    • a hard task isnt capped at a single pass

how they behave

  • they run in session through Claude Codes Workflow tool
  • each is standalone, pick one, ignore the rest
  • every one is budget aware
    • fan out scales to whats left
    • heavy stages get skipped when it runs low

In Practice ​

  • every workflow runs the same way, in session through the Workflow tool, task passed as args:
Workflow({ scriptPath: "harness/orchestration/smart.workflow.js", args: "your task here" })
  • they fan out agents, so they need the ultracode opt in
  • what differs is how each one spends that fan out

Reach for smart when you do not know how hard the task is

  • one cheap triage agent sizes the job in a single pass
    • routes are trivial, effort, decompose, contested
  • takes the lightest route that clears a strict gate
  • never over spends on something small

what comes back

  • returns { path, result }
  • path names the route it actually took
    • direct, attempt, deepen:orchestrate, deepen:debate, deepen:panel
    • attempt-capped when the budget runs thin

Spend cheap first with escalate

  • a low effort pass answers directly
  • a strict gate judges it
  • the thorough panel only runs when the cheap answer falls short
    • three angles, completeness, correctness, the edge cases the cheap pass missed
Workflow({ scriptPath: "harness/orchestration/escalate.workflow.js", args: "your task here" })
  • most tasks clear cheap, back as { tier: 'cheap' }
  • only the ones that fail the gate pay for { tier: 'thorough' }

Buy top model quality at crew prices with foreman

the loop

  • fable plans the task into subtasks, each with its own done criteria
  • the cheaper crew does the work, sonnet on easy subtasks, opus on hard ones
  • fable checks every output against its criteria
  • a stray gets one correction round before fable merges
Workflow({ scriptPath: "harness/orchestration/foreman.workflow.js", args: { task: "your task here", worker: "opus" } })

quirks

  • pass args.worker to force one crew model for everything
  • the only workflow here that pins models instead of inheriting the session model
  • reads its tier map from routing.nuon at stage 0

Break a wall with unstick

the attempt

  • the worker runs under a no bluffing rule
  • it reports the exact blocker rather than guessing past it

the rescue

  • the lesson store is checked first
  • then three web search angles fan out on the blocker, verbatim error, official docs, known issues
  • a ranker turns the findings into fixes, the retry gets them as notes
  • the same wall twice ends the loop, more searching will not save it

An example outcome

  • a one line lookup handed to smart comes back { path: 'direct', result } after two agent calls
  • a big splittable task returns { path: 'deepen:orchestrate', result }, workers scaled to the budget
  • an unstick web rescue banks the blocker, cause, and fix to the lesson store, so the next session skips the search

One caveat on nesting

  • smart calls orchestrate and debate, and router calls debate
  • workflows nest only one level deep
  • so run smart and router at the top level, never from inside another workflow

Capstones ​

smart.workflow.js ​

  • the composed one, distils route, escalate, and orchestrate into one frugal flow
  • four phases, Triage, Attempt, Gate, Deepen

how it stays frugal

  • cheap triage picks the path
  • early exits stop it spending when a lighter stage is good enough
  • budget gates keep it from going heavy on a tight budget

extras

  • calls orchestrate and debate as optional sub workflows, falls back to its own panel when either is missing
  • a failed gate also banks the shortfall to the lesson store

router.workflow.js ​

  • the dispatcher, classifies the task into one of five routes
  • then runs only the strategy shaped for that kind of work

the routes

  • research, fans searchers out across angles, then synthesizes
  • review, judges across dimensions, then merges
  • bug-hunt, finds candidate bugs, adversarially verifies each, keeps only the confirmed
  • contested, runs a debate
  • explain, one careful deep pass, also the default for an unrecognised route

Strategies ​

escalate.workflow.js ​

  • cheap first, a low effort pass then a strict gate
  • the thorough panel only runs when the cheap answer does not clear the bar
  • effort in proportion to difficulty
  • a thin budget keeps the cheap answer rather than escalating

speculate.workflow.js ​

  • latency hiding, runs the cheap and thorough passes at the same time
  • a judge ships the cheap answer when the two agree, takes the thorough one when they disagree
  • spends tokens to save wall time, the heavy pass hides behind the cheap one
  • below the floor it runs the cheap pass alone

orchestrate.workflow.js ​

  • runtime decomposition, a planner breaks the task into independent subtasks
  • one worker runs each in parallel, a synthesizer merges
  • the breakdown is decided by the model, not hardcoded
  • every worker brief carries the discipline block
    • hold to the subtask
    • pull lessons first
    • end with a four part report

foreman.workflow.js ​

  • model tiered, fable plans with done criteria and merges
  • the cheaper crew does the bulk work
  • fable polices every output against the criteria it wrote, a stray gets one correction round
  • args.worker forces one crew model for all subtasks
  • tier map comes from routing.nuon, builtin fallback is { easy: 'sonnet', hard: 'opus' }

debate.workflow.js ​

  • consensus through disagreement, several agents answer independently from distinct stances, so no one anchors
  • each revises after reading the others
  • a judge keeps what survived
  • three debaters is the useful minimum, scaled up on a fat budget

reflexion.workflow.js ​

  • self assessing loop, draft, critique, refine, repeat
  • a strict critic scores the draft 1 to 10 and lists concrete fixes, the refine works off those
  • loops only while the score keeps climbing
  • stops at the bar (8 by default), when a round stops improving, or at the round cap
  • always ships the best draft it saw
  • the generic version of skill-smiths loop

unstick.workflow.js ​

  • self rescuing loop, the worker surfaces the exact blocker instead of grinding
  • the lesson store is checked before the web
  • searchers fan out on the blocker, a ranker turns findings into fixes for the retry
  • a win from the store bumps that lessons hit count, a win from the web is banked as a new gotcha
  • the same wall twice ends the loop

References ​

patterns.md ​

  • the catalogue, the full set of orchestration patterns
    • the ones with a script and the ones worth reaching for without one
  • plus a picking guide
    • unknown task type goes to route
    • latency over cost goes to speculate
    • top model quality on a small budget goes to foreman
    • and so on

routing.nuon ​

  • the tier map, a NUON record mapping easy and hard to model names
  • read by foreman at stage 0, installed as .claude/workflows/routing.nuon
  • retune the difficulty to model tiering here without touching the workflow
  • a missing or unparseable file degrades to the builtin fallback

Budget Convention ​

  • every workflow here is budget aware, a hard convention in this kit
  • each reads the token budget and does two things with it
    • gates its heaviest stage behind a floor, so no expensive fan out on the dregs of a budget
    • scales its worker, debater, or verify count to what is left
  • the shared move is one line:
js
const fleet = budget.total ? Math.floor(budget.total / 100000) : 4

the floors, and the stage each one guards

WorkflowFloorGuards
smart40kstarting the Deepen stage
escalate40kthe thorough panel
speculate40kracing the thorough pass at all
debate40kthe revise round
reflexion30kanother refine round
foreman30ka correction round on a stray
unstick30kanother search and retry round

the unfloored two

  • orchestrate and router carry no named floor
    • still scale their fan out to budget.remaining()
    • the worker count for orchestrate, how many bug claims to verify for router
  • with no budget directive set, budget.total is unset and every workflow runs its full path
  • the gates only bite once a budget is in play

Connects to ​

  • threads through memory
    • smarts gate and foremans check bank shortfalls to .claude/memory/lessons.nu as process lessons
    • orchestrate and foreman workers pull lessons before starting
    • unstick checks the store before searching, then banks a web found fix as a gotcha
  • reflexion is the generic form of the self critique loop skill-smith runs to refine a skill against its rubric
  • installed by the installer into .claude/workflows/
    • where smarts and routers sub workflow names (orchestrate, debate) resolve
    • and where foreman finds routing.nuon