Chapter 15: Role Specialization – Avoiding the "Omniscient Agent" Trap
Learning Objectives
Learn to decompose agents by responsibility, enabling multiple agents to balance each other rather than each operating in isolation.
The Omniscient Agent Trap
If you only configure one agent, it will:
Let me write code → write tests → review my own code → and validate
Result:
✗ Tests are written "to make my own code pass"
✗ Reviews are "to find places that look good to myself"
✗ Validation is "to pick easy-to-pass scenarios"
→ Just like humans: self-supervision = no supervision.
4 Core Roles in doc2video
flowchart LR
Dev["developer
implements task"]
Tester["tester
writes unit/feature tests"]
E2E["e2e-tester
black-box end-to-end"]
Rev["reviewer
reviews against spec"]
Spec["📜 specs/"] -.reads.-> Dev
Spec -.reads.-> Tester
Spec -.reads.-> E2E
Spec -.reads.-> Rev
Dev -->|code| Files["src/"]
Tester -->|tests| TFiles["tests/"]
Rev -.reviews.-> Files
Rev -.reviews.-> TFiles
E2E -.runs black-box.-> Build["dist/"]
style Dev fill:#bbdefb
style Tester fill:#c8e6c9
style E2E fill:#fff9c4
style Rev fill:#f8bbd0Key Decomposition Principles
| Principle | Why |
|---|---|
| Dev doesn't write tests | Self-justification trap – will write "just-enough tests to pass their own code" |
| Tester doesn't modify src | Role transgression – tests should expose issues, not mask them |
| Reviewer doesn't write code | Writing code creates ego, leading to bias towards one's own solutions |
| E2E-tester doesn't read src | Black-box perspective – only sees what the user sees, avoiding misleading implementation details |
Write Permissions Matrix
src/ tests/ specs/ design.md review/ test-reports/ STUCK.md
developer ✅ ❌ ❌ ❌ ❌ ❌ ❌
tester ❌ ✅ ❌ ❌ ❌ ✅ ❌
e2e-tester ❌ ❌ ❌ ❌ ❌ ❌ ❌
reviewer ❌ ❌ ❌ ❌ ✅ ❌ ❌
architect ❌ ❌ ❌ ❌ ❌ ❌ ✅
main Claude ❌ ❌ ❌ ❌ ❌ ❌ ❌
→ main Claude writes nothing – it's just a dispatcher.
Read Permissions: Mostly Universal
✅ All agents can read proposal / design / spec
✅ Developer / tester / reviewer can read src / tests
❌ E2E-tester does not read src (strict black-box perspective constraint)
Role-to-OpenSpec Artifact Mapping
flowchart TB
Tasks["tasks.md
(- [ ] tasks)"] -->|developer checks off| Dev2["Completed"]
Spec["spec.md
(Scenario)"] -->|tester translates| TestFile["tests/test_group_N.py"]
Diff["git diff
(developer + tester changes)"] -->|reviewer reviews| Review["review/N.md"]
Build["doc2video CLI"] -->|e2e-tester black-box| E2EReport["e2e-report.md"]
Stuck["All agents stuck"] -->|architect diagnoses| StuckMD["STUCK.md"]
style Dev2 fill:#bbdefb
style TestFile fill:#c8e6c9
style Review fill:#f8bbd0
style E2EReport fill:#fff9c4
style StuckMD fill:#e1bee7→ Each role has its exclusive "output file" – no overlap, no conflicts.
Anti-Patterns
❌ One agent writes both code and tests Self-justification
❌ Reviewer can also modify src Loss of independence
❌ Multiple agents write to the same review/N.md Confused state
❌ Role definition too broad ("full-stack agent") No division of labor = no checks and balances
❌ Roles too granular (one agent per folder) Dispatch cost explosion
Role Extension for Complex Projects
For special projects, you can add:
| Scenario | Added Role |
|---|---|
| Security-sensitive (finance/medical) | security-reviewer (independently scans for vulnerabilities) |
| Documentation/SDK project | doc-writer (synchronizes documentation updates) |
| Refactoring-intensive | refactor-agent (specializes in refactoring) |
| Data migration | migration-agent (specializes in schema migration) |
→ However, the 4 core roles are the baseline – fewer than these 4 would not constitute "multi-agent checks and balances."
What You Can Do Now
- Draw your project's role permission matrix.
- Explain the reasons behind each "cannot do" hard constraint.
- Determine when to add new roles.
The next chapter will turn these roles into dispatchable agent files.