convez.ai
AgenteDesenvolvimento WebAvançado
Wievondii

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 GitHub
InicialPluginScore · de 0 a 100

Plugin 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-team

1 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

Estrelas
2
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
2

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:

RoleResponsibilityModel
Project Manager (main agent)Receives requirements, dispatches the team, maintains the event log + boulder.json view, routes errors—
PlannerAnalyzes requirements, defines interface/style specs + semantic_constraints, splits modules, produces round-plan.mdopus
Developer ×NImplements assigned modules in parallel; private dev-{module}.md with YAML frontmatter; must paste self_check evidenceopus
ReviewerTwo modes: reviewer (parallel review, write report only) + committer (exclusive git add + git commit)opus
Tester ×NRuns tests in parallel; classifies bugs as A/B/C/D/E; severity auto-derived from impact × frequency matrixsonnet

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.json changes go through boulder-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 write shared_file_requests instead of editing directly
  • Rollback — every round starts with git tag round-N-baseline; on budget exhaustion, one-click git reset is 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.mjs on 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:

RoleDefault Model
Planneropus
Developeropus
Revieweropus
Testersonnet

Key Design Decisions (v2.0)

  1. Parallel architecture — Developers and Testers run in parallel; Reviewers also parallelize (split modules across N reviewers, then 1 committer).
  2. Hard tool whitelisting via subagent frontmatter — stronger than prompt-only "don't modify code" instructions.
  3. Two-phase review — N reviewers in parallel (report only) + 1 committer for exclusive git add + git commit.
  4. task_id persistence — same-round bug fixes always wake the original Developer session.
  5. PM doesn't read private logs — dev-*.md is read/written only by the corresponding Developer; PM uses validate-dev-log.mjs to confirm status indirectly.
  6. Three independent budgets — reviewer_rejection / bug_fix_a / bug_fix_b count separately, so Class-B re-planning doesn't drain the Class-A pool.
  7. Five-class error routing — A in-module / B cross-module / C env / D requirement misunderstanding / E test-case error (D escalates immediately).
  8. Parallel write-conflict protection — Planner must list cross-module shared files in shared_files and assign a coordinator; non-coordinators write shared_file_requests; PM enforces with check-file-conflicts.mjs.
  9. Append-only event log — all boulder.json mutations go through events.jsonl + rebuild, eliminating concurrency races.
  10. Hard schema validation — dev-log / round-plan / bug-report all validated via Ajv against JSON Schema; non-conforming outputs are rejected immediately.
  11. Forced quality-gate evidence — Developer must run check-quality-gates.mjs and paste command output into self_check.evidence before reporting completion.
  12. Rollback mechanism — every round starts with git tag round-N-baseline; on budget exhaustion, the user can opt for git reset --hard to restart the round.
  13. Agent Guard Hook — built-in hook (.claude/hooks/agent-guard.js) enforces role-based permissions using agent_type field. 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:

AgentWrite/Edit AllowedBash Commands Blocked
PM (main thread)All filesNone
Planneragent-team-logs/** onlygit add/commit/push, build/test commands
Developerfile_scope + dev-*.md + notepadsgit add/commit/push
Reviewerreview.md + notepadsbuild/test commands
Testertest.md + notepadsgit add/commit/push, build commands

All agents are blocked from:

  • .git/** - Git internals
  • node_modules/** - Dependencies
  • .env, .env.* - Environment files
  • *.key, *.pem - Security keys

Blocked Bash Commands

AgentBlocked Patterns
Plannergit add/commit/push, npm run build/test, cargo build/test, go build/test, pytest
Developergit add/commit/push
Reviewernpm run build/test, cargo build/test, go build/test, pytest
Testergit 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:

  1. Copies agent-guard.js to <project>/.claude/hooks/
  2. Configures <project>/.claude/settings.json with 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.


License

MIT

Ver o original no GitHub

Bom para

Relacionados