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, SaveWorkflow and EvalWorkflowSnippet refuse to run until this skill has been loaded in the session. 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 is spent where a wrong claim would cost the user something, and each piece of work gets the one check that decides it, not every check this skill knows. When a shortcut and the expert's way disagree, take the expert's way. Trim the work only when the task is genuinely small, never because thoroughness is inconvenient; 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. The request is the whole routing rule: 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 loop with a stopping condition, control flow branching on a typed result — none of these are a reason to start one. Delegate with Agent or do the work yourself.

An explicit request is binding. When the user names workflow/工作流 as the way to do the task, the routing question is closed: not Agent, not doing it inline, not "this is too small for a workflow". The user picked the tool; what remains for you is only how big the script should be, and the smallest task still gets a small workflow rather than something else.

Once a workflow has been requested, these are the shapes it is good at, and what the script should reach for: results feeding later steps (pipelines, fan-out then fan-in), a loop with a stopping condition, and control flow branching on a typed result. They describe how to build the workflow the user asked for — they never decide that there should be one.

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) — and size the checking to the stakes: a bug the user will fix on your word gets a confirmer; a poem, a brainstorm or a survey gets a reader at most. Cost still counts: every task is a full model session with its own context, so put the sessions where they raise confidence, not where they repeat each other. "Review the changed files" wants one reviewer per changed file plus one confirmer per finding; a three-line question wants neither; "write me twenty poems" wants twenty poets and no confirmers.

2. Subagent topology

This is the decision that separates a good script from a bad one, and there are four parts to it.

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}`));

Both are correct for different jobs. Independent is right when the items are unrelated and you want parallelism; shared is right when the answers must be consistent with each other, and you are paying serialization for that consistency. Choosing shared by accident — by hoisting the agent() call out of a loop for tidiness — turns a parallel fan-out into a queue. Nothing rejects that script; the run simply takes as long as every item in a row.

A name is an identity, and it has to be unique. Naming is optional, but no two subagents in one run may share a non-empty name — a duplicate fails the whole run. Note what that means for the first snippet above: one fixed name inside a fan-out is a duplicate once per item, so it is written agent(`judge-${i.id}`), per item. The compiler catches the literal form (agent("judge") inside a .map/for...of) before you submit; a name built at run time it cannot see, so that one costs you the run. Anonymous is always safe: drop the name when you have nothing per-item to build one from.

Names are worth giving anyway, because they are how a revised re-run finds its cache (§13): resubmitting a fixed script with AmendWorkflow imports, per named subagent, every ask whose instructions did not change — at zero tokens, up to the first ask that has to run live. Stable, meaningful names are what makes that hit. Anonymous subagents are legal and simply always start with an empty context.

Persona, frozen at creation. A persona stacks on top of the harness's own workflow subagent contract — citing path:line, never reporting a check it did not run, saying plainly what it could not do, escalating instead of faking — so write the role and the standard of judgement, and leave those rules out; they are already there. Every subagent has the same tools — reading, searching, editing, running commands — and runs on the session's model; there is no per-subagent tool profile or model choice. What a subagent may do with its tools is said in the ask: a reviewer that must not touch the code is told "do not edit any file", a judge of a string is handed the string and told to judge it as given. A subagent asked to run a check runs it; one told not to edit does not. None of this can change after agent() — there is no per-task override.

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 — that is the point. A subagent asked more than once keeps its accumulated context and gets long-lived caching, so round five is cheap. Creating a fresh planner each round throws away everything it learned in round four. The one thing reuse costs you is freshness: by round three the reviewer is anchored on its own earlier critique. Keep the persistent reviewer for continuity and add an independent one at the end (§3).

No nesting. Subagents cannot call CreateWorkflow. If a task is big enough to want its own workflow, model it 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 told to judge a plan about code from the plan's text alone can only judge coherence. To judge correctness it must read the code: 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, a write-up — hand it, before the script returns, to a reader-proxy subagent asked what is unclear, what the text itself fails to support, and what the user will ask next — then fix those, not the prose. Say in the ask that it judges the report as a reader would, from the text alone, so it does not wander off to verify it against the repository. If you want claims checked, that is a confirmer that reads the code, not an independent read. A report whose findings were each confirmed (§10) has already had its eyes; do not add a reader on top of the confirmers.

Three cautions. Correlated reviewers add little — same model, same prompt, same blind spots — so give each a distinct lens or a different task. Bound it: one deliverable gets one mechanism — a plan gets a reviewer who reads the code, findings get a confirmer, prose gets a reader. A draft that came out of a planner–reviewer loop and then passed a fresh final reviewer has had its fresh eyes; a reader-proxy pass over the same text is a third session re-reading work two have already read. Two mechanisms on one deliverable is the ceiling, and it needs a reason you can say. And the rules above are about the subagents inside the script, not a gate on submitting it: reading your own script once against the request is normally enough, and the run confirmation already puts the plan in front of the user. An independent read of the script by a fresh Agent is an option for a genuinely hard one — many phases, subtle gates — not a routine step.

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. With them you get a calibrated field, for the price of three lines.

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 and can read what it needs; handing it a stringified 4000-line file spends tokens to tell it something it could have fetched itself.

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 from the record on resume.

Caps reject rather than truncate: an over-wide files.grep fails that call instead of handing you a silently partial view of the workspace to fan out over. Narrow the pattern or add a glob filter. Reads are catchable, so a script that wants a coarser fallback writes one — which is exactly what you need for git, 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. Deciding which files to hand out is script work; reading them is subagent work.

world.run is the deterministic gate. When a check is fixed and machine-checkable — the build passes, the proof checks, the tests are green — run it as code and branch on the exit code, instead of asking a subagent to run it and trusting the claim:

const check = await world.run("lake", ["build"], { timeoutMs: 1_800_000 });
if (check.exitCode !== 0) feedback = check.stderr;

A nonzero exit code is a value, not an exception: the gating loop's normal case reads exitCode and carries stderr forward as the next round's feedback, with no catch in sight. Rejections are reserved for the world failing to answer — spawn failure, timeout (default 300s, override per call, no cap), or output over the per-stream cap. The command name must be a compile-time string literal, because the user approves the script's command set at confirmation: interpolate paths, flags and round numbers into the args array, never into the command. And keep the division of labor: open-ended editing belongs to a subagent with tools; world.run is for checks whose outcome your control flow branches on.

Choose the gate before you write it. A gate decides exactly as much as the check it runs, and the check the task needs is rarely the first one you would type from habit. Before the first world.run, find out what checks the repository actually has — the scripts in package.json, the targets in a Makefile, the CI config, the README's "run this to verify" line — and rank them by how much they decide: a unit suite over fixtures decides less than an integration or end-to-end suite, which decides less than the acceptance command the README names, and none of them decides a performance request the way the bench does. Then build the gate in two tiers. The fast tier may drive the rounds of a loop. The strongest tier the request implies decides the exit, and it runs for real at least once before the final return — even when the fast tier already said yes, because the fast tier cannot see what it does not test. When the strong tier is slow, give it the timeoutMs it needs; a faster substitute is a different check, not a cheaper version of the same one.

phase("Fix until the unit tests pass");
for (let round = 1; round <= 5; round++) {
  const unit = await world.run("npm", ["test"]);
  if (unit.exitCode === 0) break;
  await fixer.ask(`The unit tests failed:\n${unit.stderr}\nFix them.`);
}

phase("Run the end-to-end suite once before handing over");
const e2e = await world.run("npm", ["run", "e2e"], { timeoutMs: 1_800_000 });
const verified = e2e.exitCode === 0;

A check that exists in the repository and did not run is not "not covered"; it is unverified work (§10).

6. Test the pieces before you commit

A workflow script is final at submit. The fixed logic inside it does not have to be: run it through the EvalWorkflowSnippet tool first, which compiles and executes a snippet against the same compiler, sandbox and world-read path a real run uses, synchronously and without persisting anything. What passed there pastes into the workflow verbatim. Send the snippet as code, or as path to a file holding it when you have already written it out — the second try then costs an Edit rather than the whole snippet again.

Snippet work is exactly the non-subagent part: what a glob really returns (workspace-relative, sorted), whether a grep pattern overruns its cap, how world.run("lean", ...)'s stderr parses, whether a gate predicate does what you meant. A snippet has files.*, git.*, world.run and log, but no agent() — orchestration cannot be rehearsed, only the pieces can. Testing a parse function by burning a full run is the expensive way to find a typo. Once you know which check decides the result (§5), run it once here as well: that tells you what its output looks like, whether it exits nonzero the way you assumed, and how long it takes — which is the timeoutMs you write, not a guess.

7. Keep the script analyzable, and join only where the data needs everyone

The harness recovers the dependency graph by reading your code before it runs, so write code whose data flow is visible. Node results flowing through plain variables, template interpolation, destructuring and small local helpers are all traced exactly. Stashing a result into a container and fishing it out later, or routing it through a clever indirection, earns an analyzability diagnostic instead.

Promise.all is a join, and a join is a barrier: nothing after it starts until the slowest item before it has landed. Parallelism comes from not awaiting yet:

// Concurrent: nothing is awaited until the join.
const all = await Promise.all(
  paths.map((p) => agent(`reviewer-${p}`).ask<Review>(`Review ${p}`)),
);

// Serial: each await blocks the next call. Only write this when you mean it.
for (const p of paths) results.push(await agent(`reviewer-${p}`).ask<Review>(`Review ${p}`));

Join where the next step needs every item, and nowhere else. When two stages map one to one — a reviewer per file and a confirmer per finding, a migrator per file and a checker per file — a barrier between them makes every confirmer wait for the slowest reviewer while the concurrency slots sit idle. Chain the stages per item inside the fan-out instead, and join once at the end:

// ✗ Two barriers: no finding is confirmed until every file has been reviewed.
const reviews = await Promise.all(paths.map((p) => agent(`reviewer-${p}`).ask<Review>(`Review ${p}`)));
const confirmed = await Promise.all(
  reviews.flatMap((r) => r.findings).map((f, i) => agent(`confirmer-${i}`).ask<Confirmation>(`Reproduce: ${JSON.stringify(f)}`)),
);

// ✓ One join: each file's findings go to their confirmers the moment its review lands.
const confirmed = (
  await Promise.all(
    paths.map(async (p) => {
      const review = await agent(`reviewer-${p}`).ask<Review>(`Review ${p}`);
      return Promise.all(
        review.findings.map((f, i) => agent(`confirmer-${p}-${i}`).ask<Confirmation>(`Reproduce: ${JSON.stringify(f)}`)),
      );
    }),
  )
).flat();

The stages that genuinely need everyone — a triage that ranks on one scale, a synthesis that deduplicates across findings — are the legitimate barriers, and they are few. A shared, calibrated subagent is not one of them: asks on it queue FIFO, so feeding it per item as results land keeps it consistent and keeps the pipeline moving (§11).

One rejection inside Promise.all rejects the whole join and the sibling results with it. When one bad item should cost one item, catch inside the callback (examples #3) or use Promise.allSettled and read each outcome.

8. Group the run into named phases

Phases are required, not a nice-to-have. The user experiences a workflow through its phase graph: the confirmation dialog they approve is drawn one node per phase, and a dialog with thirty step cards in it is a dialog nobody reads. Cover the whole script — every stage gets a phase("...") marker at its head, and the arrows between the phases are inferred from the same analysis:

<!-- compile -->

interface Attempt {
  /** One sentence: the optimization this round is trying. */
  approach: string;
}

/** Total nanoseconds the bench reports, or Infinity when it printed none. */
function benchNanos(output: string): number {
  const match = /time:\s*([\d.]+) ns/.exec(output);
  return match?.[1] === undefined ? Number.POSITIVE_INFINITY : Number(match[1]);
}

phase("Measure today's baseline");
const baseline = await world.run("cargo", ["bench"], { timeoutMs: 1_800_000 });
const target = benchNanos(baseline.stdout);
const optimizer = agent("optimizer");

let winner = "none";
for (let round = 1; round <= 3; round++) {
  phase("Make one improvement");
  const plan = await optimizer.ask<Attempt>(
    `Round ${round}. Baseline timings:\n${baseline.stdout}\nMake one improvement.`,
  );

  phase("Check that the tests still pass");
  const check = await world.run("cargo", ["test"]);
  if (check.exitCode !== 0) continue;

  phase("Measure whether it is actually faster");
  const bench = await world.run("cargo", ["bench"], { timeoutMs: 1_800_000 });
  if (bench.exitCode === 0 && benchNanos(bench.stdout) < target) {
    winner = plan.approach;
    break;
  }
}

phase("Collect the final numbers");
const head = await world.run("git", ["rev-parse", "HEAD"]);
return { approach: winner, commit: head.stdout.trim() };

Five nodes — "Measure today's baseline" → "Make one improvement" → "Check that the tests still pass" → "Measure whether it is actually faster" (and back to "Make one improvement") → "Collect the final numbers" — and they stay five when the real version of this script grows to thirty steps. That is the entire payoff: the user sees the story you had in your head instead of a wall of cards.

Notice the two checks. The unit tests are the fast tier: they decide whether a round is worth measuring. The bench is the check the request was about, and it runs every time a round survives the tests — not once at the start to print a baseline and never again. A loop that gates on cargo test alone would crown the first round that compiles (§5).

Write the names for the user, not for the graph. A phase name is a short natural phrase saying what this stage accomplishes for the user, written in the language the user is speaking in this session — "Research each changed file in parallel", "汇总并产出最终报告". Orchestration vocabulary the user never chose ("fan-out", "gate", "aggregate") names the machinery, not the work. Names must be compile-time string literals, so you cannot number rounds by interpolation — and you should not want to: two markers with the same name are one node, which is how a loop body stays one box across all its rounds.

Put the marker where the steps are. A marker claims the rest of the block it sits in, nested blocks and inlined helper calls included, so a marker inside an if covers that branch and stops at its closing brace. Mark the block where the ask and world.run calls actually live.

Not inside a concurrent fan-out callback. The run has one current phase, and every step is stamped with it at birth. Twenty map(async …) callbacks each re-entering phase("Review") and phase("Confirm") out of order would stamp each other's steps and count every re-entry as a round. A per-item pipeline (§7) is one phase, named for what it does to each item — "Review each changed file and confirm its findings as they land" — and the markers stay at the top level around it.

Every phase must contain at least one ask or one world.run. A phase is a stage the user watches progress through. Plain script logic — reading args, shaping a prompt, sorting results, building the final return — runs in a flash and shows no progress, so it is not a stage; a phase made only of it sits on the timeline as a step that never does anything. Fold that logic into the phase before or after it. In particular, do not open a phase for the setup at the top of the script or for the return at the bottom; the first phase starts at the first ask, and the last phase is the last stage that asks or runs something. The same goes for a branch that only narrates: an if whose body is nothing but report(...) and log(...) does not get its own marker.

9. Write for the user

Six things you write are read by the user, not by the script: phase names, subagent names, log lines, artifact titles and the markdown you publish, the four report fields, and any question a subagent escalates. Write each one the way you would tell a colleague across the desk what is happening: say what the work is, in the words the user would use, in the language the user is speaking in this session. The machinery — fan-out, gate, node, stage, pipeline — is yours, not theirs, and so is the numbering.

The method names in this skill — fresh eyes, independent read — are English idioms for you, not words for the user. Carry the idea across, not the words: in Chinese that is 独立复核 or 换人复审, never a word-for-word rendering such as 冷读 or 冷眼, which are not Chinese.

The language travels through your asks. Findings, summaries and anything else the user will read are written by subagents answering the ask you wrote, so write those asks in the user's language, or say in the ask which language to answer in. Otherwise a Chinese report arrives wrapping English findings.

10. Verify, report, deliver

log(...) is narration for the human watching the run. Use it at the points where a reader would otherwise wonder whether anything is happening — after a fan-out is sized, at the top of each loop round.

Verify before you report, in proportion to what a wrong claim costs. Verification exists to buy down the cost of the user acting on something false, so it goes where that cost is real: a bug they will fix, a security claim, a number they will quote, a fact a decision rests on. Each finding of that kind is confirmed independently before it reaches the user: a second subagent that reproduces the finding from its evidence alone — reading the code, running a check when one decides it, never editing — or a world.run command when one can decide. The reviewer that found the problem does not get to confirm it; self-confirmation is not confirmation. A finding that fails confirmation is kept and labelled unconfirmed, never silently dropped — a real issue the confirmer could not reproduce is still worth a human's eyes, and the label is what lets the user tell "seen" from "suspected".

Three things that look like verification and are waste. A confirmer on a finding a world.run already decided: the exit code is the confirmation, so record the command in verified and move on. A confirmer on work nobody will act on as fact — poems, brainstormed options, a first-draft survey — which gets at most one independent read (§3). And a suite run three times because the hunter ran it, the confirmer ran it and then the script gated on it: a check the script runs as a gate is run once, by the script, and the asks say so ("the script runs the full suite after you; do not run it yourself") so the subagents spend their turns on what only they can do.

Gate at the task's scale. verified names the commands that actually decided the result, and the reader will hold them against what they asked for. A unit suite in verified and the end-to-end suite in notCovered is not a verified deliverable; it is an unverified one with a disclosure attached. notCovered is for what could not be checked — no test exists for it, the environment lacks the tool, the check needs something only the user has — never for a check that exists in the repository and was skipped because it is slow or because the fast tier already passed. If the strongest check the request implies exists and did not run, the run is not done: run it, or say in conclusion that the work is unverified and why (§5).

Salvage by report. report(...) is different from log and more important: reported items are delivered with the completion notification even when the run fails. A forty-task run that dies on task twelve still did eleven tasks' worth of work, and report is the only thing that gets that work out. So report each finding at the moment it lands — after its confirmation, with its status — rather than accumulating an array and returning it at the end: the array is what you lose. Items are recorded, so a resumed run never shows the same one twice.

Give open-ended work an explicit round cap in the script rather than an unbounded loop: the harness enforces no node limit, so a loop that never goes dry only ends when the user cancels.

Deliver a report. The script's final return is the handoff the main agent presents, in the order below; what the user themselves keep is the artifact of the next section. Return this shape (copy the interfaces; they compile as-is) rather than a bare array:

<!-- compile -->

interface Finding {
  /** Workspace-relative path, with a line when it applies: "src/a.ts:42". */
  where: string;
  /** One sentence: what is wrong, or what was found. */
  what: string;
  /** What showed it: the lines read, or the command and the output that proved it. */
  evidence: string;
  /** "verified" when an independent subagent or a deterministic check confirmed it; "unconfirmed" when confirmation failed or was not attempted. */
  status: "verified" | "unconfirmed";
  /** How much it matters. Reserve "high" for data loss, a crash, or a wrong result. */
  severity: "low" | "medium" | "high";
}
interface WorkflowReport {
  /** Two or three sentences answering what the user asked for. */
  conclusion: string;
  findings: Finding[];
  /** What the run checked and how: the commands it ran, the files it covered. */
  verified: string[];
  /** What the run did not look at or could not check, and why. */
  notCovered: string[];
}

const result: WorkflowReport = {
  conclusion: "Nothing was reviewed: this snippet only shows the shape.",
  findings: [],
  verified: [],
  notCovered: ["everything — no subagent ran"],
};
return result;

Before returning it, give it an independent read (§3): a reader-proxy subagent that has seen nothing else tells you what is unclear, unsupported, or missing, while there is still time to fix it.

Each field has a reader. conclusion is the answer to what the user asked. findings carry their evidence and their status, so the user can tell what was seen from what was suspected. verified says what this run actually checked and how — the commands it ran, the files it covered. notCovered says what it did not look at and why, which is the difference between "we found nothing" and "we looked nowhere". Write all four in the language the user is speaking in this session.

Deliver artifacts. The return is read by the main agent, which retells it. artifact.* is the other channel: things the user opens, shown as cards beside the run while it is still going and kept after it ends. Two habits:

• Every run publishes its deliverable. The deliverable is whatever the user asked for. When that is a thing — a webpage, a PDF, a spreadsheet, a generated site — a subagent writes it into the workspace with its own tools and returns the path, and the script publishes that path with artifact.file. Until it does, nothing the run left in the workspace exists as far as the user is concerned, which is why "write it to out/… and return the path" belongs in the ask that produces it. When the user asked for an answer — findings, a review, an analysis — the deliverable is a report, and the return alone is not it: the return is a compact handoff the main agent retells, while the user deserves the long form of the same facts, the findings with their evidence, what was checked and what was not. Markdown composed from the same values the return is built from is the usual shape; a subagent-written document is fine when the user asked for one. Publish it once, at the end, when the facts are settled. The one exception is a run whose whole answer is a line: a verdict, a number, a yes or no. A page that restates one sentence is noise, so let the return carry it alone. When the run publishes more than one artifact, mark the deliverable { primary: true }: the completion card and the run pane lead with it (its description is shown beside the title), and the notification the main agent reads lists it first. One id per run; a run whose only artifact is the deliverable needs no flag.
• A dashboard is for the person watching the run. Its job is to answer "where is it, how is it going" without opening anything. Declare one when the run has state worth watching while it is still running: the key number after each round, which items are done and which failed. Metrics or a chart when the watched thing is a number; a table or board when it is a set of items with a status. Declare it once at the top, then tag the items you are already reporting: report(item, "perf"). Nothing else is needed; the dashboard is a projection of that stream, so it grows live and comes back identical after a resume. A run that is over before anyone would look at it needs none.

Show what matters. More artifacts is not more delivery: every card competes with the deliverable for the user's attention. Two tests decide what earns a card. Would the user open it on its own? If not, it is a section of the deliverable. Does it repeat another artifact? A CSV and a table of the same rows, a report and a copy of it, a chart and a metrics tile of the same number — one of each pair is noise. The common run publishes one deliverable, one dashboard when there is something to watch, and further files only when a subagent produced something else a person opens.

Ids and the report tag are compile-time string literals. What a run can publish is therefore fixed at the moment the user approves the script, and an id assembled at runtime is a compile diagnostic rather than a surprise. Publishing an id a second time mints the next version and keeps the old one, so a file worth republishing each round costs you nothing to name once.

A rejected publish is a repair opportunity, not an error to swallow. Content publishes reject catchably — the file is missing, the path escaped the workspace, the bytes are over the cap — and the honest response is to hand the gap back to a subagent and publish again, rather than let a run end with nothing the user can open:

<!-- compile -->

interface RoundOutcome {
  /** 1-based round number. */
  round: number;
  /** Query latency in milliseconds, measured after this round's change. */
  queryMs: number;
  /** One sentence: what this round changed. */
  change: string;
}

const TARGET_MS = 20;
artifact.chart("perf", {
  title: "Query latency by round",
  x: { field: "round", label: "Round" },
  y: { field: "queryMs", label: "ms" },
  baseline: { field: "target" },
});

phase("Optimize until the bench meets its target");
const optimizer = agent("optimizer", {
  system:
    "You speed up a JSONL query engine: change one thing, measure it, and write the profile " +
    "of the query path to out/profile.html.",
});
const rounds: RoundOutcome[] = [];
for (let round = 1; round <= 3; round += 1) {
  const outcome = await optimizer.ask<RoundOutcome>(
    `Round ${round}: make the query faster, then measure it.`,
  );
  rounds.push(outcome);
  report({ ...outcome, target: TARGET_MS }, "perf");
  if (outcome.queryMs <= TARGET_MS) break;
}

phase("Hand the user the profile and the write-up");
try {
  await artifact.file("profile", "out/profile.html", { title: "Query profile after the last round" });
} catch {
  const profiler = agent("profiler");
  await profiler.ask("out/profile.html is missing. Profile the query path as it stands and write the profile there.");
  await artifact.file("profile", "out/profile.html", { title: "Query profile after the last round" });
}
const latest = rounds[rounds.length - 1]?.queryMs ?? 0;
await artifact.markdown(
  "report",
  [
    `# Query latency: ${latest}ms against a ${TARGET_MS}ms target`,
    "",
    ...rounds.map((r) => `- Round ${r.round}: ${r.queryMs}ms — ${r.change}`),
  ].join("\n"),
  {
    title: "Optimization report",
    description: `What each of the ${rounds.length} rounds changed and what it bought.`,
    primary: true,
  },
);

return {
  conclusion: `Latency landed at ${latest}ms against a ${TARGET_MS}ms target.`,
  verified: ["each round's latency was measured by the subagent that made the change"],
  notCovered: ["memory use; only query latency was measured"],
};

One report call feeds both surfaces: the tagged item lands on the chart and in the run's progressive results, so tagging costs nothing and adds a picture. Three cards, none repeating another: the chart is what the user watched, the profile is what a person opens, the report is what they keep. The CSV the bench also wrote stays in the workspace — its rows are the chart's points, so a card for it would say nothing new.

11. A complete example

The complete review workflow that used to sit here — a reviewer per changed file, triage through one shared subagent that is fed as reviews land, a confirmer per kept finding chained inside the same callback, one join for the cross-file deduplication — is ${ZCODE_SKILL_DIR}/examples.md §5. Read it when you want to see a whole script's arc; §7 and §10 already carry its rules.

12. Anti-patterns