workflow

name	workflow
description	Deterministic multi-agent orchestration powered by the GitHub Copilot CLI. Use when asked to "run a workflow", "orchestrate", "fan out agents", "run agents in parallel", "spawn subagents", or to decompose a job across many independent agents — audits, code review, sweeps, research, migrations. Instead of working turn-by-turn, write a small JavaScript orchestrator on the fly; each step runs as a headless `copilot -p` child process. Reach for this when a job needs breadth, independent verification, or scale a single context can't hold.
metadata	{"version":"0.1.0"}

Workflow: deterministic orchestration with Copilot

You hold the control flow (loops, fan-out, branching) in plain JavaScript; each individual step is delegated to a fresh headless Copilot agent. The orchestration is deterministic — only the work inside each agent() call is model-powered.

Prerequisites

• GitHub Copilot CLI installed and logged in (copilot once interactively, or copilot login).
• Node ≥ 18.

How to run a workflow

When this skill triggers, do not do the task turn-by-turn. Instead:

1. Write an orchestrator script (e.g. workflow.mjs in the project root), importing the runtime that ships with this skill:

   import { agent, parallel, pipeline, phase, log } from './.claude/skills/workflow/tools/wf-runtime.mjs'
   

   Adjust the path to wherever this skill is installed (e.g. .github/skills/workflow/tools/… or ~/.copilot/skills/workflow/tools/…). If unsure, locate wf-runtime.mjs first.

2. Follow the shape: fan out → reduce → synthesize.

   phase('Find')
   const found = await parallel(items.map((x) => () => agent(promptFor(x), { schema: ITEM, label: x.id })))
   const clean = found.filter(Boolean).flatMap((r) => r.items)   // reduce in plain JS — no agent
   phase('Synthesize')
   const report = await agent(`Write a report from:\n${JSON.stringify(clean)}`)
   console.log(report)
   

3. Run it and report the result:

   node workflow.mjs
   

   Progress prints to stderr; the final console.log is the answer to relay to the user.

The primitives

• agent(prompt, { schema?, model?, label?, retries? }) — one headless Copilot agent. With schema (a JSON Schema) it returns parsed JSON and retries on invalid output; without, it returns raw text. Returns null on failure — .filter(Boolean).
• parallel(thunks) — run concurrently. Barrier: awaits all. Failures become null.
• pipeline(items, ...stages) — stream each item through stages, no barrier. Each stage gets (prev, originalItem, index).
• phase(title) / log(msg) — progress lines on stderr.

Rules (do not skip)

• Default to pipeline(). Only use a parallel() barrier between stages when a stage genuinely needs ALL prior results at once (dedupe/rank across everything, early-exit on total count, "compare against the other findings").
• Each agent is stateless — a separate process with no memory of the others. Put every bit of context it needs into its prompt.
• Never remove the recursion guard. The runtime launches children with --no-custom-instructions so they don't re-load this skill and spawn more workflows.
• Reduce with plain JS, not agents — flatten, dedupe, filter, sort are just code.
• Quota costs are real: every agent is a full Copilot invocation. Scope --allow-all-tools down for untrusted tasks, and route cheap stages with { model: '<smaller-model>' }.

Confidence patterns (compose as needed)

• Adversarial verify: for each finding, spawn N skeptics prompted to refute it; keep it only if a majority survive.
• Perspective-diverse verify: give each verifier a different lens (correctness, security, performance, reproducibility) rather than N identical ones.
• Loop-until-dry: for unknown-size discovery, keep spawning finders until K consecutive rounds surface nothing new. Dedupe against everything seen, not just confirmed results.

Resume

Set WF_JOURNAL=.wf/run.json before running to cache every agent() step. Re-running with the same journal replays cached results instantly and only re-runs new/changed steps.

Reference

See references/route-auth-audit.mjs for a complete fan-out → adversarial-verify → report workflow. tools/smoke.mjs is a 4-agent end-to-end check that the runtime can drive Copilot.