Delegate: you steer, flash workers do the reading and writing

The point of this plugin is to spend a cheap model's tokens instead of yours. So: no Claude subagents (no Explore, no forks, no /code-review) for anything a flash worker can do — mapping a codebase, porting tests, implementing a slice, reviewing a diff. You keep architecture, acceptance, verification and judgement. Everything else goes out.

1. What a worker is

• A DeepSeek Flash worker is a mid-tier thinking model, and it is more capable than "flash" suggests. Measured on a 50k-line Swift app (2026-09-17): a 1,250-line provider seam with a fake, 15 tests and three re-pointed scripts in 30 min; an 11-finding security fix round, each finding with a fail-before/pass-after test, in 40 min; a 1,500-line harness rework with 29 tests in 37 min; a 7,000-line file split into 16 files with 41 grep-based scripts re-pointed (it hit the hour budget, and the salvaged patch was complete). It reports honestly — real command output, real counts, a "caveats" section that is where the information is.
• What it reliably gets wrong, and therefore what your review must read: flow semantics across a boundary (an OAuth callback that carried the server's decline was treated as noise and left the command waiting for its timeout), policy nuance (an allow-list redactor blanked the one string that explains a failure), warnings outside its own files, and checks that go stale when a second code path appears next to the one a script greps for. Its diff is right; its model of the whole is not. Read the core of a slice — the state machine, the auth flow, the classification switch — yourself, every time.
• It degrades when one session carries many separate points: one coherent goal with up to about six numbered sub-goals works; a checklist of twenty does not. A task text of 800–1,500 words is the working range.
• Every call starts with zero context. The task text is all it knows.
• A writing call runs in a disposable copy of the repository (uncommitted work included) and returns a patch. Nothing reaches the tree until flash_apply. Its summary of what it did is not evidence; the diff and your own verification are. The result lists the uncommitted files the copy started with (isolation.uncommittedAtStart); when another session has work in progress in the same tree, source: "head" starts the copy from the last commit instead.
• Project facts every task would repeat (layout, check commands, style rules) belong in the repository's AGENTS.md or CLAUDE.md: the harness loads it into every worker, up to 64 KB (the most specific files first; the rest is cut). Keep task text for the slice — but repeat the project's hard rules (no silent defaults, no unsafe, …) in the task's checklist: a long instructions file alone does not make them stick.
• It builds exactly the brief, gaps included. A slice built faithfully from a design note with a hole in it ships the hole, well tested. Review the design a brief carries before it goes out, not only the result after.
• The service root is fixed at the project; cwd selects a directory inside it.

Choosing a model

Leave model off for the installed default: it suits a quick hand-off. To run a slice on another model, pass model from the user's allowlist on flash_task, or once on flash_batch for the whole fleet — a per-task model is refused, because one fleet is one process. Read the result's route: it is the model that actually ran, and a mismatch arrives as a warning rather than a silent success. Comparing models on the same kind of task — same brief, same acceptance — is how you learn which suits that kind of work. A model the user did not allow is refused, and so is a non-default model while the installed profile predates 0.1.6; the error says to rerun the setup.

2. The loop

1. Frame. Read what you must to own the design (the docs, the seams a slice will touch — a few hundred lines, not the codebase). Write the decisions down where a worker can read them (a design doc in the repo is ideal). If the goal needs a map of the code first, that map is a read-only worker task, not an Explore agent.
2. Slice. Cut the goal into slices with one unambiguous "done" each. A slice is a coherent unit of behaviour with its tests, not a file list. Order them by dependency; slices that share files run one after another.
3. Dispatch. One flash_task per slice, or one flash_batch for slices that touch disjoint files (§4). Write the task with the template in §3.
4. Verify yourself. Apply the patch to the working tree (it stays uncommitted), then run the project's real gates: the full test suite, the wiring/invariant scripts, a build of every target, the mutation controls where the project has them. Read the diff — all of it, and the semantic core twice (§1). When change.diffTruncated is true, read the rest with flash_patch (by file or by page) before applying. A patch that no longer applies because a file moved meanwhile takes flash_apply with threeWay: true; it merges without touching the index and names any conflicts, keeps each file's line endings, and either writes nothing when it fails or names every file it already wrote. To land only part of a patch, pass files with names from change.filesChanged (a rename by its old or its new path): each file is recorded as it lands, so the rest can follow later, and a whole apply after a partial one is refused with the count unless you pass force: true. flash_apply and flash_patch report drift (commitsBehind, and filesChangedSince: the patch's own files you changed in the tree since the copy was made), and an apply that would delete or rename away one of those files is refused unless you pass threeWay: true (merges and keeps the edit, marking conflicts) or force: true (discards it). A worker that reports green has still only tested its copy, and "no warnings in the files I created" says nothing about the files it changed.
5. Review independently. Send the diff to a read-only worker with the review template (§5). A read-only worker cannot build or run tests — both write. When the review must, send it as a writing call with apply: "none" (the default): it runs in a throwaway copy and stores its change as a patch, so its proof tests survive. Read them with flash_patch, then flash_apply with files naming only the test files — they become the fix round's failing-first tests. Use apply: "discard" when nothing is to be kept. Merge its findings with yours; keep only what you can confirm from the code.
6. Fix round. One task carrying every confirmed defect, each with "add a test that fails before and passes after". Apply, verify, review again. Stop when a review pass finds nothing real. Expect one to two rounds; three means the slice was framed badly — reframe it.
7. Commit only when the user asks, in the repository's own voice.

3. Writing a task

<Language/toolchain, targets, test framework and its idiom, one line.> Work only in <the files or
modules this slice owns>. Do not touch <what it must not>. No git commits. Read <files> completely
first.

# Goal
<One or two paragraphs: what exists today and why it falls short, what must be true afterwards,
and the rules that must hold (the invariants, the compatibility that matters, the design
decisions already taken). Point at the design doc for the rest.>

# What to build
<The shape in prose plus, where an API is a contract, the Swift/TS signatures. Give latitude on
implementation; be exact on behaviour and on names other slices will call.>

# Tests
<Which suites to extend or add, and the behaviours that must be pinned. "A test that fails before
and passes after" for every defect being fixed.>

# Build and verification
<The exact commands, in order. The worker must run them and paste their output.>

Reply with: files changed (one line each); the public API added or changed as signatures; the
verbatim output of every verification command; anything you deviated from, and why.

Rules that held up:

• One goal per task. Related fixes go in one task; unrelated goals do not. A fix round with ten findings is one goal ("make these ten things true, each with a test"); a feature plus a refactor plus a doc rewrite is three.
• Decide the architecture in the task, not in the worker. Give the protocol signatures, the type names other slices will call, the contract each type must express, and the mapping rules (which error becomes which case, and why). The worker implements a decision well and invents one badly.
• Name what it must not touch — including files a sibling in the same batch owns.
• Name the helpers to reuse. A worker that is not told about the shared parser or lookup function writes its own beside it: in one night, four of eleven patches carried a copy of an existing helper. "Use parse_header in src/wire.rs; do not write another" stops it.
• Keep input files inside the repository. A worker cannot read a file in your session's /tmp or elsewhere outside the root: write it into an ignored folder of the repository and name that path. flash_task warns when a brief names an existing file outside the root.
• Give the verification recipe, not just "run the tests". Compiled projects: cloned build state carries absolute paths and is unusable in a copy. For SwiftPM, point a cache: folder at the scratch path in the repository's .flash-agents.json — "slotEnv": { "SWIFT_SCRATCH": "cache:swift-build" } — and build with swift build --scratch-path "$SWIFT_SCRATCH" --disable-sandbox, and the same for swift test. Each slot then builds incrementally, and since 0.1.12 keeps that path across restarts, so the recipe does not remove .build. A repository without that setting removes the cloned build state first (rm -rf .build as the task's first step) or uses a scratch build directory inside the copy. Toolchains with a sandbox of their own cannot start it inside the worker's sandbox: SwiftPM needs --disable-sandbox on every swift build/swift test, or the worker reports Operation not permitted and cannot verify anything. A cold build in the copy is usually seconds to a minute. Where it is not (a large Rust workspace), the repository's .flash-agents.json can leave target/ out of the copy and keep a warm per-slot one instead ("slotEnv": { "CARGO_TARGET_DIR": "cache:cargo-target" }), and give tools that write to the home folder a writable one (see the README's per-repository settings). A setting the whole project shares — RUSTC_WRAPPER — belongs there too as "NAME": "value:<text>", not repeated in every brief; a path only one machine has, such as a prebuilt OpenSSL, belongs in a git-ignored .flash-agents.local.json beside it, under platform.<name> when it is that platform's business. A project whose tests need an environment built inside the copy (a Python venv with editable installs, node_modules) can have it built once per slot with slotSetup; ask the user before enabling it, because those commands run outside the sandbox. An edit to either settings file applies from the next writing call, with no reconnect; a call already running keeps the settings it started with. Keep the recipe in project memory so every task carries it verbatim.
• Ask for verbatim output and for a "deviations" section. Workers use both honestly; that is where the real information is. Every worker is already told to say first when it built a different interface than the task names, to report a contract that looks wrong instead of working around it, to say why it stopped when it stops early, and to list any change beside a rule the task states ("only here", "never that") under a "Rules crossed" heading — read that section first. On Windows it is also told that its commands run in PowerShell, not bash.
• Make the tests go through the real entry point. A test of a security rule must enter where real input enters: one worker "tested" that an agent key cannot send a reviewed post by passing the sender's kind into the store by hand, so the receive path that labelled every sender a person was never run. Ask for that explicitly.
• Ask for real-shaped test data: real id lengths, many items, real sizes. Short made-up ids let a 64-character limit and a 50-character LIKE pattern pass every test and fail in production. Add "no cap, prefix or truncation unless the task asks for one" — workers reach for them (a copy count capped at 99, folders named by an 8-character id prefix).
• When two slices share a contract built in parallel, tell both: "if the contract looks wrong, report it and stop that part". Otherwise each works around the flaw its own way and the two sides stop matching.
• Send a long brief with taskFile, not pasted: write it to a file inside the repository and pass the path. Never pass shell syntax such as $(cat brief.md) as the task — the worker gets that literal text.
• Use acceptance for the one-sentence definition of done; the body carries the how.

4. flash_task versus flash_batch

• A batch is one call, one shared copy, one patch: its members see each other's edits. Batch only slices whose files are disjoint, and tell each member which files the others own. A member's full-suite run may compile a sibling's half-written file and fail once; the worker re-runs, and your own verification on the tree is what counts.
• Coupled slices go sequentially, each applied before the next is dispatched.
• Two flash_task calls in parallel is the other shape: each gets its own copy and its own patch, so two slices on disjoint files can run at once (the service has two slots). A copy is taken from the working tree at dispatch, uncommitted work included. Apply the patches in either order; a commit in between does not matter as long as the files are disjoint. Keep a note of which files each running worker owns so the next task you write does not touch them.
• Read-only work (maps, reviews) uses mode: "read-only"; it cannot change anything and needs no patch. It runs in your live tree, not a copy, so it sees edits that land while it reads: do not apply patches under a review that is still reading them.
• background: true returns a job id at once. Use it when there is something to do meanwhile — verifying the previous patch, writing the next task — and collect with flash_result (waitSeconds: 300 per wait); flash_cancel stops a call whose framing turned out wrong. Prefer it for writing calls when copies may be busy: a foreground one that has to wait for a free copy holds your whole turn, and says so while it waits and in its warnings. A queued job's flash_status has queue (position, of, and the holders of the trees, first come, first served), so you can see which job to wait for or cancel. When a job runs long, flash_status says what its workers are doing — current lists each open tool call (command, runningMs) and warnings names a command that has failed three times the same way with no file changed in between (exit 1 from grep, rg, diff or cmp is not a failure, and the line says when a later run succeeded), or one rerun with ever new arguments for twenty minutes. child.treeCpuSeconds is the CPU of a command's whole tree: a cargo test at 0 s with a large tree figure is working, not stuck.
• A misspelt argument is refused with the nearest known name, and so are provider, reasoningEffort, agentOptions, permissions and sandbox: fix the call rather than dropping the field.

5. The review task

Send it read-only with the diff obtainable in place (git status --short, git diff, cat for untracked files) and the design it implements. Ask, in priority order, for: correctness defects on inputs the tests do not cover (name the classes: encodings, line endings, empty and oversized values, duplicates, ordering of columns/bindings, rules that can lose a person's edit); behaviour changes for existing callers (have it grep the call sites and say whether each still behaves); assertions that do not match the code. Require file:line, a triggering input, and a confidence (confirmed by tracing the path / plausible), and an explicit "none found" per category. No style remarks. Then confirm each finding yourself before it enters a fix round.

When the review should arrive with proof, ask for one failing test per finding and run it as a writing call with apply: "none" (the default) — a read-only call cannot write a test file. The patch that comes back is the evidence: read it with flash_patch, then flash_apply it with files naming only those test files. They fail against today's code, which is exactly what the fix round's "fails before and passes after" needs, and the fix round then makes them pass. Keep apply: "discard" for a review whose change is only read, never kept.

6. Budgets and what to expect

• Per-task and per-fleet budgets are in flash.config.json (three hours each by default, and ten minutes without any activity stops a stuck call). A timed-out call still stores the change so far as a patch and names the refusals it saw; the tree it used is retired, never recycled, but its warm build cache (cache: folders) moves to the replacement tree, so a retry does not build from cold. isolation.buildCacheEmpty: true says a call started with an empty cache.
• timing in every result breaks the call down in milliseconds — queuedMs, prepareMs, setupMs, workerMs, collectMs, totalMs — so a slow one shows whether it waited, copied, set up, ran or was collected. queuedMs is 0 when there was no wait; a phase that did not run is absent.
• flash_result takes jobIds (2 to 16) as well as jobId: it returns the first that ends and names the rest under pending; when another id answers, an id with no job and no stored report is listed under unknown.
• flash_apply and flash_patch take excludeBase: true on a patch that continued from a base patch: only that call's own work is read or applied, not the base patch's change as well.
• Run at most about four workers that compile at once on a 12-core machine; read-only work can run beside them.
• A slice of a few hundred lines with tests typically returns in two to six minutes; a coherent feature slice of 1,000–1,500 lines with tests in thirty to forty; a fix round of ten findings in thirty to forty. A large mechanical job (a multi-thousand-line split with scripts to re-point) can hit the hour: the salvaged patch is still complete, but take it only after checking for transient artefacts — a snapshot taken while the worker's own mutation-controls run had a file mutated carried that mutation into the patch once.
• In Claude Code the call moves to the background after two minutes and the result arrives as a task notification; keep steering (write the next task, review the previous patch) rather than waiting. The idle abort at 30 minutes is covered by progress notifications and the plugin's own timeout, but a long call still needs the server reconnected after any plugin edit.
• NOT_DELEGATED: the dispatcher did the work itself instead of delegating; re-run the call.
• A worker that stopped partway (it says why, first) left a good start: send the next task with basePatch: <that patchId> and say what is left. The copy starts with that change already applied, and the new patch is cumulative — apply it instead of the old one, never both. The exception: when you already applied the base patch to the tree, it is not applied again, the result warns and basePatch.alreadyInTree is true, and the new patch holds only the new work — apply it on top of the base. To start workers from a branch in another worktree, write its git diff --full-index into an ignored folder of the root and pass it as basePatchFile: each patch then holds only that worker's change. An id can be quoted short: flash_apply, flash_patch and basePatch take any unique prefix of at least eight hex digits, with or without flash-, and refuse an ambiguous one with the matches named.
• emptyResult: true with status: "error": the worker ended without a report and without a change. Treat it as failed and send the task again.
• finalMessageProblem: "tool-call-markup" (or "empty") with status: "error": the worker wrote its next tool call as text and the run ended there, so that call never ran. Its patch holds the work so far: check it and continue with basePatch; do not trust the checks it reports.
• Pass label with a short title when briefs start with the same shared rules, so the jobs differ in flash_status. A flash_status warning that a command used no CPU for minutes usually means it waits forever (ninja on Windows); current[].child names what it is waiting in.
• overlaps on a writing result names other unapplied patches that touch the same files: decide which one wins before applying either. hunks shows where they meet (disjointHunks: true: they share a file but no lines, so a three-way apply of the second will most likely be clean), and a flash_apply with dryRun lists the same before anything is written.
• Refusals appear in the result's denials and in the log with their reason; a worker that hit the wall says so in its reply.
• The result's change.diff is clipped at a file boundary when it is long; change.diffOmitted names the files left out, change.patchPath is the full patch on disk, and flash_patch reads it. flash_apply always uses the stored full patch.
• usage in every result is the call's token count (inputTokens, outputTokens, modelCalls; cache hits are separate, in cacheReadTokens), for weighing a delegation against doing the work yourself.
• A read-only worker is a good security reviewer of a bounded surface: given an OAuth/MCP client and RFC citations it returned eleven real findings in one pass. It is not a substitute for your own read of the same surface; the two lists differ, and both matter.
• After editing this plugin's own lib/, reconnect the server (/mcp reconnect plugin:flash-agents:flash); a running one keeps the old code.

7. What stays with you

Design decisions, the acceptance bar, reading the diff, running the gates, the judgement on findings, the commit. If you find yourself delegating a design decision, stop and decide it.