| name | deep-work |
| description | Run a large, multi-place, uncertain task to completion via "plan → adversarial review → serial execute → synthesize & verify." Trigger: cross-file refactor, data migration, large feature build, system audit, deep research — tasks that can't be done in one pass and touch many places. Manual invocation: /deep-work.
|
deep-work — Multi-Agent Orchestration
Take a task too big to force through in a single pass and run it through four roles:
Planner → Adversarial Reviewer → Executor pool → Synthesizer. Complex tasks usually
fail not from a lack of intelligence, but from acting too fast, never challenging the
plan, and not verifying when done.
Route first
This skill is the conductor. Before running the full loop, route:
- The task is a codebase audit / production-readiness review → use
deep-analysis
(it already runs readers → skeptics → roadmap with the right schemas).
- The task is a defined feature or bugfix → use
implementation / /implement.
- The task is a broad, multi-place execution that is neither (large refactor,
migration, multi-source research) → run the four stages below, delegating slices to
implementer agents and challenges to adversarial-verify.
- If the shared board must outlive this context window (multi-session work) → persist it under
thoughts/<task-slug>/ per the thoughts skill, and resume from it next session.
When to use / not use
Use: refactors across ≥3 files, data migrations, large features, system audits,
research needing many sources — any task where getting one spot wrong sets off a chain
reaction.
Don't use (overkill): single-file edits, answering a question, looking up one value,
running one command. Do these directly.
Rule of thumb: if it takes several steps and you're not yet sure of the details of each
step → use it.
The four stages
Stage 1 — Plan (Planner)
Don't act yet. Break the task into independent subtasks, each labeled with:
- What it changes (files/scope)
- What it depends on (which subtask must finish first)
- Safety level (touches a core many things depend on → mark "high risk")
- (only if you'll parallelize) Which files it shares with a sibling subtask — so two
otherwise-independent slices that collide on one file can be put in different waves
(Stage 3) instead of forced fully serial
Produce a subtask list. This stage only thinks; it doesn't do.
Stage 2 — Adversarial Review
Hand the Stage 1 plan to an independent agent to challenge — ideally from another
angle. Prompt it:
This is a task plan. Your job is not to affirm it — find where it will fail.
Assume this plan has a 60% chance of missing something. Challenge specifically:
- Which subtasks have hidden dependencies, so the serial order is wrong?
- Which "assumed simple" subtasks actually ripple into other places?
- Is there a simpler approach (subtraction) that avoids doing this much?
- Which steps, once done, can't be verified for correctness?
Support every challenge with ls / grep / reading real files — not guesses.
Problems surfaced → revise the plan. This is the highest-value stage — don't skip it.
The adversarial-verify skill runs exactly this move and can be called here directly.
Stage 3 — Serial Execution (Executors)
Execute subtask by subtask. Iron rule: subtasks that touch the same git working tree
run serially, never in parallel — parallel agents eat each other's staged changes and
commits end up mismatched. Only unrelated subtasks touching disjoint files run in parallel.
Give each executor a dead-spec, don't let it explore on its own:
- Which file, which lines, changed to what
- How to verify when done (which test / what smoke check)
- One subtask, one commit (atomic)
At scale, four optional refinements — defaults above stay; reach for these only when the
parallel set is large enough that the default leaves real time on the table:
- Scout once, share once. Before fanning out >1 executor over a shared codebase, scout
the shared facts yourself and bake them into one common preamble every executor gets (the
way
deep-analysis builds its CTX), so each spends its budget on its slice instead of
re-deriving the architecture. Keep each slice's dead-spec; add the shared layer above it.
- Cap the fan-out. Honor any owner ceiling on concurrent mutating agents (e.g. a
max_parallel_agents memory); absent one, start with a small fan-out and widen only once
disjointness is proven. Read-only agents (e.g. deep-analysis readers) aren't capped.
- Waves, not blanket-serial. The iron rule sends same-tree work serial. When several
independent slices collide only on one shared file, you may instead group them into
waves — run the disjoint slices in parallel (wave 1), then the colliding slice alone
(wave 2) — recovering the parallelism a blanket serial throws away. Truly-coupled work
still runs serial; waves are only for independent slices that happen to share a file.
- Worktrees — the last resort. When slices genuinely can't be made disjoint and waves
would serialize too much (many slices all mutating overlapping files), isolate each agent in
its own checkout —
git worktree add, or a Workflow with isolation: 'worktree' — and
integrate the branches yourself. The merge conflicts are yours to resolve, so this earns its
keep only when the parallelism saved outweighs the merge cost. The verify gates are
per-worktree safe — each worktree carries its own ledger, so an agent in one can't satisfy or
clobber another's gate (the gate suite's worktree-isolation test proves it). Disjoint-parallel
and waves stay the defaults; reach for this only when both can't hold.
Stage 4 — Synthesize & Verify
After all subtasks are done:
- Converge the results; check the whole achieves the original task.
- Verify the root-cause fix took effect — run end-to-end tests, look at real output.
- Don't accept a self-reported "I'm done." Look at evidence (logs / green tests /
actual behavior), not the agent's claim that it finished.
Verification finds it wasn't really fixed → go back to Stage 1 and re-plan that part.
Flow
Plan (think only)
→ Adversarial review (independent agent finds plan holes; must look at real files)
→ Serial execute (dead-spec / same git tree serial / atomic commits)
→ Synthesize & verify (real evidence, not self-reports)
→ if it doesn't pass, re-plan
Key disciplines
- Stage 1 thinks only — the most expensive failure is charging ahead on a wrong assumption.
- Don't skip Stage 2 — one independent challenge beats re-thinking it yourself.
- Stage 3 — serial to prevent races + dead-spec.
- Stage 4 — verify real evidence, don't trust self-reports.
