Docs
Workstreams
Define who owns each responsibility, what evidence crosses the handoff, and what must stay sequential. Use helpers only when the current client and task justify them; the same contract works in one primary session.
Start with the ownership contract
A workstream is a repository-visible plan for dividing responsibility. It is not proof of parallel execution, a requirement to spawn helpers, or a guarantee that specialization improves the result.
Ownership
One role owns each active file scope and deliverable.
Handoff
The next role receives an artifact, evidence, and an explicit decision.
Execution
Run roles sequentially by default; add concurrency only across disjoint scopes.
The 11 bundled roles
Start most implementation work with the five-role core roster. Add a bundled specialist only when the work needs a distinct planning, test, traceability, or simplification boundary.
trw-leadInspect
- Role
- Orchestrator with no file writes of its own.
- Best for
- Planning and delegating across a multi-agent run.
trw-implementerInspect
- Role
- Production code author.
- Best for
- Writing the src/** changes that satisfy the plan.
trw-testerInspect
- Role
- Test authoring only.
- Best for
- Producing tests/** that cover the implementer's diff.
trw-reviewerInspect
- Role
- Read-only diff review.
- Best for
- Structural review of the change before audit.
trw-researcherInspect
- Role
- Context gathering, read-only.
- Best for
- Reading the codebase and surfacing relevant priors.
trw-adversarial-auditorInspect
- Role
- Spec-vs-code audit, read-only.
- Best for
- Breaking confirmation bias with an independent audit.
trw-prd-groomerInspect
- Role
- PRD drafting and grooming.
- Best for
- Turning a feature brief into a sprint-ready PRD.
trw-requirement-writerInspect
- Role
- Functional requirement authoring.
- Best for
- Writing EARS-style functional requirements.
trw-requirement-reviewerInspect
- Role
- FR review and quality gate.
- Best for
- Validating requirements before execution plans.
trw-traceability-checkerInspect
- Role
- FR to code to test link checker.
- Best for
- grep-verifying that each requirement has code and tests.
trw-auditorInspect
- Role
- Post-hoc compliance audit.
- Best for
- Spec and ceremony compliance after delivery.
| 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-auditor | Post-hoc compliance audit. | Spec and ceremony compliance after delivery. |
Formations
A formation describes how responsibilities relate; it does not require helpers. Start with single-track, then add structure only when the task has a real fan-out, pipeline, or contested decision.
01
Single-track
One active owner at a time with explicit handoffs. Use this default when the work is tightly coupled, the scope is small, or concurrent edits would create more coordination than value.
02
Map-reduce
Independent shards inspect separate axes, then a single owner reconciles their outputs. Use only when the scopes are genuinely independent and the merge criteria are explicit.
03
Pipeline
Ordered specialist stages with a defined artifact at every transition. Use when research, implementation, validation, and review depend on the prior stage's completed output.
04
Debate + critic + judge
Competing proposals are challenged and then adjudicated against explicit criteria. Reserve it for consequential decisions where genuine alternatives justify the additional cost.
File ownership
Declare file scope before implementation and keep overlapping paths out of concurrent work. Ownership is a planning and review contract; whether a client can enforce it before a write depends on that client's available, trusted adapters.
A typical split gives src/module.* to an implementer and tests/test_module.* to a tester. They may run in the same wave only when those scopes are disjoint. The same model works across languages because ownership describes repository paths, not language rules.
Waves and shards
A wave is an ordered boundary. A shard is an independently owned unit inside that boundary. A capable harness may run disjoint shards concurrently; another client can execute the same plan sequentially without changing the handoff contract.
Record ownership, dependencies, expected output, and validation for each shard before it starts. Close the wave only after those outputs have been reconciled; do not infer safety from the word “parallel.”
Running workstreams per client
Workstreams adapt to the client surface you actually have. A capable client can map a disjoint role to an explicit helper. A simpler client runs the same role plan sequentially.
Helper-capable
Map disjoint roles to explicit helpers when the user and harness allow it.
Single-session
Execute the same role and handoff sequence locally when helpers are unavailable.
Always required
Preserve ownership, project checks, checkpoints, and review evidence in either mode.