Agent Team — Equipe Multi-Agente para Claude Code
Wievondii/agent-team
Equipe de dev paralela: PM, Planner, Devs, Reviewer, Tester em uma conversa
Ver no GitHubPlugin para Claude Code que orquestra uma equipe completa de desenvolvimento com 5 agentes especializados (PM, Planner, Developer, Reviewer, Tester) executando em paralelo. Comunica-se via log Markdown compartilhado com persistência de estado e auto-correção de bugs através de SendMessage. Instalação e ativação simplificadas com um comando cada.
Instalação
npx convez-ai Wievondii/agent-team1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Desenvolvimento de projetos complexos com múltiplos módulos em paralelo
- Revisão automática de código e testes integrados no fluxo
- Prototipagem rápida com divisão de responsabilidades entre agentes especializados
Veredito

Arquitetura sofisticada com paralelização real, persistência de task_id e roteamento de erros por classe de severidade. Requer Node.js 18+ e compreensão profunda de fluxos multi-agente; viável para equipes que precisam de orquestração determinística e auditável de desenvolvimento.
README
A tradução para o português deste README ainda está na fila.
Agent Team — Multi-Agent Dev Team for Claude Code
v2.0 is a breaking upgrade. Parallel architecture, three independent budgets, five-class error routing, strict YAML-frontmatter schemas, append-only event log, shared-file coordinator pattern. Migration: see MIGRATION.md.
Prerequisite: Node.js >= 18 (required for the validation scripts; first run of the plugin auto-installs npm deps).
What is this?
Agent Team is a Claude Code plugin that gives you a complete software development team inside your terminal:
| Role | Responsibility | Model |
|---|---|---|
| Project Manager (main agent) | Receives requirements, dispatches the team, maintains the event log + boulder.json view, routes errors | — |
| Planner | Analyzes requirements, defines interface/style specs + semantic_constraints, splits modules, produces round-plan.md | opus |
| Developer ×N | Implements assigned modules in parallel; private dev-{module}.md with YAML frontmatter; must paste self_check evidence | opus |
| Reviewer | Two modes: reviewer (parallel review, write report only) + committer (exclusive git add + git commit) | opus |
| Tester ×N | Runs tests in parallel; classifies bugs as A/B/C/D/E; severity auto-derived from impact × frequency matrix | sonnet |
Core mechanics (v2.0):
- Parallel execution — Developers and Testers run concurrently in the same conversation turn (Claude Code's Task tool dispatches them in parallel)
- task_id persistence — when the Tester finds a bug, the PM wakes the original Developer session via the recorded task_id; full context preserved
- Three independent budgets —
reviewer_rejection(3) /bug_fix_a(3) /bug_fix_b(2) +round_total(8). Class-B bugs no longer eat the same pool as reviewer rework. - Append-only event log — all
boulder.jsonchanges go throughboulder-events.jsonl+rebuild-boulder.mjs; no concurrency races - Hard schema validation — dev-log / round-plan / bug-report all validated against JSON Schema via Node.js scripts
- Shared-file coordinator — to prevent parallel write conflicts: shared files get a single
coordinator; other devs writeshared_file_requestsinstead of editing directly - Rollback — every round starts with
git tag round-N-baseline; on budget exhaustion, one-clickgit resetis offered
Quick Start
1. Install the Plugin
Inside Claude Code, register the marketplace and install:
/plugin marketplace add Wievondii/agent-team
/plugin install agent-team@wievondii-agent-team
Alternative — local install from clone:
git clone https://github.com/Wievondii/agent-team.git
Then inside Claude Code:
/plugin marketplace add /absolute/path/to/agent-team
/plugin install agent-team@wievondii-agent-team
2. Activate the Team
/agent-team:team
Then tell the PM what you need:
"Build a landing page with a hero section and contact form"
The team handles everything: plan → parallel develop → integration check → parallel review → commit → parallel test → report.
The first time you run the plugin, the PM's startup hook auto-installs the npm deps the validation scripts need (ajv, fast-glob, proper-lockfile, yaml). The init-project.mjs script also automatically copies the Agent Guard hook to your project and configures .claude/settings.json. You won't notice — it just works.
How It Works (v2.0)
User Request → Project Manager (your Claude Code session)
│
0. Recovery check (boulder.json)
│
1. Plan
Planner → rounds/round-N/plan.md (YAML frontmatter, schema-validated)
PM runs validate-plan.mjs + check-file-conflicts.mjs (must pass)
│
2. Parallel develop
PM dispatches N Developers in one turn (parallel)
Each writes its own dev-{module}.md (frontmatter + self_check evidence)
PM runs validate-dev-log.mjs (must pass)
│
3. Integration check (when N > 1)
Integration lead verifies all call chains
Failure → fix + simplified review (typecheck + interface contracts)
│
4. Two-phase review
4a. N Reviewers in parallel (write reports only, no commit)
4b. 1 Committer exclusively runs git add + git commit
│
5. Parallel test
PM dispatches N Testers in one turn
Each writes bugs to rounds/round-N/test.md (frontmatter, schema-validated)
│
6. Error routing (5 classes)
A → wake Developer (consume bug_fix_a)
B → wake Planner + Developer (consume bug_fix_b)
C → PM self-fix (env / deps)
D → escalate to user immediately
E → wake Tester to rewrite test case
│
7. Report → ask user for feedback
│
8. Round end (archive-round.mjs)
File Structure
agent-team/
├── .claude-plugin/
│ ├── plugin.json # v2.0.0 manifest
│ └── marketplace.json # Self-contained marketplace definition
├── agents/
│ ├── planner.md # agent-team-planner subagent
│ ├── developer.md # agent-team-developer subagent
│ ├── reviewer.md # agent-team-reviewer subagent (reviewer/committer modes)
│ └── tester.md # agent-team-tester subagent
├── commands/
│ └── team.md # /agent-team:team entry point
├── skills/team/
│ ├── SKILL.md # PM orchestration contract (v2.0)
│ ├── schemas/ # 5 JSON Schemas
│ │ └── boulder.schema.json / boulder-event / dev-log / round-plan / bug-report
│ ├── scripts/ # 13 validation/event scripts (Node.js)
│ │ ├── package.json # ajv / fast-glob / proper-lockfile / yaml
│ │ ├── ensure-deps.mjs # PM startup hook, auto npm install
│ │ ├── append-event.mjs / rebuild-boulder.mjs
│ │ ├── validate-dev-log.mjs / validate-plan.mjs
│ │ ├── check-file-conflicts.mjs / check-quality-gates.mjs
│ │ ├── check-budget.mjs / heartbeat.mjs / check-task-id-fresh.mjs
│ │ ├── derive-severity.mjs / init-project.mjs / archive-round.mjs
│ │ └── lib/ # paths/locking/schema-loader/frontmatter/git-helpers/severity-matrix
│ └── template/
│ ├── agent-team-log-index.md
│ ├── round-plan.md / round-review.md / round-test.md / round-integration.md
│ ├── dev-workspace.md # YAML frontmatter
│ └── notepads/ # 5 notepad templates
├── LICENSE
├── MIGRATION.md # v1 → v2 upgrade guide
├── README.md / README.zh-CN.md
Runtime logs (created in your project directory when active):
your-project/
└── agent-team-logs/
├── index.md # Index file
├── boulder.json # State view (rebuilt from events; do not edit)
├── boulder-events.jsonl # Append-only event log
├── rounds/round-N/
│ ├── plan.md # Planner output (frontmatter + freeform)
│ ├── review.md # Reviewer/Committer output
│ ├── test.md # Tester output (with bugs[] frontmatter)
│ └── integration.md # Integration check report
├── dev-{module}.md # Each Developer's private log (strict frontmatter)
├── notepads/ # decisions / learnings / issues / verification / problems
├── shared-file-changes/round-N.md # Non-coordinator change requests for shared files
└── test-evidence/round-N/ # Test screenshots/logs
Requirements
- Claude Code (with plugin support)
- Node.js >= 18 (validation scripts; npm deps auto-installed by
ensure-deps.mjson first run) - Git (for round baseline tags + the Committer)
Customizing Models
Edit the model: field in each subagent's frontmatter (agents/*.md):
---
name: agent-team-developer
model: opus # change to sonnet / haiku
---
Default mapping:
| Role | Default Model |
|---|---|
| Planner | opus |
| Developer | opus |
| Reviewer | opus |
| Tester | sonnet |
Key Design Decisions (v2.0)
- Parallel architecture — Developers and Testers run in parallel; Reviewers also parallelize (split modules across N reviewers, then 1 committer).
- Hard tool whitelisting via subagent frontmatter — stronger than prompt-only "don't modify code" instructions.
- Two-phase review — N reviewers in parallel (report only) + 1 committer for exclusive
git add+git commit. - task_id persistence — same-round bug fixes always wake the original Developer session.
- PM doesn't read private logs —
dev-*.mdis read/written only by the corresponding Developer; PM usesvalidate-dev-log.mjsto confirm status indirectly. - Three independent budgets —
reviewer_rejection/bug_fix_a/bug_fix_bcount separately, so Class-B re-planning doesn't drain the Class-A pool. - Five-class error routing — A in-module / B cross-module / C env / D requirement misunderstanding / E test-case error (D escalates immediately).
- Parallel write-conflict protection — Planner must list cross-module shared files in
shared_filesand assign acoordinator; non-coordinators writeshared_file_requests; PM enforces withcheck-file-conflicts.mjs. - Append-only event log — all
boulder.jsonmutations go throughevents.jsonl+ rebuild, eliminating concurrency races. - Hard schema validation — dev-log / round-plan / bug-report all validated via Ajv against JSON Schema; non-conforming outputs are rejected immediately.
- Forced quality-gate evidence — Developer must run
check-quality-gates.mjsand paste command output intoself_check.evidencebefore reporting completion. - Rollback mechanism — every round starts with
git tag round-N-baseline; on budget exhaustion, the user can opt forgit reset --hardto restart the round. - Agent Guard Hook — built-in hook (
.claude/hooks/agent-guard.js) enforces role-based permissions usingagent_typefield. Blocks Write/Edit/Bash based on each agent's allowed paths and commands. Intercepts return detailed role-responsibility messages.
Agent Guard Hook
The plugin includes a built-in Agent Guard Hook that provides role-based permission enforcement using Claude Code's agent_type field.
How It Works
The hook runs before every Write, Edit, or Bash tool call. It reads the agent_type field from the PreToolUse hook input to identify which agent is making the call, then enforces role-specific permission rules.
Permission Matrix:
| Agent | Write/Edit Allowed | Bash Commands Blocked |
|---|---|---|
| PM (main thread) | All files | None |
| Planner | agent-team-logs/** only | git add/commit/push, build/test commands |
| Developer | file_scope + dev-*.md + notepads | git add/commit/push |
| Reviewer | review.md + notepads | build/test commands |
| Tester | test.md + notepads | git add/commit/push, build commands |
All agents are blocked from:
.git/**- Git internalsnode_modules/**- Dependencies.env,.env.*- Environment files*.key,*.pem- Security keys
Blocked Bash Commands
| Agent | Blocked Patterns |
|---|---|
| Planner | git add/commit/push, npm run build/test, cargo build/test, go build/test, pytest |
| Developer | git add/commit/push |
| Reviewer | npm run build/test, cargo build/test, go build/test, pytest |
| Tester | git add/commit/push, npm run build, cargo build, go build |
Intercept Messages
When an agent tries to perform an unauthorized action, the hook returns a detailed message explaining:
⛔ 角色越权拦截
👤 你的角色: 策划师(Planner)
🚫 拦截的操作: Write 项目源文件
📁 目标: src/index.ts
📝 原因: 不在允许的路径范围内
✅ 你的职责:
• 分析需求,制定开发计划
• 定义接口规范和语义约束
• 划分模块和 file_scope
• 识别 shared_files 和 coordinator
❌ 你不能:
• 禁止 Write/Edit 项目源文件
• 禁止运行 build/test/lint 命令
• 禁止 git add/commit/push
Configuration
The hook is automatically configured when the PM initializes a project. The init-project.mjs script:
- Copies
agent-guard.jsto<project>/.claude/hooks/ - Configures
<project>/.claude/settings.jsonwith the hook settings:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Write|Edit|Bash",
"hooks": [
{
"type": "command",
"command": "node",
"args": [".claude/hooks/agent-guard.js"],
"timeout": 10
}
]
}
]
}
}
No additional setup required — the hook is active as soon as the project is initialized by the PM.