dynamic-workflow skill

Dynamic Workflow Skill

Runs large fan-out work as a workflow: the plan, the loop and every intermediate result live in a script and on disk, so the parent's context holds only verified results. Covers one-shot fan-outs, adversarial convergence (attempts + refuters), and multi-wave campaigns that integrate dozens of worker branches. It does not make delegate_task durable across restarts; that is the kanban swarm's job.

When to Use

Reach for it when the unit of work is clear (a file, an endpoint, a record) and there are more units than one context can hold. Skip it for under ~10 units or for serial chains. For a refactor or fix campaign on hermes-agent itself, load hermes-agent (the dev workflow) alongside; this skill owns the fan-out shape.

Prerequisites

the wave (default 10; the runtime rejects a tasks=[] larger than that with a clear error rather than queueing). delegation.maxspawndepth >= 2 only if children must fan out themselves. <!-- no-tmp: ok — explains why a literal /tmp is wrong -->

• delegatetask available and delegation.maxconcurrent_children sized for

Termux has no such directory and native Windows breaks on it. Use /wf__/, unique per run, so an interrupted earlier run cannot leave stale outputs to be misread.

• A writable run directory resolved from the terminal environment's temp dir ($TMPDIR, else the platform temp dir). Never a literal /tmp:

readfile, writefile, search_files, terminal, patch exist inside it).

• executecode for the deterministic layer (only websearch, web_extract,

How to Run

Two layers, split by a real capability boundary:

Do the deterministic part in Layer A first, fan out only the irreducibly-LLM step in Layer B, synthesize on the parent.

Background-first: results re-enter as messages

A top-level delegatetask returns immediately with one handle per task; each child's result re-enters the conversation as a new message when it finishes. You cannot read out.csv on the line after the call. Finish whatever does not depend on the children, give a one-line status, and END YOUR TURN; act on each result message as it lands. An ordinary follow-up user message does not cancel children; /stop, /new and process exit do. Only a delegation issued by an orchestrator subagent (depth > 0) is synchronous.

Quick Reference

corpus; size by the LARGEST unit. Structured output goes to files, never the summary field (it truncates under load); delimiter-separated lines over JSON.

• Unit must be answerable without sibling output, else it is serial.
• Manifest: one unit per line in /manifest.jsonl; print count + run dir.
• Per child: ~8-12 mechanical edits, or ~2-3k lines of reading, or ~50-70 KB of

• Parent verifies file count and per-run freshness before merging.
• A "stalled" child usually completed its write; check the filesystem first.
• Scoped slice first (one directory, 20 records), report token cost, then scale.

Procedure

One-shot fan-out

maxconcurrentchildren, issue bounded waves yourself.

1. Decompose into independent units.
2. Layer A pre-pass writes the manifest.
3. Size chunks against the limits above; for more tasks than

/out_.csv, prints a status word, stops.

1. Layer B: one delegate_task(tasks=[...]); each task reads its slice, writes

cross-cutting synthesis stays on the parent.

1. End the turn. As result messages arrive, read the files, verify, merge; the

Adversarial convergence (finding-quality work)

framings in each context, each writing one claim per line to /attempt_.md. Located, individually falsifiable claims only ("POST /api/users/:id/role in src/routes/users.ts:142 has no role check"); a refuter cannot break "the auth layer has problems".

1. Independent attempts: the SAME question to N children (2-4) with DIFFERENT

emitting claimidx|survives|counterevidence. Give them the sources, not the attempts' reasoning.

1. Merge and dedupe on the parent; note the agreement count per claim.
2. Refuters: a second batch told to BREAK each claim with counter-evidence,

adds no survivors, cap at 3 rounds.

1. Surface only survivors; drop refuted claims with a one-line reason.
2. Feed new claims from round 2 through one more refutation; stop when a round

The same mechanic protects the parent from its own wrong premises: when you hand children a heuristic ("every patch target on a facade is a dead seam"), tell them to refute it with evidence before acting on it. Four squads doing so turned a 647-site blanket rewrite into 59 real fixes and saved 130+ green tests.

Campaign shape (dozens of workers, several waves, hours)

The one-shot recipe does not scale to a whole-codebase pass. What did:

shared BRIEF.md plus a per-cluster task_.md. Every child reads both. When the fleet drifts (children shaving docstrings instead of cutting code), patch the brief once and steer; re-dispatched children inherit the fix.

1. Measure first (LOC, hotspots, dead symbols, oracle corpora) and write ONE

discarded at integration. Sub-fan-outs inside one file own line RANGES and define helpers inside their range so diffs merge cleanly.

1. Exclusive ownership: one cluster of files per worker, edits outside it are

Committed state is the only handoff; every worker that died mid-campaign lost exactly its uncommitted tail. A worker sharing a worktree index commits with git commit -- only; a bare commit swept a sibling's staged hunks.

1. Commit per verified step, locally, no push, no PR, no rebase from children.

hourly token refresh stampedes into 401s and kills the wave. Queue the rest.

1. Fleet size 12-16 concurrent. Above ~40 processes on one OAuth grant the

with 0 commits on its branch, has not finished; look for its sub-branches or re-dispatch it with the predecessor's worktree and diff.

1. Parent liveness: a child reporting completed with a few dozen log lines, or

give each conflicting branch its own rebase worker ("main's behaviour wins, re-applied inside the new structure"), merge onto one integration branch, run the FULL suite on the combined tree. Collisions that every branch passed alone appear only here. The next round branches from the integrated commit so its workers cannot conflict with each other.

1. Integration per round: freeze a base SHA, rebase clean branches mechanically,

is 0 for EVERY branch. Workers keep committing after you merge their tip; 168 commits across six slices were once left behind that way.

1. Before declaring a round integrated: git rev-list --count ..

Many parallel low--j runners were slower AND killed each other's process groups. Red files are re-run on a bare origin/main worktree in the same venv; identical per-file failure sets are pre-existing, not yours.

1. Test runs: exactly one runner on the box, behind a lock file, at high -j.

conflicted files by directory to workers editing ONE merge worktree with no commits, then the parent commits the merge once. CI never runs on a conflicted PR, so re-merge main before every push.

1. Forward-port at the end, not per round: freeze main's SHA, fan out the

expectation written before the check, evidence on disk, report only, and a PR-vs-main difference is the only thing that counts as a regression. Green unit tests missed the one P0 (a logged-in code path no test exercised).

1. Live QA is its own wave: one squad per surface, isolated HERMES_HOME,

base before "restoring" anything. Several confidently stated review deltas already behaved that way on base.

1. Reviewer claims get the same treatment as child claims: A/B against the