zcodium-project/zcodium/dynamic-workflows

Writing dynamic workflows

This skill is the whole authoring contract for CreateWorkflow. The tool descriptions are short on purpose; the facade the compiler checks against, the rules a script must satisfy and the fields each tool takes are in §16, and CreateWorkflow, AmendWorkflow, FillWorkflowHole, SaveWorkflow and EvalWorkflowSnippet refuse to run until this skill has been loaded. The rest is the judgment layer: how many subagents a request deserves, which of them should share a context, what each one should hand back, and how to keep the run's work from dying with the run.

Two names collide in this codebase. CreateWorkflow is the dynamic-workflow tool and the only one this skill is about. The legacy Workflow tool and /expert are a different, older feature that happens to share the word.

The bar: first-class, expert-level work

A workflow exists to produce first-class, expert-level work — the deliverable a senior practitioner would hand over after doing the job properly, not a faster draft of what one reply could have said. A user who asks for a workflow is paying for that depth, and every choice in this skill serves it: enough subagents to actually cover the ground, fresh eyes on every plan and every draft (§3), an independent confirmation of every finding, deterministic checks wherever a command can decide, and a report that says what was verified, what was not, and what it all means. Depth is measured by what is at stake, not by how many subagents re-read the same work: verification goes where a wrong claim would cost the user something, and each piece of work gets the one check that decides it. When a shortcut and the expert's way disagree, take the expert's way; trim the work only when the task is small, and trim the checking when a wrong claim costs little or a command has already decided it.

1. Is this the right tool, and how big should it be?

Only an explicit request starts a workflow. A workflow begins with /workflow or with the user naming workflow/工作流 as the means, never with your own judgement that a task looks orchestration-shaped. Results feeding later steps, a bounded loop, a branch on a typed result — those are shapes the script is good at once one has been requested, not reasons there should be one. Delegate with Agent or do the work yourself.

An explicit request is binding. Once the user names workflow/工作流 as the means, the routing question is closed — not Agent, not inline, not "too small for a workflow"; what remains is only how big the script should be, and the smallest task gets a small workflow.

An explicit workflow request is a request for depth, and the bar above is the measure. Default to the thorough shape — a fresh subagent per unit of work, a deterministic gate wherever a command can decide, an independent confirmation of every finding the user will act on as fact (§10) — sized to the stakes: a bug the user will fix on your word gets a confirmer; a poem or a survey gets a reader at most. Every task is a full model session, so put sessions where they raise confidence, not where they repeat each other: "review the changed files" wants a reviewer per file plus a confirmer per finding; "write me twenty poems" wants twenty poets and no confirmers.

Write only as much of that shape as you know for sure. Where a later stage depends on what an earlier one finds, write up to that point, end in a hole (§15), and let the findings write the rest. Guessing a topology is not depth.

2. Subagent topology

This is the decision that separates a good script from a bad one. It is made twice: now, for what the request already tells you, and at a hole (§15), for what only the run can tell you. This section is about the first, in four parts.

Fresh subagent per item, or one shared subagent? Every agent() call creates a new context. Sharing a context means sharing the variable:

// Independent: each judge sees only its own item. Runs concurrently.
items.map((i) => agent(`judge-${i.id}`).ask<Verdict>(`Judge ${i.id}`));
// Calibrated: one context sees every item in sequence, so its later verdicts are
// consistent with its earlier ones. Asks on one subagent queue FIFO — this serializes.
const judge = agent("judge", "You rank consistently across a whole batch.");
items.map((i) => judge.ask<Verdict>(`Judge ${i.id}`));

Independent is right for unrelated items; shared is right when the answers must be consistent with each other, at the price of serialization. Hoisting the agent() call out of a loop for tidiness turns a fan-out into a queue, and nothing rejects that script.

A name is an identity, and it has to be unique. No two subagents in one run may share a non-empty name — a duplicate fails the run. One fixed name inside a fan-out is a duplicate per item, so write ` agent(judge-${i.id}) `; the compiler catches the literal form, a name built at run time costs you the run. Anonymous is always safe.

Names are worth giving anyway: a revised re-run finds its cache by them (§13), importing every ask whose instructions did not change at zero tokens. Anonymous subagents start empty.

Persona, frozen at creation. A persona stacks on the harness's own subagent contract — citing path:line, never reporting a check it did not run, saying what it could not do, escalating instead of faking — so write the role and the standard of judgement and leave those rules out. Every subagent has the same tools; what it may do with them is said in the ask: a reviewer that must not touch the code is told "do not edit any file".

Per-subagent model, only when the user asked for one, with the name they used: agent("judge", { model: "GLM-5.3-Flash" }), ids from ListModels. A literal or a model() ModelRef; to route, map the router's typed key to a model() table (patterns.md #13). NEVER move a subagent to a model under another provider on your own — not for a judge, not because it looks cheaper; another provider is another bill. When a lighter model would clearly fit (one-turn judges, routers) and the user has not said, ask them first, before the call: name the model and the provider, say what it would save, and go with their answer. Their yes is the request; write it as the full providerId/modelId (a bare name never crosses providers).

Where each item goes next. A run with more than one stage is a pipeline: an item leaves its stage as soon as it is done, and the next stage takes it while the rest are still being worked on. Decide this at every hand-off when you lay out the topology, and let a stage wait for all of its items only where the next step needs every one. §7 says how to write each case.

Loops. Bound every loop with a round cap, and carry the feedback forward:

let feedback = "none";
for (let round = 0; round < 5; round++) {
  const plan = await planner.ask<Plan>(`Plan the fix. Previous critique: ${feedback}`);
  const review = await reviewer.ask<Review>(`Critique this plan: ${JSON.stringify(plan)}`);
  if (review.approved) return plan;
  feedback = review.feedback;
}

Reuse the same two subagents across rounds: a subagent asked again keeps its context, so round five is cheap. Reuse costs freshness — by round three the reviewer is anchored on its own critique — so add an independent one at the end (§3).

No nesting. Subagents cannot call CreateWorkflow; model a big sub-task as more subagents here.

3. Fresh eyes

The author of a plan or a draft cannot see its gaps, because they filled them while writing. A reader with a separate context has no such fill, so the gaps show. That is the whole method, and it applies at every stage inside the workflow where something is drafted — a plan, a fix, a finding, the final report. It pays most on plans, which are cheap to critique and expensive to execute wrongly.

Four rules make the eyes actually fresh:

• Separate context, not a second opinion from the same head. An independent reader is a new

agent() that has seen nothing but the draft. Every planner–reviewer loop keeps a persistent reviewer for continuity (§2), and then puts the final draft in front of a reviewer that has never seen an earlier round.

• Ask for failures, not approval. "Is this good?" gets a yes. "What would break this?

What is missing? Restate the plan in your own words" gets findings. Write the ask so that approving takes evidence and objecting is the easy move.

• Give the eyes the same evidence. A reviewer judging a plan about code from its text

alone can only judge coherence: tell plan reviewers to read the files the plan touches, and not to edit them.

• Give a prose deliverable an independent read. When the deliverable is text nothing else

checked — a guide, an analysis — hand it, before the script returns, to a reader-proxy subagent asked what is unclear, what the text fails to support, and what the user will ask next; then fix those. Say it judges from the text alone — checking claims is a confirmer's job. A report whose findings were each confirmed (§10) has had its eyes; add no reader on top.

Three cautions. Correlated reviewers add little — same model, same prompt, same blind spots — so give each a distinct lens. Bound it: one deliverable gets one mechanism — a plan a reviewer who reads the code, findings a confirmer, prose a reader; two is the ceiling, with a reason you can say. And these rules are about the subagents inside the script, not a gate on submitting it: read your own script once against the request, and at every Promise.all ask whether the next step needs every item; where it does not, pipeline it (§7). The confirmation window then puts the plan in front of the user.

4. Typed results

Pass a type argument to ask whenever your control flow will branch on the answer; leave it off when you just want prose back. The type must be an interface or type alias you write in the script.

JSDoc on a property becomes the field description the subagent actually reads. This is the cheapest quality lever in the whole surface and the easiest to skip:

interface Finding {
  /** Workspace-relative path the problem is in. */
  path: string;
  /** One sentence: what is wrong, not how to fix it. */
  problem: string;
  /** How much it matters. Reserve "high" for data loss or a crash. */
  severity: "low" | "medium" | "high";
}

Without the comments you get whatever the subagent guessed severity meant.

Keep results narrow: a result crosses a schema boundary and gets interpolated into the next prompt, so a wide one costs tokens twice. Pass paths, not file contents — a subagent has its own file tools; a stringified 4000-line file spends tokens on what it could have read.

5. Getting the world in

files.glob and git.changedFiles are how a script learns what to fan out over; both are executed by the harness, recorded, and replayed on resume.

Caps reject rather than truncate (§16.2), so narrow the pattern instead of fanning out over a silently partial view. Reads are catchable, so a coarser fallback is a catch — which git needs, since every git call rejects outside a repository:

let paths: string[];
try {
  paths = await git.changedFiles("origin/main");
} catch {
  paths = await files.glob("src/**/*.ts");
}

Reach for files.read or files.grep only when the script itself must shard or branch on content; reading files is subagent work.