Stop 5 of 7
Parallel work
Running several agents at once is the harness's most expensive capability and the easiest one to misuse. The whole decision rests on one word — independent — and that word has a mechanical definition.
What "independent" actually means
Two features may run in parallel when both hold:
empty depends_on and
non-overlapping scope. Not "they feel unrelated". Not
"different tickets". Those two fields, checked.
Scope overlap between two features
scope overlaps — two agents own the same files
Choosing the mode
Single-session
One feature is next and it touches fewer than 5 files, or the work is sequential, or you explicitly want focused work. You are both lead and implementer — say so out loud, so it is a decision rather than a forgotten step.
Workflow mode
Two or more independent, spec-verified features are ready. The
lead launches /vv-harness:implement-features: one implementer per
feature in an isolated worktree, then a reviewer per feature, returning structured
per-feature results the lead integrates.
"Fewer than 5 files ⇒ single-session" is not the rule. When two verified independent features each touch fewer than 5 files, workflow mode still wins — the parallel gain outweighs single-session's simplicity once two independent verified features exist. The 5-file threshold decides between one feature and one session, not between one feature and two.
What workflow mode does
Each agent gets a physically separate copy of the repository. That is the cleanest separation available — scope violations become impossible rather than merely detected. The lead never edits feature code in this mode: it prepares inputs, launches, and integrates the returned results, so the task and commit gates fire in the lead's own session.
If the Workflow tool isn't available
Older CLI, or an organization that disabled it. Do not abort parallel
work. Fall back to plain subagents spawned with the same
vv-harness:* agent types, passing worktree isolation at spawn time for
independent scopes. Same isolation, same agents, sequencing still with the lead.
Roles map to tiers, not to model names
Roles and their cognitive-demand tiers are protocol — they don't change when a model generation ages out. Which model name fills each tier is a binding, updated by a requalification pass.
| Role | Tier | Reasoning |
|---|---|---|
| Lead (coordinator) | Opus | Decomposition, synthesis, and quality judgment need deep reasoning |
| Feature implementer | Sonnet | Scoped TDD inside a well-defined directory |
| Layer implementer | Sonnet | Same |
| Researcher | Sonnet | Retrieval-heavy, not reasoning-heavy |
| Reviewer | Opus | Deep review catches subtle bugs; worth the cost |
Elevation escalates the review, not the implementer. A feature
marked risk: "elevated" buys a deeper review pass and, optionally, an
author-blind conformance check — both of which judge the work rather than
produce it. Executors stay on the execution tier. A feature is elevated when it
touches 10+ files or spans modules, changes a shared interface, is
security-sensitive, or is the first feature in a new codebase.
When not to parallelize
Given equal weight in the source, and it should be given equal weight by you.
- Only one feature is ready. Nothing to overlap.
- The work is sequential — step B needs step A's output and there is nothing else to run.
- Features touch fewer than 3 files each. Sequential single-session is cheaper; the lead runs for the whole session regardless of how many agents launch.
- Agents share an interface. Worktree isolation is exactly wrong here — they need to see each other's changes in real time. Give one feature the shared interface and sequence the rest behind it.
- Orchestration overhead exceeds the benefit. When in doubt, start with a single session and escalate if the task naturally decomposes.
Research or competing-hypothesis work that genuinely needs agents to argue with each other is not what an implement→review pipeline does. Spawn plain parallel subagents for that instead.
Only verified specs enter a batch
Unverified features are excluded from a parallel batch, never silently
included. Verification comes from the spec gate: read-only
spec-verification and reverification-guard agents prove a
spec is testable, unambiguous, and internally consistent before any implementation
starts. Verdicts are PASS, ASK, or BLOCK.
The framing: the harness is a mint. It verifies specs interactively,
where human judgment is cheap, and emits proof — a local spec field, or
a signed readiness stamp on an issue. An external runner is a consumer
that validates the stamp before trusting the issue for unattended work.
reverification-guard exists for one specific failure mode: when a human
answers the gate's questions, the guard re-runs every check against the amended text
and refuses to advance on pressure alone. Anti-sycophancy, encoded
as an agent rather than requested in a prompt.