Agents
A single agent holding an entire codebase in context misses things. Focused agents with narrow context windows catch what broad agents miss — 3x fewer P0 defects. TRW ships 12 focused agents, each with a distinct role, scoped tool access, and worktree isolation.
Consolidated from 18 to 5. Fewer agents, sharper scopes, worktree isolation. Upgrading? See migration map below.
How it works
Agent Teams follow a delegation model. The primary agent decomposes work, each specialist operates in isolation via worktrees, and structured messages replace shared state.
- 1
Primary agent decomposes the work
The orchestrating agent reads the sprint plan and PRD execution plans, then creates tasks with explicit file ownership boundaries for each specialist.
- 2
Each agent gets only what it needs
Implementers receive exclusive file sets in separate worktrees. No agent sees another's files. Narrow context means deeper understanding per task.
- 3
Communication via structured messages
Agents exchange interface contracts and completion signals through the task system. No shared mutable state, no merge conflicts.
- 4
Auditor verifies integration
Before delivery, trw-auditor checks that all agent outputs wire together correctly against the PRD acceptance criteria.
> /trw-sprint-team
[Primary] Reading sprint plan: sprint-79.yaml
[Primary] PRDs to implement: PRD-CORE-092, PRD-CORE-094
[Primary] Creating 3 teammate tasks with worktree isolation...
Task 1: impl-092 → trw-implementer
Files: src/agents/, data/agents/
Contract: 5-agent roster, PREDECESSOR_MAP exported
Task 2: audit-092 → trw-auditor
Files: (read-only verification)
Blocked by: Task 1
Task 3: review-094 → trw-reviewer
Files: (read-only review)
Contract: rubric scores for all changed modules
[implementer] Task 1 complete. Build check: PASS (1337 tests, 94% coverage)
[auditor] Task 2 complete. All FRs verified. 0 spec gaps.
[reviewer] Task 3 complete. Rubric scores: correctness 9/10, security 10/10.
[Primary] Integration check: all contracts satisfied.
[Primary] Sprint delivered. 2 PRDs, 0 integration gaps.Info
Model assignment: All 5 specialist agents default to Sonnet for speed and cost efficiency. The primary orchestrating agent uses Opus for strategic decomposition and gate verification. Model assignment is configurable per project.
The 5 agents
Each agent has a single mandate, a defined trigger condition, and worktree isolation for parallel work.
| Agent | Role | When to use | Model |
|---|---|---|---|
| trw-implementer | Code implementation specialist. Writes production code following TDD, honors interface contracts and file ownership boundaries. | Writing production code, TDD, file ownership | Opus |
| trw-researcher | Research and investigation specialist. Explores codebases and the web, gathers evidence, produces structured findings. | Codebase exploration, web research, evidence gathering | Sonnet |
| trw-reviewer | Code review and audit specialist. Read-only, rubric-scored reviews with security auditing. | Rubric-scored reviews, security auditing | Sonnet |
| trw-auditor | Adversarial spec-vs-code auditor. Verifies implementation against PRD acceptance criteria, checks type safety, DRY violations, and error handling. | Spec compliance, type safety, DRY, error handling | Sonnet |
| trw-prd-groomer | PRD drafting and validation specialist. Grooms requirements to sprint-ready quality, manages the full PRD lifecycle. | Requirements engineering, PRD lifecycle | Sonnet |
Formation patterns
Three common team shapes. Pick the smallest formation that covers the work.
Solo + reviewer
One implementer does the work, an independent reviewer catches what they missed. Worktrees keep each agent isolated.
When: Most common. Single-PRD features, refactors, bug fixes that touch 3-10 files.
Parallel implementers
Each implementer gets exclusive file ownership. No shared state, no merge conflicts. The auditor verifies integration seams.
When: Multi-package changes where files have no overlap. API + frontend, or two independent modules.
Full sprint team
Full team with dedicated research, implementation, and review. Each role operates in its own worktree with exclusive file ownership.
When: PRD sprints delivering 2-4 PRDs in parallel. Quality-critical or security-sensitive work.
When to use agent teams
Agent teams add coordination overhead. Use them when the benefits outweigh the cost:
- Multi-file features — changes span 3+ files across different modules or packages
- Parallel PRDs — a sprint delivers 2+ PRDs that can be implemented concurrently
- Quality-critical work — security hardening, API migrations, or anything that benefits from independent review
- Large refactors — splitting a god module, migrating a dependency, or restructuring packages
Warning
When NOT to use teams: For single-file fixes, quick config changes, or edits touching fewer than 3 files, a solo agent session is faster. The coordination overhead of a team outweighs the benefit when there is nothing to parallelize.
Quality gates
Agent teams include automatic enforcement at every stage:
- Teammates are blocked from completing tasks until
trw_build_checkpasses - Idle agents with unfinished tasks get nudged automatically
trw-auditorverifies integration across all agent outputs before delivery- Each agent performs FR-by-FR self-review before marking work complete
Upgrading from <= 0.36.0
If you have playbooks or agent configs referencing the old 18-agent roster, use this predecessor map to update them:
| Old agent | Replacement |
|---|---|
| trw-lead | Orchestration is now done by the primary agent directly |
| trw-tester | trw-implementer (testing is part of TDD implementation) |
| trw-adversarial-auditor | trw-auditor |
| trw-prd-groomer | trw-prd-groomer (unchanged) |
| trw-requirement-writer | trw-prd-groomer |
| trw-requirement-reviewer | trw-prd-groomer |
| trw-traceability-checker | trw-auditor |
| trw-code-simplifier | trw-reviewer |
| reviewer-correctness / reviewer-integration / reviewer-performance / reviewer-security / reviewer-spec-compliance / reviewer-style / reviewer-test-quality | trw-reviewer |
Tip
Lifecycle hooks: TRW runs lifecycle hooks in the background — blocking agents who skip tests, warning on missed delivery, and preserving state before context compaction. Phase-change hook emissions were reduced from 20-100 per session to 3-5 in Sprint 79. These are automatic. No configuration needed.