Workstreams
A technical reference for TRW's multi-agent coordination layer — the specialist roster, the four formations, the file-ownership rules that keep parallel work from colliding, and the wave-and-shard model that decides what runs in parallel and what blocks on what.
You will learn
- Why focused role passes outperform one overloaded generalist pass.
- The 12 specialists TRW ships and what each one is scoped to touch.
- The four coordination formations and when to pick each.
- How file ownership is declared and verified.
- How waves and shards decide parallel versus sequential execution.
- How to adapt workstreams to your current client surface.
What workstreams solves
One agent trying to do everything produces worse output. Split attention across research, implementation, and review degrades each of them. A focused specialist reading a narrow slice of the codebase finds more relevant signal than a generalist reading everything while also writing code. Specialization is the lever — and the lever works the same way for language models as it does for humans.
TRW's workstream layer makes specialization operational. Each role has a declared responsibility, file scope, and handoff. The orchestrator composes those roles into a formation that matches the work. Parallel execution becomes safe only when conflicts are prevented at declaration time; sequential execution uses the same contracts without requiring helper spawning.
The 12 specialists
Full agent definitions live in the agent roster; this table is the quick-reference of who does what.
| Agent | Role | Best for |
|---|---|---|
| trw-lead | Orchestrator with no file writes of its own. | Planning and delegating across a multi-agent run. |
| trw-implementer | Production code author. | Writing the src/** changes that satisfy the plan. |
| trw-tester | Test authoring only. | Producing tests/** that cover the implementer's diff. |
| trw-reviewer | Read-only diff review. | Structural review of the change before audit. |
| trw-researcher | Context gathering, read-only. | Reading the codebase and surfacing relevant priors. |
| trw-adversarial-auditor | Spec-vs-code audit, read-only. | Breaking confirmation bias with an independent audit. |
| trw-prd-groomer | PRD drafting and grooming. | Turning a feature brief into a sprint-ready PRD. |
| trw-requirement-writer | Functional requirement authoring. | Writing EARS-style functional requirements. |
| trw-requirement-reviewer | FR review and quality gate. | Validating requirements before execution plans. |
| trw-traceability-checker | FR to code to test link checker. | grep-verifying that each requirement has code and tests. |
| trw-code-simplifier | Refactoring only, no new features. | DRY and clarity passes after an implementation wave. |
| trw-auditor | Post-hoc compliance audit. | Spec and ceremony compliance after delivery. |
Formations
A formation is the topology of a workstream — not whether to spawn helpers, but how roles relate to each other. TRW ships four formations. The orchestrator picks one based on the shape of the work, then executes it either sequentially or with client-supported helpers.
Pipeline
Sequential stages with clean handoffs. Each agent completes before the next begins. Use when every stage depends on the previous output and cannot start early — the default for most feature implementations.
Map-reduce
A researcher fans out to parallel shards that read independent axes of the codebase, then results merge into a single implementer. Use when the reading can be parallelized and the outputs have a single downstream consumer — reduces wall-clock time on large codebases.
Planner-executor-reflector
A three-node triangle: the planner defines work, the executor implements it, the reflector reads the diff and feeds observations back to the planner before the next wave. Use when iterative design matters more than raw throughput.
Debate-critic-judge
Two implementers propose competing approaches. An adversarial critic probes both. A judge delivers the verdict. Use when correctness matters more than speed — it is expensive, and the evidence it produces justifies the cost for quality-critical decisions.
File ownership
Every workstream role declares its file scope as a set of glob patterns before work begins. When hooks are available, writes outside the declared scope can be rejected before the filesystem is touched. Without hooks, the same ownership table still gives the primary agent, reviewer, and human operator an explicit contract to check.
A typical split: trw-implementer owns src/module.* and trw-tester owns tests/test_module.*. Both run in the same wave. Neither can write to the other's scope. The same model works for any language — scopes are glob patterns, not language rules.
Waves and shards
Work decomposes into two nested units. A wave is a sequential boundary: wave 2 cannot begin until wave 1 exits. A shard is a parallel unit within a wave: shards in the same wave run concurrently. This is the knob that decides what waits and what races.
The orchestrator writes a wave manifest before execution, and each shard writes its findings back before the next boundary. Wave 1 typically handles foundation work, wave 2 handles integration, and a final serial wave synthesizes the outputs. Parallelism, when supported, lives inside each wave; ordering lives between them.
Running workstreams per client
Workstreams adapt to the client surface you actually have. A capable client can map a workstream to an explicit helper or subagent. A simpler client runs the same role plan sequentially. In both modes, the stable requirements are file ownership, project-native validation, checkpointed handoffs, and a final review before delivery.
Workstream execution mode
# Claude Code
# Use installed agents/hooks when present.
# Spawn helpers only through currently supported client primitives.
# Otherwise execute the workstream roles sequentially.Next steps