bunshin

The Shadow Clones. genjutsu's full-scale pipeline: a whole website or web app built by a team of subagents under one art director, with two human gates, the cost announced first, and refine rounds looped until only minor issues remain, the tier's round cap is reached, or a round fixes nothing.

bunshin builds a whole website or web app, first version, from scratch or as a full redesign. It is the one job cast and paint are too small for, and it exists for that job alone: a site at the level a client would pay an agency for.

One art director, many clones. The main agent keeps the direction: it writes the direction contract, builds the foundation and the signature surface itself, and decides what every review means. The clones are subagents. They research, build the pages in parallel on files that never overlap, review through independent lenses, and apply the fixes. Impeccable, when it is installed, leads the product interview and draws the visual direction; genjutsu’s modules govern the motion, the platform principles, the tells and the audit. You are asked twice, and once more only to go past the tier’s round cap.

With the Claude Code plugin it is /genjutsu:bunshin. After an npx install or on claude.ai, /genjutsu sends a request here only when you name it (“bunshin”, “the shadow clones”) or say yes when cast or paint propose it. A whole-site request without that word goes to paint, whose first step proposes bunshin when the brief and the host fit.

bunshin, paint, cast

When it is the wrong tool

bunshin recognises a request smaller than a site in its first phase, says so in one line before anything is spent, and hands over:

You can overrule the step down. bunshin then runs, and says what it expects to be oversized.

What the host needs

bunshin runs where the session can spawn subagents: Claude Code, as far as the genjutsu repository has checked. claude.ai and Cowork have not been tested, and the repository marks both VERIFY-NEEDED. It checks once, in its first phase, by capability rather than by product name: the tools the session actually exposes decide, so a host that gains a subagent tool runs it with no change.

• A tool that spawns a subagent. Without one there are no clones, and bunshin does not run. It says so and steps down to paint. It never plays ten clones in one context: that would be one long session reviewing its own work, which is exactly what the independent lenses exist to avoid.
• A tool that runs a multi-agent workflow script. With it, the five fan-outs run as written. Without it, the same phases run and the clones are spawned by hand, slower, from the exact prompts brief.mjs prints. Claude Code names these two tools Agent and Workflow.
• A structured question tool, for the two gates. Without one, each gate is a single message.
• A browser the session can drive, to harvest a social profile and for the art director’s own look at pages. Clones never use it.
• Permissions. Clones run rsync, ln, find, node, the framework’s binary and a headless Chrome, in parallel, on new paths every time. When the session asks before each command, the summoning gate lists the allow rules the run needs. bunshin never writes them into a settings file itself.

Then one shell call looks for the rest, and the summoning gate says what each missing piece costs before anything is spent, never at phase 8:

The captures come from shoot.mjs, a zero-dependency script in the orchestration module. It opens a headless Chrome over the DevTools protocol and answers every request to a made-up origin from the static build on disk. No dev server runs and no port is fixed: the only socket is the browser’s own DevTools endpoint, on a free port the operating system picks, so nothing collides with a server you are running and every clone can capture at once, each with its own browser. Requests to any other origin go to the network as usual, and nothing outside the build folder is ever served. A shot that fails comes back with its error and does not stop the others. That is why it needs Node 22, for the built-in WebSocket, and a Chrome or Chromium binary.

The module ships one more script, brief.mjs, for a host with a subagent tool and no workflow tool. There the template is the plan, and rebuilding its prompts by hand drifts, so brief.mjs runs the template against stand-in agents and prints every clone it would spawn, in order: its label, its agent type, its schema and its exact prompt. A call made after an earlier answer came back, a synthesis or a plan, is marked, and its prompt is rebuilt with the real answers.

Impeccable leads the direction

Impeccable is a design skill with a command-line tool, by Paul Bakaus, under the Apache 2.0 licence. genjutsu never bundles it and never installs it without a yes. When it is missing, the summoning gate offers this once:

npx impeccable install --project -y

When it is installed, bunshin hands it the two things it does better than anything else in the pipeline: the product interview, and a visual direction drawn rather than defaulted. It also brings its quality floor, its anti-pattern detector, image provenance, and two shipped subagents, a finish reviewer and a documenter.

Product interview

With Impeccable Its init questions and the ones it asks before the draw, batched into the summoning gate.

genjutsu's part The tier question, first.

Direction

With Impeccable Seven worlds ordered before the draw, the draw, challengers judged and their raises taken, a decision page. Always code-led: no comp round.

genjutsu's part An interaction thesis and an Allowed patterns: line on every card.

Contract

With Impeccable surface-brief write.

genjutsu's part The interaction thesis, written into the contract.

Quality floor

With Impeccable Its craft floor, read before any UI edit.

genjutsu's part tells, loaded right after the direction.

Detector

With Impeccable impeccable detect --json.

genjutsu's part The tells audit.

Finish review

With Impeccable Its shipped finish reviewer, spawned fresh by the agent type the host lists. It answers in its own contract: a disposition, then five sections (persistence, fidelity, ceiling, material fixes, keep); a recapture carries only its list. It requires the home page's two captures in .impeccable/review/. When Impeccable is installed but the host does not list that agent type, its degraded role file is passed instead.

genjutsu's part The other lenses, and the plan.

Verdict

With Impeccable The same reviewer, in a verdict pass: every fix of the round scored resolved, partial or unresolved, and at most three regressions named, with no new hunt.

genjutsu's part The cold eyes when the tier calls for them, and the next round's plan, which verdict.js writes from the reviewer's remaining points.

Documentation

With Impeccable Its shipped documenter: DESIGN.md and .impeccable/design.json.

genjutsu's part AGENTS.md, and the final report.

Without it, bunshin still runs and says in the summoning gate that the direction is the weaker path: seven worlds ordered before any choice, three of them carried forward that the category would not publish by default, each shown on a rendered page with its visual thesis, interaction thesis and Allowed patterns: line. The finish review is then a reviewer clone holding the contract, and DESIGN.md is written from the shipped code, never from intentions.

The Impeccable verbs bunshin uses were checked against the Impeccable skill 4.3.1 on 2026-09-30. When the installed version differs, its own files win.

The two gates

Nothing heavier than reading happens before the first answer, and after the second nothing waits for you, except a yes to go past the tier’s round cap. bunshin never opens the preview menu cast and paint start their visual gates with: that would be a third question.

1. Summon. One message, right after the first phase: what bunshin read (how many pages, in which languages, from which sources), the plan, what this host can do (clones in parallel through workflows, clones one by one, or none), whether Impeccable is there, whether captures will work, the stack, and, when there is no project yet, the exact command that scaffolds it and the packages it installs. Your answer to the tier covers that install and nothing else. Then the cost of each tier, and the allow rules the run needs when the session asks before each command. Then up to four questions in one structured call: the tier first, with standard marked as recommended, then the product questions that change the work the most. With Impeccable those are its init questions and the ones it asks before the draw; without it, paint’s brainstorm domains. What the four questions leave open becomes an assumption, written in PRODUCT.md and in the final report.

2. Direction. The visual directions come back as cards, and every card carries genjutsu’s interaction thesis (timing range, hover, scroll, forbidden patterns) and its Allowed patterns: line inside a field the page shows. Choosing one card validates both theses at once. With Impeccable the cards are served on a local decision page, and that page is the preview. The same question goes through the structured question tool only when the page cannot run here or was closed unanswered, never in a second channel while the page is open. Without Impeccable, the cards are shown on a rendered page, announced in one line. The guessability test holds for every card: a direction that could be written from the product category alone is the category’s default, not a direction.

Once more, only past the cap. When the loop reaches the tier’s round cap with more than minor points left, going on needs your yes, with the table of what is left in front of you. Below the cap, nothing is asked.

Commits, pushes and deploys happen only when you ask for them.

The tiers, and what they cost

The tier is the first question of the summoning gate, because it is the budget.

standard is the one the gate marks as recommended. The tiers differ in two more ways:

• Lenses. lean reviews through three, finish, mobile and truth-tech, which merges truth and tech; standard and full use all five.
• Cold eyes. standard runs them in round 1’s verdict, so that round 2 applies their decisions; full runs them at every verdict; lean never does.

Where the figures come from. One measured run: a seven-page site in two languages, built from a professional’s social profile, with two human touches. It spent about 10.5M subagent tokens, as the host reported them, over six to eight hours, with one review, three refine rounds (one from the review, two from decisions files) and two verdicts. The main session’s own tokens were not measured, so no figure on this page includes them. The tiers are estimates built from that run’s per-unit costs, not a benchmark, and bunshin says where they come from every time it quotes them.

They scale with the number of pages. Per unit, from the same run: research about 0.6M; about 0.4M per page clone (2.3M for six); a five-lens review with its plan about 1.6M; a refine round from a plan about 1.6M, with eight owners; a refine round that applies a decisions file about 1.75M; a verdict with cold eyes about 0.35M; the documenter about 0.2M. Two units were not measured and are estimates: a three-lens review with its plan, about 1.1M, and a verdict without cold eyes, about half of one with them.

bunshin announces the estimate before the first clone, from your page count and the tier, plus the main session’s own tokens, which it cannot count in advance. After each workflow it notes how many agents ran and, when the host reports it, the tokens. It never passes the tier’s round cap without asking you, with the table of what is left in front of you. In a session with nobody answering, it spends nothing unless the request names a tier: see below.

The pipeline

Twelve phases, numbered from zero the way the skill numbers them. Four of them fan out to clones. The others are the art director’s, and two of those are the gates where it waits for you.

0. Read

The stack scan cast and paint run, then the brief, and a skim of every source it names (the profile, the current site, the documents) without harvesting yet. The capability check above. The size of the job: pages or screens, languages, audiences, the main channel. This is where a request smaller than a site steps down. It ends with a declared read, in one line: what it is, for whom, heading toward which direction, on which stack.

1. Summon

The first gate. Once you have answered, bunshin adds .bunshin/ to your .gitignore, writes the run’s settings to .bunshin/run.json, and loads the orchestration module. With Impeccable, it runs Impeccable’s context once, from the project root.

2. Harvest

The client’s real material: their own images at full resolution, their texts, contact sheets it actually reads, a palette sampled from the key images, the facts with their sources, and the list of what is missing. Only what the client owns and agreed to use, for their own site. Never another business’s photos, never a stock look-alike passed off as theirs. Prices, testimonials, numbers and legal details the material does not state go on the missing list and stay generic on the page.

3. Research

Four clones, then a synthesis. The four run in parallel, one per angle: direct competitors, the premium end and the design references, the adjacent offer or the second audience, and the path from the main channel to a request on a phone. Each one reads real pages and names the site behind every claim. Then one more clone writes the synthesis, and the art director reads it and writes PRODUCT.md: confirmed facts only, and a section of what must never be invented.

4. Direction

The second gate, and the contract that comes out of it: thesis, own world, story, first viewport, form, finish, the interaction thesis and the allowed patterns. Every clone and every reviewer holds the work against this file. Right after it, tells loads with its web reference, so the type chosen next has the reflexes it must rule out in front of it.

5. Material

Chosen by evidence, not by reflex. Type specimens set in a real miniature of the layout, with the project’s own words, captured and compared as images rather than as names. Photographs trimmed and cropped. A round object seen from above can become a cutout, but only one fitted to the object’s own edge, and checked on a light and a dark ground. Provenance on every image.

6. Foundation

The art director’s, never a clone’s. It loads motion-principles, mobile-principles, desktop-principles, design-audit and the modules the stack calls for, each in a call of its own, then builds:

• The scaffold, when there is no project yet. By then the root is not empty (it holds .claude/, .bunshin/, PRODUCT.md and .gitignore), and scaffolders refuse, redirect or offer to empty a folder that is not. So the command the summoning named runs without its install step in a scratch folder, and is merged into the root with rsync -a --ignore-existing, which never overwrites a file already there. The scaffold’s .gitignore lines are appended to the root’s, the named packages are installed in the root with the package manager, the only place it ever runs, and one build prints exit code 0 before anything else.
• The tokens, and the content model: every visible text, in every language, in typed content files and never in the views.
• The shared components, and every route of every page in every language, each linked from the header and rendering its page with an empty content file, so each clone’s page builds and captures from its first run.
• The signature surface: the home page and its one signature interaction. It captures that surface, fixes what the capture shows, and captures it again.

A site with no build step is supported: plain HTML and CSS, with the build passed as build.cmd: 'true', build.static: '.' and build.link: []. Each page’s HTML file is then its view and holds its own copy, so the content-model rule cannot apply, and the report says so. The header and footer are written once in the home page and copied verbatim into every route file before the fan-out; a change to them is a shared change, applied to every page.

Then it writes the owner map: one owner per page, with its view, its content file and its own components folder, and one owner, shared, for everything more than one page uses, the route files included.

7. Clones

One clone per page, in parallel, each with a brief in six parts: who it is and what it builds, what to read first by absolute path, the exact files it owns, the rules that do not move, how it verifies, and the shape of what it returns. A clone never edits a shared file; a shared need comes back as a request, which the art director applies. Each one builds in a copy of the project outside it, with the framework’s own binary and never the package manager, reads the exit code the build printed, and captures its own page from that copy before it returns.

8. Prove

Before anyone reviews: the build, the type check, impeccable detect when installed, the tells audit, and a grep for the em dash unless the thesis allows it. Captures of every page and every language at 390x664, 390x844, 1280x720 and 1440x900, first screens and full pages in segments. With Impeccable, two more shots of the home page, the ones its finish reviewer requires: the full page at 1440x900 and at 390x664, unsegmented, written straight to .impeccable/review/desktop.png and mobile.png, and shot again at every prove, because its verdict pass reads those exact paths. Scripted tests of the paths that sell (the menu, the sticky bar, a selection carried into the form, each form step, the endpoint failing and succeeding), each reported with the value it measured. What is broken is fixed first: five lenses spent on a broken build are five lenses wasted. What passed goes to the reviewers as already verified.

9. Review

Once, before the first round. One clone per lens, each with the same evidence and none of the others’ reviews: finish (the render against the request and the contract), mobile, desktop, truth (every claim against the sources) and tech (headings, forms, keyboard, computed contrast, metadata, page weight). The lean tier merges truth and tech and drops desktop. With Impeccable, the finish lens is its shipped finish reviewer, spawned by the agent type the host lists and answering in its own contract: a disposition, then five sections (persistence, fidelity, ceiling, material fixes, keep), and a recapture carries only its list. When Impeccable is installed but the host does not list that agent type, its degraded role file is passed as finishRole instead, and the report says so. Then a plan clone, the only one that sees every review, deduplicates, checks each finding against the code and the captures, rejects with a reason, groups the fixes by owner and writes the plan to disk. On a recapture or a rebuild, no plan is drawn.

The finish reviewer’s disposition is read first. recapture: the evidence failed, not the build, so the pages are captured again and the review runs again, and that round does not count. rebuild: the art director rebuilds the regions it names, then a full review runs again, and the round counts as one of the tier’s refine rounds. fix or ship: the plan stands, and before the first round the art director applies, itself, the fixes on files no owner holds.

10. Refine

The loop, one round at a time:

1. Refine. The shared owner applies its fixes first and alone when it has any, then every other owner in parallel, each reading its fixes from the plan on disk. Round 1 applies the review’s plan. Every later round applies the plan the last verdict wrote from the finish reviewer’s remaining points, and the rules of the last decisions file.
2. Prove. The checks again, and new captures.
3. Verdict. The finish reviewer scores every fix of the round: resolved, partial or unresolved, and at most three regressions the fixes introduced, with no new hunt (without Impeccable, a fix can also be marked not verifiable). It gives each remaining point a priority and an owner, and verdict.js writes the next round’s plan from them, with an empty fixes list when nothing is left, so a round that applies a decisions file alone still has a plan to read. When the tier says so, a cold-eyes art director sees the site for the first time, with no review, no plan and no history, and says in at most eight points what still looks amateur or like a template.
4. Decisions. The art director turns those notes into decisions, never into tasks: rules the next round applies everywhere, written in .bunshin/decisions/. A list of eight tasks fixes eight spots; a rule fixes the pattern that produced them. In the measured run, the cold eyes’ notes led to the two decision rounds that closed the build.

Then the stop rule, the finish reviewer’s disposition first: recapture means capture again and rerun the verdict, and nothing the invalid pass said binds; rebuild sends the run back to a full review. Otherwise the loop stops on a rule, never on a feeling: when nothing above minor is left, when the tier’s round cap is reached, or when a round fixed nothing and the same critical or major points come back. Minor points left after the last round go into the report, not into one more round.

11. Seal

DESIGN.md, written by Impeccable’s documenter or, without it, from the shipped code. An AGENTS.md for the AI that will maintain the site, in the client’s language, with a CLAUDE.md pointing to it: where each kind of change is made, the design rules, the writing rules, the commands, what to check before pushing. A launch guard: a build-time warning that lists every fact still missing, with a strict mode that fails the production build. The full audit, over the whole project. And the final report.

What lands where

In your project: the site, with its tokens, its typed content files and its shared components; PRODUCT.md; the direction contract (through Impeccable’s surface-brief write when it is installed); DESIGN.md; AGENTS.md and CLAUDE.md; the launch guard; and a .bunshin/ line in .gitignore. With Impeccable, also .impeccable/design.json and the two captures its finish reviewer reads, in .impeccable/review/.

In .bunshin/, everything the run writes that is not the site:

Outside your project: the isolated build copies, in the session’s scratch directory or under ${TMPDIR:-/tmp}/bunshin-<project>/.

The final report says, in order: what was built, what was verified and with which evidence, what was not verified, the minor points left by page, every fact the client still has to supply, the cost (the tier, the rounds, the agents per workflow, the tokens when reported), the assumptions, and the modules loaded and not loaded.

How cast and paint propose it

cast and paint carry the same short passage. Right after the stack scan, and before anything else they would ask, they propose bunshin once when all three of these hold: the target is a whole site or web app, several pages or screens, from scratch or as a full redesign; the stack is web, or there is no project yet; and the session can spawn subagents, through a subagent tool or a multi-agent workflow tool. And at least one of these four: there is real material to harvest, the site serves two audiences or two languages, it is a first version meant for a client or a stakeholder, or the request asks for the full treatment.

The proposal is one message: what bunshin does, down to the loop that reviews and refines the pages until only minor issues remain, the round cap of the tier you pick is reached, or a round fixes nothing; whether Impeccable is installed; the two times it will ask you; and the cost: one run measured on a seven-page site, about 10.5M subagent tokens over six to eight hours, and tiers estimated from it at about 6 to about 13 million, scaling with the pages. Say bunshin and the pipeline switches. Say anything else and it carries on, and does not propose it again in that session.

When nobody is there to answer

A tier is a budget, and in a session with no human nobody agreed to one. So a headless bunshin goes past its first phase only when the request itself names a tier, and that answer stands. Without one, it stops after reading the project, prints the summoning message as its final report, and spawns nothing: it spends nothing.

When a named tier lets it run, the scaffold is the stack the scan finds, or the one the request names when it also says installs are allowed; otherwise plain static HTML and CSS with no install, the site with no build step described under Foundation. The direction is the card the draw assigned, taken without serving the decision page, or without Impeccable the first of the three worlds carried forward. An Impeccable that is not installed stays not installed, and nothing beyond the scaffold is installed either. Every gate answer is marked UNVALIDATED in the report, and everything else in the pipeline runs: a headless run skips the waiting, never the work.

cast and paint do not propose and wait in that case either. They say in one line that bunshin would fit the brief, carry on with their own pipeline, and name bunshin in the final report.

What it does not do

• Native stacks. The evidence harness is web, so on Compose or SwiftUI bunshin says it does not cover native stacks yet and steps down to paint.
• Commits, pushes, deploys. Nothing leaves the machine unasked, including when the site is finished and you look happy.
• Dev servers. It never starts one. Captures come from the static build.
• Installs. No dependency without asking, Impeccable and browser tooling included. The one install your answer to the tier covers is the scaffold the summoning named. With nobody answering, nothing beyond it.
• Inventions. No testimonial, no client, no figure, no price. What the material does not say stays generic on the page, is marked in the content file, and is listed for the client.

If what you want is one page or a visual identity, that is paint. If it is motion on what already exists, cast.