Tool Roles
This page explains why the system uses one builder CLI, Claude Code, and Gemini CLI together instead of pretending one tool should plan, build, review, and approve by itself.
If you first need the broader distinction between chatbot surfaces and CLI surfaces, read Chatbots And CLIs.
Proof status note:
- the role split is the current platform contract
- deterministic PR state checks are already real
- the full multi-tool CI review loop is still a target proof item until it reaches
proven_livein Workflow And Proof
1. Why This Split
Three tools exist because three jobs must stay separate:
- the builder should not approve itself
- the broad reader should remain comment-only rather than pushing implementation
- the human should remain the final owner of scope and merge
If one tool tries to do everything, the common failure modes are predictable:
| Failure mode | Why it happens | Why the split helps |
|---|---|---|
| self-approval | the same tool builds and reviews its own work | Claude stays outside the builder path |
| hidden scope drift | the implementation loop narrows around local code | Gemini reads wider context and flags contradiction |
| silent takeover of ownership | one tool can accumulate planning breadth, write access, and merge authority | the split keeps those powers separated across the builder CLI, Gemini, and the human merge owner |
Current assignment:
- the builder lane is filled by one agentic builder surface in the current proof
- Claude Code is the hard auditor
- Gemini CLI is the broad contradiction reader
- the human remains scope owner and merge owner
Each tool has one role and one write boundary. The assignment is fixed, not emergent.
Prompt ownership follows the same rule:
- the builder lane authors the scoped audit prompt in the current proof
- Claude Code and Gemini CLI take the reviewer role named in that prompt
- the human still owns merge and override decisions
The prompt defines the audit lane. The reviewer does not improvise one.
The builder does not invent the audit criteria from taste.
It translates the human-signed repo contract, especially PLAN.md, REQUIREMENTS.json, and the declared review lane, into a machine-readable prompt for the reviewers.
2. Actors
Three tools cover three machine roles; the human is the fourth actor because scope and merge authority must not sit on any tool.
| Actor | Reads | Writes | Why this boundary exists |
|---|---|---|---|
| Human | scope, plan, merge surface | PLAN.md, merge decisions |
silent ownership takeover |
| Builder CLI | branch, AGENTS.md, INVARIANTS.md, PLAN.md |
code, DECISIONS.md, lane-specific audit prompts |
hidden work in chat state |
| Claude Code | diff plus the contract it must satisfy | comments and blocking findings inside the assigned review lane | self-approval and contract drift |
| Gemini CLI | repository context beyond the diff | contradiction notes and scope-drift warnings inside the assigned review lane | local-context narrowing |
CI on main |
merged tree | rendered state views on main |
branch-state drift reaching public views |
Claude and Gemini sit on the review side because review must be pre-merge and non-interactive. Claude reads the diff plus the rules it must satisfy and blocks on contract drift. Gemini reads the repository beyond the diff and is intended to surface non-blocking PR comments or workflow notes, so it catches contradictions the diff alone cannot see.
The key asymmetry is deliberate:
- the builder CLI is prompted to build and to set audit scope
- Claude and Gemini are prompted to review within a named role
- neither reviewer receives merge ownership
The current proof's builder-startup asymmetry is covered in Instruction Files.
The canonical branch flow lives in Branches And Continuity.