Workflows-Driven Development
Shape the work as a workflow: a deterministic DAG of phases, each phase a
wave of parallel subagent tasks under explicit contracts, closed by
verification the parent runs itself. The workflow, not the conversation, is
the unit of execution: same decomposition, same contracts, same gates, every
run.
When to go workflow-shaped
Three shapes earn the ceremony:
- Coverage: the task decomposes into parallel slices (audit every module,
migrate every callsite, survey every subsystem).
- Confidence: the result needs independent perspectives or adversarial
checks before you commit (review waves, competing analyses).
- Scale: the evidence exceeds one context window (repo-wide sweeps,
multi-repo research).
A quick lookup or single edit stays inline; spin up no agents. An ordered
plan with per-task review gates belongs to subagent-driven. A flat split into
independent concerns, with no phase structure or verification wave, belongs to
parallel-launch.
The contract
Scout inline first (list the files, scope the diff, find the call sites)
until you can name the work list. Then:
- Phases. Order the workflow as phases; a phase is one wave of parallel
tasks plus a barrier. Later phases consume earlier phases' evidence.
- Batch context carries the shared contract for the whole wave:
# Goal: what the wave accomplishes.# Constraints: rules, non-goals, permissions, verification limits.# Contract: shared interfaces, output shape, coordination rules.
- Each assignment is self-contained:
# Target: exact files, symbols, or evidence surface; explicit non-goals.# Change: what to inspect or modify, step by step, patterns to reuse.# Acceptance: observable result and return packet. Workers skip
formatters, linters, and project-wide tests; the parent runs shared proof
once.
- Disjoint write scopes. Every writing worker owns its paths exclusively;
shared files (manifests, configs, indexes) are edited only by the parent.
- Pointers, not payloads. Workers exchange file paths and artifacts,
never pasted blobs.
Verification patterns
- Adversarial verify: dispatch skeptical reviewers with distinct targets;
keep only findings the parent confirms against source.
- Perspective-diverse review: separate correctness, security, performance,
and maintainability roles instead of identical reviewers.
- Completeness critic: after the first wave, one read-only critic asks
what file, claim, modality, or proof was missed.
- Circuit breaker: give each batch a success threshold; when a batch falls
below it, stop the workflow and rediagnose instead of spending the remaining
budget on a broken playbook.
- No silent caps: bounding coverage (top-N, sampling, no-retry) is
declared with what was dropped and why, before acting on partial evidence.
- Parent owns closure: workers return evidence; the parent reads it,
resolves contradictions, runs the shared proof, and makes the final call.
Durability
Track the workflow in the visible todo list, one entry per phase. Keep
evidence in files (artifacts, ledgers), not conversation memory: a resumed or
compacted session must pick up from the ledger alone. On hosts that
checkpoint workflow runs, resume instead of rerunning; completed tasks
return cached evidence.
Materialize on your host
The contract above is host-neutral; the fan-out primitive is not. Detect,
then read the matching reference:
- Claude Code (Dynamic Workflows:
/workflows exists, plugins ship
workflows/*.js): read references/claude-code.md. Default ephemeral;
build and run the workflow for the task at hand, and save to
.claude/workflows/ only when it will recur.
- oh-my-pi (a
task tool that batches tasks[]): read
references/omp.md. The task batch is the only fan-out primitive; never
emulate batching with shell loops or eval helpers.
- Neither: run the same contract inline as sequential waves of subagent
calls, same batch context and assignments, parent owns closure.
Red flags
- One worker spawned, parent idle behind it: do that work inline.
- Independent slices dispatched serially: one wave, one batch.
- A wave declared done without the parent's own proof pass.
- Two workers writing one file: the wave was mis-partitioned; stop and re-cut.
- A coverage cap the summary never mentions.
1---2name: workflows-driven3description: Drive decomposable work as a deterministic multi-subagent workflow: phased fan-out under per-task contracts with adversarial verification. Use for audits, migrations, broad research or review sweeps, work needing independent cross-checks before committing, or scale one context cannot hold.4---5
6# Workflows-Driven Development
7
8Shape the work as a **workflow**: a deterministic DAG of phases, each phase a
9wave of parallel subagent tasks under explicit contracts, closed by
10verification the parent runs itself. The workflow, not the conversation, is
11the unit of execution: same decomposition, same contracts, same gates, every
12run.
13
14## When to go workflow-shaped
15
16Three shapes earn the ceremony:
17
18- **Coverage**: the task decomposes into parallel slices (audit every module,
19 migrate every callsite, survey every subsystem).
20- **Confidence**: the result needs independent perspectives or adversarial
21 checks before you commit (review waves, competing analyses).
22- **Scale**: the evidence exceeds one context window (repo-wide sweeps,
23 multi-repo research).
24
25A quick lookup or single edit stays inline; spin up no agents. An ordered
26plan with per-task review gates belongs to subagent-driven. A flat split into
27independent concerns, with no phase structure or verification wave, belongs to
28parallel-launch.
29
30## The contract
31
32Scout inline first (list the files, scope the diff, find the call sites)
33until you can name the work list. Then:
34
351. **Phases.** Order the workflow as phases; a phase is one wave of parallel
36 tasks plus a barrier. Later phases consume earlier phases' evidence.
372. **Batch context** carries the shared contract for the whole wave:
38 - `# Goal`: what the wave accomplishes.
39 - `# Constraints`: rules, non-goals, permissions, verification limits.
40 - `# Contract`: shared interfaces, output shape, coordination rules.
413. **Each assignment** is self-contained:
42 - `# Target`: exact files, symbols, or evidence surface; explicit non-goals.
43 - `# Change`: what to inspect or modify, step by step, patterns to reuse.
44 - `# Acceptance`: observable result and return packet. Workers skip
45 formatters, linters, and project-wide tests; the parent runs shared proof
46 once.
474. **Disjoint write scopes.** Every writing worker owns its paths exclusively;
48 shared files (manifests, configs, indexes) are edited only by the parent.
495. **Pointers, not payloads.** Workers exchange file paths and artifacts,
50 never pasted blobs.
51
52## Verification patterns
53
54- **Adversarial verify**: dispatch skeptical reviewers with distinct targets;
55 keep only findings the parent confirms against source.
56- **Perspective-diverse review**: separate correctness, security, performance,
57 and maintainability roles instead of identical reviewers.
58- **Completeness critic**: after the first wave, one read-only critic asks
59 what file, claim, modality, or proof was missed.
60- **Circuit breaker**: give each batch a success threshold; when a batch falls
61 below it, stop the workflow and rediagnose instead of spending the remaining
62 budget on a broken playbook.
63- **No silent caps**: bounding coverage (top-N, sampling, no-retry) is
64 declared with what was dropped and why, before acting on partial evidence.
65- **Parent owns closure**: workers return evidence; the parent reads it,
66 resolves contradictions, runs the shared proof, and makes the final call.
67
68## Durability
69
70Track the workflow in the visible todo list, one entry per phase. Keep
71evidence in files (artifacts, ledgers), not conversation memory: a resumed or
72compacted session must pick up from the ledger alone. On hosts that
73checkpoint workflow runs, resume instead of rerunning; completed tasks
74return cached evidence.
75
76## Materialize on your host
77
78The contract above is host-neutral; the fan-out primitive is not. Detect,
79then read the matching reference:
80
81- **Claude Code** (Dynamic Workflows: `/workflows` exists, plugins ship
82 `workflows/*.js`): read `references/claude-code.md`. Default ephemeral;
83 build and run the workflow for the task at hand, and save to
84 `.claude/workflows/` only when it will recur.
85- **oh-my-pi** (a `task` tool that batches `tasks[]`): read
86 `references/omp.md`. The `task` batch is the only fan-out primitive; never
87 emulate batching with shell loops or eval helpers.
88- **Neither**: run the same contract inline as sequential waves of subagent
89 calls, same batch context and assignments, parent owns closure.
90
91## Red flags
92
93- One worker spawned, parent idle behind it: do that work inline.
94- Independent slices dispatched serially: one wave, one batch.
95- A wave declared done without the parent's own proof pass.
96- Two workers writing one file: the wave was mis-partitioned; stop and re-cut.
97- A coverage cap the summary never mentions.
majiayu000