/vertical-workflows

name: vertical-workflows
description: Author a Claude Code dynamic workflow to run a John fan-out phase at scale. Use this skill whenever a phase has dozens-to-thousands of uniform per-entry work units (extract every chunk, apply every rule to every chapter, render every slide) and the session is configured for workflows. It is John's vertical-axis execution engine — it fans out worker subagents off your context, adversarially cross-checks them before anything folds in, and wires every worker to John's event log. Reach for it instead of hand-dispatching subagents one wave at a time. If workflows are unavailable, fall back to inline dispatch per subagent-dispatch.
metadata:
  triggers:
    - vertical workflow
    - fan-out phase
    - run the extract phase
    - sweep at scale
    - workflow for this phase
    - parallel subagents at scale
    - cross-check the extraction
    - thousands of entries

vertical-workflows

A dynamic workflow is a JavaScript script the Claude Code runtime executes in the background. You describe the work; you write the script with your Workflow tool; the runtime fans out subagents (up to 16 at once, 1,000 per run), keeps every intermediate result in *script variables* instead of your context, and hands you back only the final summary.

For John, that is the **vertical axis** — the hundreds-to-thousands of knowledge entries that each need the same kind of work, done in parallel. Until now you walked down each column by hand, placing one subagent at a time and holding every report in your own context. Past a few dozen entries your context floods. A workflow turns the whole column into an assembly line you write once.

**This skill teaches the *shape* of a John workflow, not the workflow API.** You already have the Workflow tool and know its JavaScript surface; what you need from John is *what a John-shaped fan-out looks like* — where the work-list comes from, how workers wire to the event log, what the cross-check stage checks, and what to return. Map that shape onto the live API yourself.

The one idea that makes this safe: engine vs truth

John already separates **what's on disk (truth)** from **how the agent produced it (execution)**. The vertical axis writes per-entry **events** to `<project>/.john/events/<phase>/`, and `reduce_events.py` folds them into `<project>/.john/checkpoints/<phase>/state.json`. You never trust a tool-call assertion; you read the checkpoint.

A workflow is just a new **execution engine** under that contract:

• The workflow keeps results in variables for speed and a clean context.
• But its worker agents still **write events to `.john/events/<phase>/`** — the same files inline subagents write.
• After the run, you still run `reduce_events.py` and read the checkpoint. **That is truth, not the script's return value.**

This is why adoption is low-risk: nothing below the execution line changes. Same events, same reducer, same PLAN.md. See [[event-log-and-reducer]].

When to author a workflow — and when not

If the session is in `ultracode`, your default leans toward orchestrating *everything* as a workflow. **Narrow that to fan-out work.** The decision is three-tier (it mirrors [[subagent-dispatch]]):

a few units, result needed in your context     → inline subagent (no workflow)
dozens–hundreds, uniform per-entry work         → ONE workflow run        ← this skill
thousands                                        → batched workflow runs per chunk-range,
                                                    all writing to the same event log

Author a workflow when the work is **uniform and high-fan-out**: "extract from every chunk," "apply every rule to every chapter," "render every slide." The per-unit task shape is identical; only the input differs. That homogeneity is exactly what a script loops over cleanly.

Do **not** reach for a workflow when:

• **It's a handful of units.** Spawning a whole runtime has overhead; just dispatch inline.
• **The work is coupled.** If unit A's output is unit B's input, it's serial, not a fan-out.
• **It needs the user mid-task.** A workflow takes no user input once it starts (only agent permission prompts can pause it). Anything needing sign-off belongs in the main session — see the constraints below.
• **The decision depends on your conversation with the user.** Workers start with fresh, isolated context; if the live conversation is load-bearing, do it inline.
• **It's the produced app's own runtime work.** Jobs the app's end-users wait on (upload → generate → download) run inside the produced app at its runtime, not in the John session — that's [[job-runtime]], a different layer with its own machinery.

A phase boundary — review results, update PLAN.md, ask the user — is the **seam *between* workflow runs**, never inside one. The docs' own guidance: "for sign-off between stages, run each stage as its own workflow." [[ralph-loop]] drives that seam.

The John-shaped workflow — four stages

Describe these stages to your Workflow tool. They are responsibilities, not a fixed script.

**Stage 0 — get the work-list (an indexing agent).** The script itself has no filesystem or shell access; only agents read and write. So the first agent reads the phase's index — e.g. `<project>/.john/chunks/chunks_index.json` — and returns the list of work units (chunk IDs, rule×chapter pairs, slide specs). The script loops over what this agent returns.

**Stage 1 — fan out one worker per unit.** Dispatch the matching `agents/*.md` worker (e.g. `knowledge-extractor`) once per work unit. Brief each worker fully — workers inherit nothing from your conversation or PLAN.md ([[subagent-dispatch]] has the briefing checklist; it applies verbatim to workflow workers). Each worker **writes its events to `<project>/.john/events/<phase>/<work-unit>/...`** and returns a one-line digest. The script collects digests in a variable; the durable record is the event files on disk.

**Stage 2 — adversarial cross-check