Authoring Dynamic Workflows: Building Reusable Research Pipelines with phase / agent / pipeline

Lock outputs with a schema

A workflow usually breaks when an upstream agent returns an unexpected shape. schema prevents that. Pass a JSON Schema to each agent call and the agent is required to return structured data downstream stages can handle safely.

const EXTRACT_SCHEMA = {
  type: "object",
  required: ["claims"],
  properties: {
    claims: {
      type: "array",
      maxItems: 5,
      items: {
        type: "object",
        required: ["claim", "quote", "importance"],
        properties: {
          claim: { type: "string" },
          quote: { type: "string" },
          importance: { enum: ["central", "supporting", "tangential"] },
        },
      },
    },
  },
};
 
const extracted = await agent(
  "Extract up to 5 checkable claims from this article. " +
    "Attach a direct quote from the body as quote for each.\n\nArticle path: " +
    ARTICLE,
  { label: "extract", phase: "Extract", schema: EXTRACT_SCHEMA },
);

The point is enum and required. If importance were free text, downstream sorting would fall apart; constrained to central / supporting / tangential, it becomes a sort key directly. I wrote this loosely at first and twice watched downstream sorting fail because the keys didn't line up. Design the schema backward from what downstream needs.

Understanding pipeline vs parallel in code

parallel is simple: it runs an array of functions at once and returns results as an array. The concurrency cap is 16, so passing more is throttled internally.

phase("Verify");
const VOTES = 3;            // verifier agents per claim
const REFUTES_TO_KILL = 2; // 2+ refutations kills the claim
 
const verified = await parallel(
  extracted.claims.map((c) => () =>
    parallel(
      Array.from({ length: VOTES }, (_, v) => () =>
        agent(
          "You are a skeptical verifier. Try to refute this claim.\n" +
            "Claim: " + c.claim + "\nQuote: " + c.quote,
          { label: "vote" + v, phase: "Verify", schema: VERDICT_SCHEMA },
        ),
      ),
    ).then((verdicts) => {
      const valid = verdicts.filter(Boolean);
      const refuted = valid.filter((x) => x.refuted).length;
      const survives = valid.length >= REFUTES_TO_KILL && refuted < REFUTES_TO_KILL;
      log('"' + c.claim.slice(0, 40) + '": ' + refuted + " refutes " + (survives ? "kept" : "killed"));
      return { ...c, survives };
    }),
  ),
);

pipeline, on the other hand, flows each upstream output into the next stage. /deep-research writes "search per angle, then fetch sources while de-duplicating URLs" as a pipeline, so it can flow each angle into fetching as soon as that angle returns, without waiting for all searches. For processing that requires full aggregation (like finalizing the claim pool before verification), put a barrier (an awaited parallel) after the pipeline. Keeping that distinction in mind stabilizes the design.

Porting the adversarial-verification pattern

The code above is exactly that, and the 3-vote adversarial scheme fits article fact-checking cleanly. Across four sites I publish four pieces a day total, and I always needed a step to confirm a generated article's claims don't drift from the official docs. Replacing pure mechanical checks (like my article_gate.py) with a structure that has multiple agents attempt refutation and drops any claim with 2+ refutations catches factual errors that rule-based checks can't.

Abstentions need care. When an agent returns null on error or user-skip, counting that as "no refutation, survives" lets all-abstain claims slip through. Putting a minimum valid-vote quorum into the survival condition, like valid.length >= REFUTES_TO_KILL, is the key to avoiding that trap.

Token cost and routing models per stage

A workflow drives dozens to hundreds of agents, so it clearly uses more tokens than working the same task in conversation. That's a real cost, and the reason an alternative route, zeroing out API spend with a local VLM (something like Ollama + Qwen3-VL), draws attention comes down to this same cost problem.

Still, I don't think you need to abandon cloud-model workflows. The key is routing models per stage. Each agent uses the session model by default, but for stages that don't need a strong model (extraction, labeling), you can ask Claude in the task description to "use a smaller model for this stage." Reserve the stronger model for stages where judgment matters, like verification and synthesis, and total cost drops sharply.

In practice I check things in this order.

1. Check /model before a big run (so you don't run on the small model you switched to for routine work)
2. Put "use a smaller model" into the task description for mechanical stages like extraction and classification
3. Mind the 16-concurrent / 1,000-total caps, and narrow item counts with maxItems or slice

When updating my wallpaper apps (over 50 million downloads across iOS and Android), I split manual investigation the same way: a small model for classifying crash reports, a stronger one for correlating root causes. The same allocation thinking carries straight over to workflows.

Pitfalls in real use

Things I hit while writing and running scripts.

• No user input mid-run. If your design needs human sign-off partway, split it into separate workflows per stage.
• The script itself can't touch the filesystem or shell. Reading and writing is the agents' job; the script only coordinates. Confuse this and you'll reach for fs and break the design.
• Resume works only within the same session. Quit Claude Code and the next run starts from zero, so plan long runs to stay inside one session.
• Don't count abstentions / null as survival. Especially for verification, always put a valid-vote quorum into the survival condition.

Save it and reuse it

The value of a custom workflow isn't a one-off run; it's saving it as a repeatable command. Once you get a run you're happy with, select it in /workflows, press s, and save to .claude/workflows/ (team-shared) or ~/.claude/workflows/ (yours only). From then on you call it as a command like /article-fact-check.

As a first step, copying the /deep-research raw script and swapping the search target from the web to your own repo (article MDX) is the easiest entry point. The schema and verification structure carry over almost unchanged. To keep the instructions you hand those scripts lightweight, the design principles in designing skills that stabilize output with template fixing and decision guides apply directly to the prompts inside a workflow too.

I have a feeling this verification-backed structure quietly helps keep quality up across multiple sites run by one person. I'd be glad to keep experimenting alongside you.