three-man-team: A Three-Role Agent Workflow for Claude Code
A structured 3-agent AI dev team — Architect, Builder, Reviewer. Built from production use. Token-optimized. Works with Claude Code, VS Code, Cursor, and any AI that supports context files.
At a glance
- What is it?
- The repository packages Architect, Builder and Reviewer as context files and a setup script for a single Claude Code session. The design is a process constraint on agent drift, not a new model, and its value depends on whether you accept the handoff rules.
- Who is it for?
- Adopt it if you already run Claude Code on a single repository and want the plan, build, review sequence written down as files rather than kept in your head. Skip it if your work is exploratory, if you need parallel agents on separate machines, or if you cannot accept a mandatory update checkpoint at the start of a session.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 99 days ago.
- What is it written in?
- Mainly Shell, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The failure modes three-man-team is built to prevent
The README states the problem in plain terms: coding agents read entire codebases when they need one function, add features nobody asked for, drift mid-task, and burn tokens on work that did not need to happen. The project's answer is not a better prompt but a fixed sequence with three named roles. Architect plans and writes the brief. Builder reads the brief, shows a plan, builds, and hands off. Reviewer either clears the work or sends it back. Architect deploys only with the Project Owner's go-ahead.
The intended user is someone already running Claude Code on a real repository, who has felt the cost of an agent wandering. The README is explicit that the roles map to how software ships: one person who understands the whole system and owns the deploy, one who builds, one who catches what the builder missed. The claim that three is the right number is argued rather than asserted. Solo agents drift because nobody catches a wrong turn; larger teams spend more effort coordinating than producing. That is a design position, and it is the part of the project most worth arguing with.
One session, two subagents, and a written brief between them
The mechanism is narrower than the name suggests. Three Man Team does not run three processes. According to the README, everything runs inside a single Claude Code session. Arch is the main agent. When work is ready to build, Arch spins up Bob as a subagent through Claude Code's Agent tool. When Bob finishes, Arch spins up Richard the same way. The README states directly that you do not open three windows.
The artifact that moves between roles is the brief. Architect writes it, Builder works from it, Reviewer judges against it. The README says Builder shows a plan before building, which gives the Architect a checkpoint before tokens are spent on the wrong implementation. Nothing skips a step.
A second artifact appeared in v1.3.0. The release notes describe manifest.md as generated by Arch at first-time setup, holding team names, role filenames, the handoff directory, the repo and the branch. The same release retired the VERSION file, so version now lives in the manifest. This matters for anyone upgrading from 1.2.x: the manifest is the single source of truth for the install, and the release notes flag it as a structural change that later updates depend on.
Installing it per project or globally
The README gives two install paths. The per-project route is recommended. From your project folder:
git clone https://github.com/russelleNVy/three-man-team.git .claude/skills/three-man-team cd .claude/skills/three-man-team && ./setup
The global route clones to ~/.claude/skills/three-man-team and runs ./setup there. Because the global install only puts the skill in place, each project needs a second step:
cp -r ~/.claude/skills/three-man-team/templates/project-folder/. /path/to/your/project/
Then open Claude Code and paste the prompt the README supplies:
You are the Architect on this project. Please read new-setup.md.
Arch takes over from that point, creating the project context file, the team names and the first session prompt. The README says setup prints the exact commands and the prompt to paste, so the reliable path is to run ./setup and follow its output rather than copying from a review.
Two template directories exist. templates/project-folder/ ships named personas (Arch, Bob, Richard) that are fully written and ready to use. templates/generic/ is a blank slate with [CUSTOMIZE] placeholders for people building personas from scratch. Renaming is handled by Arch during setup.
The token rules are five lines in CLAUDE.md
Token optimization is the part of the project with the clearest specification. The README quotes the five rules baked into CLAUDE.md, which the token-optimizer skill ships with and auto-loads:
Is this in a skill or memory? -> Trust it. Skip the file read. Is this speculative? -> Kill the tool call. Can calls run in parallel? -> Parallelize them. Output > 20 lines you won't use -> Route to subagent. About to restate what user said -> Delete it.
These are behavioural constraints on the agent, not a compression layer. The README distinguishes the two explicitly and points to RTK, a separate tool that compresses find, ls and grep output before it reaches Claude's context. The project calls RTK not required but recommended for heavy Claude Code CLI users, and describes the combination of RTK at the bash layer and token-optimizer at the behaviour layer as where savings compound. No numbers are given for those savings, and this article cannot supply any.
The fifth rule is the one that changes output most. Deleting restatement of the user's own message removes the conversational padding that makes agent transcripts long without making them useful.
Auto-update writes to your install, and that is a real constraint
At the start of every session, Arch fetches releases/latest.json, a version registry listing each release with a critical or non-critical flag. Behind on a critical update, Arch walks through it before any other work; non-critical updates are optional. The README quotes the kind of message you get: an update is available, Arch will look at your actual files and say what applies to you. Nothing changes without your confirmation.
The v1.3.0 notes explain why the registry exists: the version check no longer hits the GitHub API. For anyone working offline or behind a restrictive network, that is a meaningful change, though the registry still has to be fetched from somewhere, so a fully air-gapped session is not described.
The constraint is the mandatory checkpoint. If your team treats the start of a session as untouchable setup time, a critical update will interrupt it. The README frames this as structural: critical updates ship changes that later updates depend on. You can decline, but the project's own reasoning is that declining puts you on a branch of the install that future updates do not cover. That is a reasonable position and also a coupling you should accept deliberately rather than discover on a deadline.
Where the three-role model is the wrong tool
The workflow assumes the work decomposes into plan, build, review. Plenty of tasks do not. A one-line fix, a spike to find out whether an API even does what you need, or an exploratory refactor where the destination is unknown all fit badly. Forcing them through Architect, Builder and Reviewer adds a brief and a handoff to work that never needed either. The README's own framing supports this reading: the roles exist to catch drift and unwanted features, and neither is the dominant risk in a fifteen-minute experiment.
The subagent model is a second boundary. Because Builder and Reviewer run as subagents inside one Claude Code session, the parallelism is not the kind you get from three terminals on three machines. A long build blocks the session that would otherwise be doing something else. The README presents the single-session design as a convenience, and it is, but it also means the throughput ceiling is the ceiling of one session.
A third limitation is that the role files are prose. The README says the personas are fully written and meant to be customized in the Who You Are sections. Nothing enforces that Reviewer actually rejects bad work; the enforcement is the instruction in the file plus the Architect's willingness to route work back. Teams that treat the role names as a guarantee will be disappointed. The project is a set of conventions, and conventions hold only while someone applies them.
How this differs from a single-agent setup or a general agent framework
The nearest alternative is what most people already do: one agent, one long session, no role separation. That setup has no handoff artifact, so there is nothing for a reviewer to check against and no point at which a wrong turn is caught before more code is written. Three Man Team's difference is the brief. It is a written intermediate that both Builder and Reviewer read, which is why the Architect role owns it rather than the Builder.
A second comparison is RTK, mentioned in the README. RTK is not a competitor; it operates on a different layer. RTK compresses shell output before it reaches context. Three Man Team constrains what the agent chooses to do. You can run either without the other, and the README says as much by calling RTK optional.
The more interesting contrast is with general multi-agent frameworks, where agents are typically separate processes with message passing and a scheduler. Three Man Team has none of that. There is no orchestration service, no queue, no persistent agent state between sessions beyond the files in your repository. That is a deliberate simplification: the coordination cost the README warns about is avoided by keeping all three roles inside one session. It also means the project inherits Claude Code's Agent tool as a dependency. The README names Claude Code, VS Code, Cursor and any AI that supports context files, but the subagent mechanism it describes is Claude Code's, and the README does not explain how the handoff works on the other editors it lists.
Maintenance cost, licence and what to check before adopting
The project is Shell plus Markdown, licensed MIT, described in the README as free forever. There is no build step, no runtime dependency to pin, and no service to operate. The maintenance surface is the role files and the manifest. Upgrades are handled by the auto-update path, which reads releases/latest.json and applies changes with your confirmation. The releases listed run from v1.2.4 in late May 2026 through v1.3.0 on 8 June 2026, so the cadence has been frequent and the changes have included structural ones.
MIT means you can modify and redistribute the role files, including inside a commercial product, provided the licence terms are met. That is a statement about the licence text, not advice about your situation; if you are folding the templates into something you ship, read the licence yourself.
The README also advertises a paid tier, Three Man Team Pro, with pre-built teams for developers, marketers and content creators, gated behind a waitlist. Nothing in the repository material describes what Pro contains beyond that, so treat the free install as the thing under evaluation here.
What to verify before committing: open templates/project-folder/ and read the Who You Are sections to see whether the defaults match how your team reviews work, and open releases/latest.json to see the update flags you will be shown at session start. If the mandatory critical checkpoints or the single-session subagent model do not fit your workflow, the three-role structure will not rescue the fit.
Editorial conclusion
Adopt it if you already run Claude Code on a single repository and want the plan, build, review sequence written down as files rather than kept in your head. Skip it if your work is exploratory, if you need parallel agents on separate machines, or if you cannot accept a mandatory update checkpoint at the start of a session. Before installing, read templates/project-folder/ and releases/latest.json in the repository and confirm that the role files match how your team actually reviews code.
Community notes