/workflow-builder

Builds saved dynamic workflows: JS files in .claude/workflows/ that orchestrate N parallel sub-agents deterministically (loops, fan-out, schemas, adversarial verify) and surface in the skill list by meta.name. The harness API lives in reference.md — read it before writing any JS. Doctrine: references/claude-code-workflows.md.

Phase 0 — Source check (silent)

Confirm references/claude-code-workflows.md and this skill's reference.md exist. If either is missing, stop and tell Gera which source to re-ingest. Don't build from memory — the harness API drifts.

Phase 1 — Decision gate (mandatory)

Don't ask "what workflow?" yet. First confirm the task is workflow-shaped. One AskUserQuestion summarizing the task, options:

• Saved workflow — the task splits into MANY pieces that run independently at the same time (width), AND it will recur (rerunnable). Proceed.
• Script — deterministic, no-judgment work (parse, transform, hit an API). House pre-check: that's scripts/, not agents at all. Stop.
• Just-ask — one Claude can do it in-session without fan-out. No artifact. Stop.
• One-off workflow (don't save) — width-shaped but probably never again. Tell Gera to ask for a one-off dynamic workflow with explicit scope + caps and review the generated JS before approving the run (NOT blanket "ultracode" — that flips expensive defaults session-wide). Stop.
• Sub-agents / agent team — a few specialized roles, maybe talking to each other, not a wide fan-out. Refer to /agents-team-builder (or plain sub-agents). Stop.
• /goal loop — depth not width; run until criteria met. Refer there. Stop.
• Skill — a reusable recipe Gera runs interactively, no parallelism needed. Refer to /skill-builder. Stop.

The test (from the doctrine): "Does this break into many pieces that can run independently of each other at the same time?" No → not a workflow.

Phase 2 — Preflight

• Workflows are model-agnostic harness features of recent Claude Code builds; verify by running /workflows (lists runs) rather than trusting version strings — wrapper installs can report stale numbers. They survive the 2026-06-22 Fable cliff.
• Save location is in-project .claude/workflows/ — never the global default dir.
• Remind Gera of the cost story ONCE here: a careless workflow burned half a $200/mo subscription in one run. Mitigations are designed in Phase 3 (bounded scope, named deliverable, worker model choice).

Phase 3 — Discovery Interview

AskUserQuestion, one round at a time; skip rounds already answered. Stop when 95% confident.

Round A — Deliverable + recurrence. (1) What does a successful run RETURN (one concrete artifact/answer — "a report of X with fields Y,Z", never "insights")? (2) When does this rerun (what trigger/occasion)? (3) kebab-case name.

Round B — Fan-out shape. (1) What is the UNIT of parallel work (a file, a wiki page, a finding, a URL)? (2) How does the run DISCOVER the unit list (glob, grep, args, fixed list)? (3) Expected batch size per run (10? 100?) and the cap if discovery explodes. (4) Single-pass, or loop-until-dry (keep spawning finders until K rounds return nothing new)?

Round C — Quality + structure. (1) Do workers return prose or a SCHEMA (almost always schema — define the fields)? (2) Is there a VERIFY pass (adversarial refuters / diverse lenses) before results count? For anything reporting "findings", default YES. (3) Dedupe key across rounds/workers?

Round D — Cost. (1) Worker model — DEFAULT Haiku for mechanical scan/extract, Sonnet for judgment work; inheriting the session model requires an explicit reason (on Opus/Fable sessions every worker inherits that cost). Synthesis stays on the session model. (2) Hard bounds: max items, max rounds, budget-guarded loops. (3) args parameterization so scope can be narrowed per-run.

Confirmation round — echo back a fenced summary (name, deliverable, unit + discovery, phases, schemas, verify strategy, model + bounds) and get explicit yes before writing the file.

Phase 4 — Validation gates

Phase 5 — Generate the artifact

1. Write .claude/workflows/<name>.js using the house skeleton (full API + patterns in reference.md):
   • export const meta = { name, description, whenToUse, phases } — pure literal; name matches filename; description + whenToUse become the surfaced skill text.
   • phase() per stage; workers via agent(prompt, {label, phase, schema, model}); pipeline() by default, parallel() only for true barriers; .filter(Boolean) after every parallel; bounds + dedupe from Phase 3/4.
2. Self-check: node --check .claude/workflows/<name>.js (syntax only — never execute it).
3. Do NOT fire it. Build = cheap (text); fire = expensive (N sessions). Gera invokes it by name when he wants a run.

Phase 6 — Output to chat

## Saved workflow ready: <name>

File: `.claude/workflows/<name>.js` — invoke by name in any session ("run the <name> workflow"),
or narrow scope with args.

### Cost reality
One run ≈ <estimate> sub-agents on <model>. Bounds: <caps>. Workflows can eat a Pro/Max session
limit fast — fire deliberately, not habitually.

### First run
Run it once SUPERVISED on a small scope (args-narrowed) and check the deliverable shape before
trusting it on full scope.

Phase 7 — Log + register

• Append to references/log.md: ## [<date>] create | Workflow — <name> + one detail line.
• Add the workflow to the CLAUDE.md "Saved workflows" bullet (stay within the 2-line cap — extend the existing list, don't add a new bullet).
• New harness facts discovered while building → update reference.md here, not scattered notes.

Mode 2 — Optimize / Mode 3 — Audit

Optimize (existing workflow misbehaving): read the JS first — never optimize unread code. Common symptoms → fixes: results vanish silently → missing .filter(Boolean); runs forever → no dry-counter/budget guard or dedupe vs wrong set; merge step starved → barrier parallel() where pipeline() belongs; bland findings → workers lack schemas or verify pass; cost spikes → no caps, workers on too-big a model.

Audit checklist (per file in .claude/workflows/): [ ] meta pure-literal, name==filename [ ] bounded (caps/budget) [ ] schemas on data-returning workers [ ] verify pass on findings [ ] dedupe key correct [ ] no Date.now/Math.random [ ] .filter(Boolean) after parallels [ ] description/whenToUse accurate for surfacing [ ] still matches its doctrine entry in CLAUDE.md.

Notes / discipline

• Don't fire it for him. Ever. Same rule as agents-team-builder.
• The prompt IS the workflow — workers' prompts carry all context; they inherit zero conversation history.
• Workers on the smallest model that survives the task; synthesis on the session model.
• Skill stays under 500 lines; harness detail lives in reference.md.
• Review of a built workflow file routes to Codex (No-Self-Review Law).

Related

• references/claude-code-workflows.md — doctrine + ladder.
• reference.md — harness JS API, verified shapes, house patterns.
• .claude/workflows/exhaustive-review.js, wiki-audit.js — living examples.
• Sibling builders: /skill-builder, /agent-builder, /routines-builder, /agents-team-builder, /plugin-builder, /servy-routine.