# Three Man Team: a three-agent Claude Code workflow with Arch, Bob and Richard

> Three Man Team is a Shell-based skill set that turns one Claude Code session into an Architect, Builder and Reviewer with explicit handoffs. It targets token waste and mid-task drift, and it installs by cloning into .claude/skills/three-man-team.

**russelleNVy/three-man-team** — 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.

- Repository: https://github.com/russelleNVy/three-man-team
- Stars: 951 · Forks: 124
- Language: Shell
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/russellenvy-three-man-team

## What Three Man Team actually fixes in an AI coding session

The README frames the problem in behavioural terms rather than capability terms: AI coding tools "read entire codebases when they need one function", add features nobody asked for, and drift mid-task. Those are process failures, and the project's answer is a process rather than a better prompt. Three Man Team ships a set of role files, a CLAUDE.md, a token-optimizer skill and a setup script that together impose a fixed sequence on every unit of work.

The intended user is someone already running Claude Code against a real repository, not someone evaluating whether to use an AI coding tool at all. The repository is Shell with Markdown content, so there is no runtime to install beyond git and the Claude Code session itself. The README states the project works with Claude Code, VS Code, Cursor and any AI that supports context files, but the workflow description (subagents spun up through Claude Code's Agent tool) is specific to Claude Code.

## How the Arch, Bob and Richard handoff works inside one session

The mechanism is deliberately narrow. You keep one Claude Code session. Arch is the main agent and owns planning, the brief and the deploy. When a brief is ready, Arch starts Bob as a subagent through Claude Code's Agent tool. When Bob finishes, Arch starts Richard the same way. The README is explicit that you do not open three windows; the roles are agent identities inside a single session, not separate processes.

Every unit of work follows the same path: Architect plans and writes the brief, Builder reads it, shows a plan, builds and hands off to Reviewer, Reviewer clears or returns the work, Architect deploys with the Project Owner's go-ahead. The README says nothing skips a step. The roles are defaults and can be renamed; Arch handles renaming during setup, and v1.3.0 introduced manifest.md as the single source of truth for team names, role filenames, handoff directory, repo and branch.

The token argument is worth separating from the role argument. Three agents cost more coordination than one, and the project's justification is that the review step catches wrong turns a solo agent would carry to completion. Whether that trade pays off depends on your task size. For a one-line fix, the brief-and-review cycle is overhead; the README does not carve out an exemption for small changes.

## Installing Three Man Team per project and running the first brief

The README recommends the per-project install: one project, one install, cloned directly into the project folder. Navigate to your project and clone into the skills path.

```bash
cd /path/to/your/project
git clone https://github.com/russelleNVy/three-man-team.git .claude/skills/three-man-team
```

Then run the setup script from inside that directory. The README says setup takes over from here and prints the exact commands and the prompt to paste into Claude.

```bash
cd .claude/skills/three-man-team && ./setup
```

There is also a global install for people who want the team available in every project. It clones to the home skills folder and runs the same script.

```bash
git clone https://github.com/russelleNVy/three-man-team.git ~/.claude/skills/three-man-team
cd ~/.claude/skills/three-man-team && ./setup
```

For each project after a global install, the README copies the project-folder template into the target repository and then starts Claude Code.

```bash
cp -r ~/.claude/skills/three-man-team/templates/project-folder/. /path/to/your/project/
cd /path/to/your/project
```

Once Claude Code is open, the README gives this prompt to paste: "You are the Architect on this project. Please read new-setup.md." Arch then handles the project context file, the team names and your first session prompt. What you should see is a first session that asks about your setup rather than starting to code, because v1.3.0 changed Arch to read your actual files before walking through any change. The README does not show the contents of new-setup.md or the exact output of ./setup, so treat the first run as exploratory.

## The five token rules and what they do not cover

Token optimization here is a behaviour layer, not a compression layer. Every session starts with five rules baked into CLAUDE.md: trust skills or memory instead of re-reading files, kill speculative tool calls, parallelize calls that can run together, route output longer than 20 lines you will not use to a subagent, and delete restatements of what the user just said. The token-optimizer skill ships with every install and auto-loads through CLAUDE.md, so there is no separate activation step.

The README points to RTK as a separate, optional tool that compresses find, ls and grep output before it reaches Claude's context, and describes the combination as RTK at the bash layer plus token-optimizer at the behaviour layer. That distinction matters when you evaluate claims about savings: the five rules depend on the model following instructions, while RTK operates on command output before the model sees it. The README does not publish measured token reductions for either, and it does not describe a way to audit whether a given session actually obeyed the rules.

## Auto-update, manifest.md and the missing rollback path

At the start of every session, Arch fetches releases/latest.json, a version registry listing releases with a critical or non-critical flag. v1.3.0 changed this from hitting the GitHub API to reading the registry. If you are behind, Arch walks you through updates before anything else. Critical updates are mandatory checkpoints because they ship structural changes later updates depend on; non-critical updates are optional. The README states that Arch reads your actual files to determine what applies before suggesting anything, and that nothing changes without your confirmation.

The limitation is what happens when a change goes wrong. The README does not document rollback, does not describe how to pin a version, and does not say whether the registry can be pointed at a fork or a local file. The VERSION file was retired in v1.3.0 and version now lives in manifest.md, so anyone who scripted against the old VERSION file has a migration to do and no documented downgrade route. The mandatory checkpoint model also means a critical update is not something you can indefinitely defer, which is a real constraint if you run the team across repositories with different tolerances for change.

## Where a single-agent setup or a plugin is the better choice

The obvious alternative is running one Claude Code agent with a well-written CLAUDE.md and no role structure. That approach has no handoff protocol, no separate reviewer identity, and no manifest to maintain, which makes it cheaper for small, well-specified tasks and for exploratory work where the brief would be longer than the change. Three Man Team's value appears when tasks are large enough that a wrong turn is expensive and a review step is cheaper than the rework.

The README also names the Claude feature-dev plugin as a related search term, and the difference is architectural rather than cosmetic: a plugin extends what a single agent can do, while Three Man Team constrains what an agent is allowed to do by splitting planning, building and review into separate roles with a brief between them. If your problem is missing capability, a plugin is the right shape. If your problem is an agent that keeps doing more than you asked, the role split is the relevant fix. The project's own Pro tier, which the README says offers pre-built teams for developers, marketers and content creators, is a paid path to the same structure with less customization work.

## Licence, maintenance and the cost of staying current

Three Man Team is MIT licensed, and the README states it is free forever. MIT means you can fork, rename and redistribute the templates and role files, which is consistent with the project's own instruction to rename the agents to anything you like. The repository was last pushed on 2026-06-09, and the most recent release listed is v1.3.0 from 2026-06-08. The repository is not archived. Note that the README promotes a waitlist for Three Man Team Pro; the MIT licence covers the repository contents, not any hosted or paid product, and nothing here is legal advice.

Upgrade cost is mostly reading and deciding. The registry-based check runs at session start, critical updates are mandatory checkpoints, and Arch inspects your files before proposing changes, so the per-update effort is a review conversation rather than a merge. The recurring cost is keeping manifest.md accurate if you rename roles or move the handoff directory, since v1.3.0 made it the single source of truth for team names, role filenames, handoff directory, repo and branch. The README does not describe what happens if manifest.md drifts from reality.

## Conclusion

Adopt Three Man Team if you already run Claude Code on a single repository and keep losing time to agents that re-read files, add unrequested features or drift mid-task; the per-project install and the manifest.md setup path are the parts to try first. Do not adopt it if you work outside Claude Code, if you want a multi-window or multi-vendor agent orchestration layer, or if you need a documented rollback procedure, because the README does not describe one. Before committing, verify three things: that ./setup completes and writes manifest.md, that your Claude Code version exposes the Agent tool the subagent handoffs depend on, and that the five rules in CLAUDE.md match how you actually want your sessions to behave.

## FAQ

### Does Three Man Team run as three separate Claude Code windows?

No. The README states the team uses one Claude Code session, with Arch as the main agent and Bob and Richard spun up as subagents through Claude Code's Agent tool when work is ready. You do not open three windows.

### Where does Three Man Team install for a single project?

The README recommends cloning the repository into .claude/skills/three-man-team inside your project folder, then running ./setup from that directory. A global install to ~/.claude/skills/three-man-team is also documented.

### What is manifest.md in Three Man Team?

It was added in v1.3.0 and Arch generates it at first-time setup. The README describes it as the single source of truth for your install: team names, role filenames, handoff directory, repo and branch, replacing the retired VERSION file.

### Is Three Man Team free to use?

The repository is MIT licensed and the README says free forever. The README also links to a waitlist for Three Man Team Pro, which is a separate paid offering of pre-built teams.

## Sources

- [Issues](https://github.com/russelleNVy/three-man-team/issues)
- [License: MIT](https://github.com/russelleNVy/three-man-team/blob/main/LICENSE)
- [README](https://github.com/russelleNVy/three-man-team/blob/main/README.md)
- [Releases](https://github.com/russelleNVy/three-man-team/releases)
- [russelleNVy/three-man-team on GitHub](https://github.com/russelleNVy/three-man-team)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/russellenvy-three-man-team