Subagents, Built Live: Reviewer, Tester, Researcher, Doc Writer
The video version of this article, "Subagents, Built Live: Reviewer, Tester, Researcher, Doc Writer," goes public on YouTube on Friday, November 20, 2026, and shows all four configs written live in a real repo. This article is the written version, laid out so you can copy the structure.
A subagent is a job description, not a personality
Most people create a subagent by writing a personality. Friendly. Helpful. Expert at everything. Then they give it every tool in the box and wonder why it drifts, edits files it should only have read, and reports success nobody can check. That is a coworker with no job description and a master key.
A subagent is not a second generalist. It is a narrow brief with permissions attached: one job, a defined set of files it may read or write, a fixed report shape, and a list of things it must never do. The personality is irrelevant. The boundaries are the product.
This article builds four of them on the demo project from the earlier videos: a reviewer, a test writer, a researcher, and a doc writer.
1. The anatomy: five parts, same every time
- Role. One job in one sentence, plus when to use it and when not to.
- Inputs. The packet: goal, files to read, the diff or the spec, the exact verification command.
- Tools and permissions. What it may read, write, and run.
- Output format. A fixed report shape, checkable in under a minute.
- The never do list. Blunt prohibitions, specific to that role.
Permissions are what separate roles, not tone of voice. If two subagents can both edit everything, you do not have roles. You have copies.
Two rules sit underneath all four configs. The reviewer is read only. And the one writer rule: exactly one agent has write access to a given file at a time, so subagents that need the same file run in sequence, never in parallel.
2. The reviewer: read only on purpose
The reviewer's job, in one sentence: check a finished diff against the original packet and the repo rules, and report what is wrong.
Its packet has four fields: the original packet, the diff, the files changed, and the test command, from the repo rules file, not invented on the spot.
Its permissions are the whole design. Read any file. Run the test suite and read the output. Write nothing. No edits, no formatting fixes, no helpful little commits. Its report: findings first, by severity, each naming the file, what is wrong, and the evidence. Then what it checked, what it did not check, and a verdict: accept, or send back. Never do: never fix a finding yourself, never soften one to be polite, never approve work you did not read, never edit tests.
3. The test writer: writes only in tests
The test writer's job: write tests for a stated behavior, from the spec in its packet. Tests only. Never the implementation.
Its packet: the behavior spec with examples, the function signature, and the existing test file to copy style from. Permissions: write only in tests, only the file named in the packet. Read the app code, run the suite, touch no implementation.
In the demo, its new tests fail, because the function under test is still a stub. That failure is the correct result, and its report says so plainly: tests written, command run, real result, cases left out. Never do: never edit a test to match wrong output, never write the implementation to make its own tests pass, never delete or weaken an existing test, never report a skipped test as passing. Tests are the spec.
4. The researcher: writes nothing
The researcher's job: answer one specific question from named sources, and return a short brief the orchestrator can act on.
Its packet is one question in one sentence, the decision that answer will feed, and the sources it may use, official docs first. If the question takes two sentences, it is two packets. Permissions: read only on the repo, plus the named sources. It writes nothing in the repo. Its only product is the brief.
The brief has a fixed shape: the answer in the first two lines, then evidence with each source named, then what it could not confirm, labelled unconfirmed and never guessed at. Never do: never turn a brief into a code change, never present an unconfirmed claim as a fact, never widen the question, never bury the answer. Bulk reading is a cheaper model job, safe only because the format does the disciplining.
5. The doc writer: runs last
The doc writer's job: turn finished, verified work into documentation that matches what the code actually does: a README section, a usage example, a changelog entry.
It runs last, and its packet proves it: the accepted diff, the reviewer verdict, and a usage example that has actually been run. No accepted diff, no docs. Permissions: write only in the documentation files named in its packet, read code and tests freely, run examples, change no code, ever. If code and intended docs disagree, the disagreement goes in its report, not papered over. Its report is the doc change, the example with its real run output, the disagreements list, and what it left out.
Never do: never document a feature that is not in the accepted code, never invent example output, never describe planned behavior in the present tense. The example run is not optional.
6. Four roles, one task
Now the four on one task, in order, with who writes what.
The test writer goes first, writes only the test file, and its tests fail honestly against the stub. Then one worker implements the change in one file. The reviewer goes next and writes nothing: it reads the diff, runs the full suite, and returns findings or a verdict. If a factual question came up, the researcher answers it in a brief; it never enters the code path itself. The doc writer goes last, after acceptance, with an example it ran itself.
At every step you can point at exactly who was allowed to write the file that changed. Fail that pointing test and you do not have subagents. You have a crowd.
The honest failure: the reviewer who fixed it quietly
The pattern to design against is a reviewer with write access. It finds a real problem in a diff. Instead of reporting it, it quietly fixes the code itself, because fixing feels more helpful than reporting.
Three things are lost at once. Nobody learns the worker made the mistake. The fix was never reviewed, because the reviewer checked its own work. And the report says clean, so the record shows a diff that never had a problem. A lie by omission.
You do not fix this with a sterner prompt. You fix it structurally, by taking away the write permission. Read only is the first permission decision in every config here.
Get the Starter Pack
The project templates and orchestration checklist from this series are free in the Multi Agent Starter Pack. The four full subagent configs built in the video are the core of the Multi Agent Coding Ops Kit that launches in December:
- Download it on GitHub: https://github.com/second-shift-dev/multi-agent-starter-pack
- Or get it by email and join the Second Shift Dev list for new videos and the December launch of the full Multi Agent Coding Ops Kit: https://second-shift-dev.kit.com/f1a6475d0f
The video version of this article, "Subagents, Built Live: Reviewer, Tester, Researcher, Doc Writer," goes public Friday, November 20, 2026 on the Second Shift Dev YouTube channel, to watch the four configs built and run live.
The day job ends. The agent team clocks in.
Second Shift Dev
