---

name: orchestration description: "Running a team of subagents on one design build: clone briefs, disjoint file ownership, isolated builds, the evidence packet, review lenses, the fix plan, verdicts, cold eyes and the stop rule, with the workflow templates bunshin runs." metadata: internal: true

Version-sensitive. The workflow tool contract (scriptPath, args, agent, parallel, phase) and the Impeccable verbs named here were checked on 2026-09-30. What against is in _jutsu/VERSIONS.md, section "Orchestration". If that date is old, re-check before relying on a verb.

Orchestration

Loaded by /genjutsu:bunshin. One art director, many clones. This module is how the clones are briefed, fenced, checked and stopped, so that ten agents in parallel produce one site and not ten opinions.

A clone is a subagent. It starts from nothing: no conversation, no memory of the thesis, no idea which files its siblings are editing. Everything it knows is in its brief. Everything that goes wrong in a fan-out goes wrong because a brief left something out.

---

The five templates

Each phase that fans out has a template under workflows/, next to this file. Each one is a workflow script: a pure meta literal, then a body that calls agent(), parallel() and phase(), parameterised entirely by args. scripts/check-workflows.mjs runs every template against stubs in CI: to the end with every agent answering, and again with every agent answering null, where a template must end or stop on its own named error (research.js and review.js do, with nothing to synthesise or plan), never crash. build.js and refine.js share one isolated-build block, which the check holds identical in both.

| Template | Phase | Clones | Writes to disk | Returns | |---|---|---|---|---| | research.js | 3, research | 4 angles, then 1 synthesis | the synthesis, at args.out | per angle the URLs read and the patterns; the synthesis | | build.js | 7, build | 1 per owner, each capturing its own page when build names static, shoot and its routes | the owner's files | per owner: files, summary, open questions, shared change requests, build status | | review.js | 9, review | 1 per lens (the finish lens asked twice when its first answer is empty), then 1 plan (none on recapture or rebuild) | each lens's review beside args.planOut, and { round, disposition, reviews, plan } at args.planOut | the round, the disposition and its recapture list, per lens its overall verdict and a finding count, the plan (null on recapture or rebuild) | | refine.js | 10, refine | the shared owner alone, then 1 per owner | the owners' files | per owner: done, not done, files, build status, notes | | verdict.js | 10, verdict | the finish reviewer, plus cold eyes when asked, then 1 to write the plan | the next round's plan at args.planOut, built by the script from the finish reviewer's remaining points | both verdicts, and the plan path |

The header comment of each template documents its args. Read it before the call; do not guess a field.

Running one. When the session has a workflow tool (Claude Code: Workflow), pass the template by path and its arguments as a JSON value, never as a JSON string:

Workflow({ scriptPath: "<SKILL_BASE>/orchestration/workflows/review.js", args: { ... } })

<SKILL_BASE> is the absolute path the skill-base block printed (genjutsu: modules from ...). The call returns at once; the result arrives when the workflow finishes. Do not poll it.

Without a workflow tool, with a subagent tool (Claude Code: Agent; other hosts name it differently): the template is the plan. node "$SKILL_BASE/orchestration/scripts/brief.mjs" <template> <args.json> prints every clone it would spawn, with its label, agent type, schema and exact prompt, so nothing is rebuilt by hand. Spawn them several in one message when the host runs them concurrently, one by one otherwise, each schema as the "return exactly this JSON" part. Calls marked afterAnswers carry a placeholder where an earlier answer goes: rebuild those prompts with the real answers.

Without either, there are no clones. bunshin does not run: say so and step down to paint. Never play ten clones in one context: that is one long session reviewing its own work, which is exactly what the independent lenses exist to avoid.

Return small, write big. A template returns what you need to decide the next step and writes the rest to disk: the full reviews go into the plan file, not into your context. Keep it that way when you adapt one.

---

The brief every clone gets

A brief has six parts, in this order. A clone that is missing one of them improvises it.

1. Who it is and what it builds. One paragraph: the project, the page or the lens, the audience, the main channel. The project named by its absolute path.
2. What to read first, in order, by absolute path. PRODUCT.md, the direction contract (the surface brief), the quality floor, the design system files, the reference surface you built yourself. "Read the codebase" is not a list.
3. What it owns. The exact files and globs it may write. Everything else is read-only, and the brief says so. See "Ownership" below.
4. The rules that do not move. The validated theses with their forbidden patterns and their Allowed patterns: line, the tells the thesis does not allow, the voice, the truth rule (nothing invented, unknown facts generic on the page and marked in the content file), mobile first, reduced motion. Copy them in: a clone cannot read the conversation where they were agreed.
5. How it verifies. The isolated build recipe, exact, with the framework binary. What counts as green.
6. What it returns. A schema. Free text from ten clones is ten formats to reconcile.

Add a seventh part when it applies: what is already verified, so reviewers do not spend a lens re-reporting a green build.

Write the brief so it survives being read by a model that has never seen the project. If a sentence only makes sense with the conversation behind it, rewrite it.

---

Ownership

Parallel clones on one working tree are safe only when no two of them write the same file.

• One owner per file, declared before the fan-out. Split by surface: each page owns its view, its content file and a components folder of its own. Everything used by more than one page (styles, layouts, shared components, scripts, the content model's common files, the framework config) belongs to one owner, named shared, or to you.
• Page clones never edit shared files. A shared need goes back as a shared_change_requests entry: the file, the change, why. You apply them, or you give them to the shared owner in the next round. Two clones editing the global stylesheet at once is how a fan-out ends in a merge by hand.
• When a shared contract changes, shared runs first and alone, then the others run with its notes (refine.js does this). A page clone that codes against a component prop that does not exist yet breaks its own build.
• The owner map is data. Keep it in .bunshin/owners.json, every owner included. Pass all of it to review.js and verdict.js, so the plan can assign any file; a file no owner lists goes to orchestrator, which is you. Pass build.js only the page owners you did not build yourself, each with its mission: never shared, never the signature surface. Pass refine.js only the owners that have fixes, or rules of the decisions file that touch their files.
• Every route exists before the fan-out. Route files are shared: create each page's route in every language before build.js runs, so a clone's page builds and captures from its first run.

---

Isolated builds

Clones build in parallel. A build in the shared working tree reads files other clones are halfway through writing, and every clone chases errors that are not its own.

Each clone builds in a copy of its own, outside the project:

D='<scratch>/build-<owner>'; rm -rf "$D"; mkdir -p "$D"
rsync -a --exclude '/node_modules' --exclude '/dist' --exclude '/.git' --exclude '/.bunshin' \
  --exclude '/.claude' --exclude '/.agents' --exclude '/.impeccable' \
  --exclude '/.astro' --exclude '/.vercel' --exclude '/.next' --exclude '/.svelte-kit' '<root>/' "$D/"
mkdir -p "$D/node_modules" && find '<root>/node_modules' -mindepth 1 -maxdepth 1 \
  ! -name .astro ! -name .vite ! -name .cache -exec ln -s {} "$D/node_modules/" \;
cd "$D" && ./node_modules/.bin/<framework> build > "$D/.bunshin-build.log" 2>&1; echo "build exit code: $?"; tail -30 "$D/.bunshin-build.log"

build.js and refine.js generate exactly this, with every path quoted.

• The framework's own binary, never the package manager. In a copy linked to the project's node_modules, pnpm build decides the install is foreign and reinstalls through the links into the real one. The binary just builds. The templates refuse a package manager as cmd.
• Link node_modules entry by entry, not as one link. Frameworks keep caches inside it (Astro writes node_modules/.astro by default): one link to the whole folder makes parallel clones write into the project's own cache at once. Linked entry by entry, each copy gets its own cache.
• Exclude the build output and every cache the framework keeps (.astro, .vercel, .next, .svelte-kit, .output, ...), so a stale output never passes for a fresh build, and a clone never captures yesterday's page.
• Green means the printed exit code is 0. A build piped into tail exits with tail's code.
• An error in a file the clone does not own is not its problem: retry once later, then report it.
• <scratch> is an absolute path outside the project, resolved before the call: the session's scratch directory when the host gives one, else the value of printf '%s\n' "${TMPDIR:-/tmp}/bunshin-<project>". The templates quote it, so an expression passed as a path would never be expanded, and they refuse one that is not absolute.

---

The evidence packet

Reviewers judge what renders. Before any review or verdict, you produce, and the packet names:

• Captures of every page at 390x664 (the height the measured run used for a social app's in-app browser on a phone, not measured on a device; measure the real one when you can), 390x844, 1280x720 and 1440x900: the first screen, and the full page cut into segments a reader can actually open (about 1700 px tall on mobile, desktop scaled to 1000 px wide). How to take them without a dev server is in references/evidence.md.
• Sources and output: the source folders and the built static output.
• The request and the answers of both gates, verbatim.
• The contract: PRODUCT.md, the surface brief (or .bunshin/direction.md), the quality floor: Impeccable's reference/craft-floor.md, or without it the tells module and its web reference, by absolute path.
• The material: .bunshin/harvest/facts.md, missing.md and sources.json, by absolute path: the truth lens holds every visible claim against them.
• With Impeccable, the chosen world's QUALITY BAR: the board and hero images of the chosen card, saved in .bunshin/direction/, named as the QUALITY BAR card; a decision comp, when one exists, named as a critique reference only.
• Already verified, with the evidence: build, type check, impeccable detect, the tells audit, overflow at each width, functional tests. Reviewers do not report these again unless they can show one is wrong.
• History, for the verdict only: the previous plan file, the refine results, the decisions file.

---

The lenses

| Lens | Holds | Loads | |---|---|---| | finish | The render against the request, the answers and the direction contract. Gives the disposition: ship, fix, rebuild, recapture. With Impeccable installed, it is