agent-teams

Name: agent-teams
Author: alinaqi

github.com/alinaqiAgent 工作流711291 次安装2 周前更新

关于 agent-teams

agent-teams 是面向 Maggy 项目的多 Agent 协作技能，为功能开发规定依赖驱动的 TDD 流程。团队包含编排、质量、安全、审查、合并和功能 Agent，并可在 Docker/OrbStack 可用时隔离功能 Agent。

主要功能

01按规格、测试、实现和审查推进功能
02通过任务依赖强制执行阶段顺序
03设置编排、质量、安全和合并等 Agent 角色
04让多个功能开发链并行运行
05可选用 Polyphony 容器隔离功能 Agent

适用场景

01为项目初始化标准化的 Agent 团队
02按严格 TDD 流程并行开发多个功能
03在合并前执行覆盖率、代码审查和安全检查
04通过独立容器减少功能分支间的工作区冲突

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/alinaqi/maggy --skill agent-teams

安装后在 Claude Code 中输入/agent-teams确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

agents/

code-review.md

feature.md

merger.md

quality.md

security.md

team-lead.md

详细介绍

Agent Teams Skill

用途： 每个使用 Maggy 初始化的项目都会作为一支协调一致的 AI Agent 团队运行。这是默认工作流，不可选。团队会强制执行严格的 TDD 流程，任何步骤都不能跳过。

设置： Agent 定义放在 .claude/agents/ 中，并使用正确的 frontmatter（name、description、model、tools、disallowedTools、maxTurns、effort）。格式请参阅 Agent 文件。

核心原则

每项功能都遵循由任务依赖关系强制执行的不可变流程：

┌─────────────────────────────────────────────────────────────────┐
│  STRICT FEATURE PIPELINE (IMMUTABLE)                            │
│  ──────────────────────────────────────────────────────────────  │
│                                                                  │
│  1. SPEC        Write feature specification                      │
│       ↓         (Feature Agent)                                  │
│  2. REVIEW      Quality Agent reviews spec completeness          │
│       ↓         (Quality Agent)                                  │
│  3. TESTS       Write failing tests for all acceptance criteria  │
│       ↓         (Feature Agent)                                  │
│  4. RED VERIFY  Quality Agent confirms ALL tests FAIL            │
│       ↓         (Quality Agent)                                  │
│  5. IMPLEMENT   Write minimum code to pass tests                 │
│       ↓         (Feature Agent)                                  │
│  6. GREEN VERIFY Quality Agent confirms ALL tests PASS + coverage│
│       ↓         (Quality Agent)                                  │
│  7. VALIDATE    Lint + type check + full test suite              │
│       ↓         (Feature Agent)                                  │
│  8. CODE REVIEW Multi-engine review, block on Critical/High      │
│       ↓         (Code Review Agent)                              │
│  9. SECURITY    OWASP scan, secrets detection, dependency audit  │
│       ↓         (Security Agent)                                 │
│  10. BRANCH+PR  Create feature branch, stage files, create PR    │
│                 (Merger Agent)                                    │
│                                                                  │
│  No step can be skipped. Task dependencies enforce ordering.     │
│  Quality Agent verifies RED/GREEN transitions.                   │
│  Code Review + Security Agents gate the merge path.              │
│  Merger Agent handles branching and PR creation.                 │
└─────────────────────────────────────────────────────────────────┘

默认 Agent 名单

每个项目都会启动 5 个常驻 Agent，以及 N 个功能 Agent：

┌─────────────────────────────────────────────────────────────────┐
│  DEFAULT TEAM ROSTER                                             │
│  ──────────────────────────────────────────────────────────────  │
│                                                                  │
│  PERMANENT AGENTS (always present)                               │
│  ─────────────────────────────────                               │
│  Team Lead        Orchestration, task breakdown, assignment      │
│                   Uses delegate mode - NEVER writes code         │
│                                                                  │
│  Quality Agent    TDD verification (RED/GREEN phases)            │
│                   Coverage gates (>= 80%)                        │
│                   Spec completeness review                       │
│                                                                  │
│  Security Agent   OWASP scanning, secrets detection              │
│                   Dependency audit, .env validation               │
│                   Blocks on Critical/High                        │
│                                                                  │
│  Code Review Agent  Multi-engine code review                     │
│                     Claude / Codex / Gemini / All                │
│                     Blocks on Critical/High                      │
│                                                                  │
│  Merger Agent     Creates feature branches                       │
│                   Stages feature-specific files only              │
│                   Creates PRs via gh CLI                          │
│                   NEVER merges - only creates PRs                │
│                                                                  │
│  DYNAMIC AGENTS (one per feature)                                │
│  ────────────────────────────────                                │
│  Feature Agent    Implements one feature end-to-end              │
│  (x N features)   Follows strict pipeline above                  │
│                   Uses Ralph loops for implementation             │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Agent	职责	计划模式	可以编辑代码
team-lead	编排、任务拆解、分配	否（委派模式）	否
quality-agent	TDD 验证、覆盖率门槛	是	否（只读）
security-agent	OWASP 扫描、机密信息检测	是	否（只读）
review-agent	多引擎代码审查	是	否（只读）
merger-agent	分支创建、PR 管理	否	否（仅 git）
feature-{name}	功能实现（每项功能一个）	否	是

Team Lead 的职责

Team Lead 负责统筹，绝不编写代码。

阅读 _project_specs/features/*.md，识别所有功能
将每项功能拆解为 10 个任务的依赖链（见下文）
为每项功能启动一个功能 Agent
将初始任务（编写规格）分配给功能 Agent
持续监控 TaskList，跟踪进度和阻塞项
处理阻塞任务并重新分配
协调跨功能依赖关系
创建所有 PR 后，向所有 Agent 发送 shutdown_request
完成后清理团队

必须使用委派模式。 Team Lead 只能使用：

TeamCreate、TaskCreate、TaskUpdate、TaskList、TaskGet
SendMessage（message、broadcast、shutdown_request）
Read、Glob、Grep（用于监控）

功能 Agent 工作流（强制）

每个功能 Agent 必须严格遵循以下顺序。任务依赖关系会强制执行步骤顺序——只有步骤 N 标记为完成并通过验证后，功能 Agent 才能开始步骤 N+1。

步骤 1：编写规格

创建 _project_specs/features/{feature-name}.md
包含：描述、验收标准、测试用例表、依赖关系
遵循 base.md 技能中的原子 TODO 格式
将任务标记为完成 -> Quality Agent 审查

步骤 2：编写测试（RED 阶段）

根据规格中的测试用例表编写测试文件
测试必须覆盖所有验收标准
导入尚不存在的模块（测试将会失败）
将任务标记为完成 -> Quality Agent 验证测试已存在且失败

步骤 3：等待 RED 验证

Quality Agent 运行测试，并验证所有新增测试均失败
如果有任何测试在尚未实现时通过 -> 重写测试
Quality Agent 将验证标记为完成 -> 解锁实现

步骤 4：实现（GREEN 阶段）

编写最少量的代码，使所有测试通过
遵循 base.md 中的简洁性规则（每个函数 20 行、每个文件 200 行、3 个参数）
使用 Ralph 循环（/ralph-loop）进行迭代实现
实现后运行测试——必须全部通过
将任务标记为完成 -> Quality Agent 验证测试通过

步骤 5：等待 GREEN 验证

Quality Agent 运行完整测试套件并检查覆盖率
覆盖率必须 >= 80%
如果测试失败或覆盖率不足 -> 修复并重新请求验证
Quality Agent 将验证标记为完成 -> 解锁验证阶段

步骤 6：验证

运行代码检查器（ESLint / Ruff）
运行类型检查器（TypeScript / mypy）
运行带覆盖率的完整测试套件
修复任何问题
将任务标记为完成 -> 解锁代码审查

步骤 7：等待代码审查

Code Review Agent 对已更改的文件运行 /code-review
如果存在 Critical 或 High 级别问题 -> 修复并重新请求审查
Code Review Agent 将任务标记为完成 -> 解锁安全扫描

步骤 8：等待安全扫描

Security Agent 运行安全检查
如果发现严重或高危问题 -> 修复并重新请求扫描
Security Agent 标记完成 -> 解锁合并

步骤 9：等待分支 + PR

Merger Agent 创建功能分支、暂存文件并创建 PR
创建 PR 后，功能即告完成

任务依赖链模型

对于每个功能“X”，团队负责人会按严格顺序创建以下 10 个任务：

┌────────────────────────────────────────────────────────────────┐
│  TASK CHAIN FOR FEATURE "X"                                     │
│                                                                  │
│  Task 1:  X-spec                                                │
│           owner: feature-X                                       │
│           blockedBy: (none)                                      │
│           ↓                                                      │
│  Task 2:  X-spec-review                                         │
│           owner: quality-agent                                   │
│           blockedBy: X-spec                                      │
│           ↓                                                      │
│  Task 3:  X-tests                                               │
│           owner: feature-X                                       │
│           blockedBy: X-spec-review                               │
│           ↓                                                      │
│  Task 4:  X-tests-fail-verify                                   │
│           owner: quality-agent                                   │
│           blockedBy: X-tests                                     │
│           ↓                                                      │
│  Task 5:  X-implement                                           │
│           owner: feature-X                                       │
│           blockedBy: X-tests-fail-verify                         │
│           ↓                                                      │
│  Task 6:  X-tests-pass-verify                                   │
│           owner: quality-agent                                   │
│           blockedBy: X-implement                                 │
│           ↓                                                      │
│  Task 7:  X-validate                                            │
│           owner: feature-X                                       │
│           blockedBy: X-tests-pass-verify                         │
│           ↓                                                      │
│  Task 8:  X-code-review                                         │
│           owner: review-agent                                    │
│           blockedBy: X-validate                                  │
│           ↓                                                      │
│  Task 9:  X-security-scan                                       │
│           owner: security-agent                                  │
│           blockedBy: X-code-review                               │
│           ↓                                                      │
│  Task 10: X-branch-pr                                           │
│           owner: merger-agent                                    │
│           blockedBy: X-security-scan                             │
└────────────────────────────────────────────────────────────────┘

并行执行功能

多个功能的任务链会并行运行。共享 Agent 会在任务解除阻塞时处理任务：

Feature: auth         Feature: dashboard      Feature: payments
  auth-spec             dash-spec               pay-spec
  auth-spec-review      dash-spec-review        pay-spec-review
  auth-tests            dash-tests              pay-tests
  auth-fail-verify      dash-fail-verify        pay-fail-verify
  auth-implement        dash-implement          pay-implement
  auth-pass-verify      dash-pass-verify        pay-pass-verify
  auth-validate         dash-validate           pay-validate
  auth-code-review      dash-code-review        pay-code-review
  auth-security         dash-security           pay-security
  auth-branch-pr        dash-branch-pr          pay-branch-pr
       |                     |                       |
       v                     v                       v
   [All chains run simultaneously]
   [Quality Agent handles all verify tasks as they unblock]
   [Review Agent handles all review tasks as they unblock]
   [Security Agent handles all scan tasks as they unblock]
   [Merger Agent handles all branch-pr tasks as they unblock]

Agent 间通信

直接消息（用于定向工作）

Feature Agent -> Quality Agent:  "Tests written for auth, ready for RED verify"
Quality Agent -> Feature Agent:  "All 7 tests fail as expected. Proceed to implement"
Feature Agent -> Review Agent:   "Implementation complete, ready for code review"
Review Agent  -> Feature Agent:  "2 High issues found: [details]. Fix before proceeding"
Security Agent -> Merger Agent:  "Security scan passed for auth feature"
Merger Agent  -> Team Lead:      "PR #42 created for auth feature"

任务列表（状态的唯一事实来源）

所有 Agent 在完成工作后都会检查 TaskList
Quality Agent 会自动领取验证任务
Review Agent 会自动领取代码审查任务
Security Agent 会自动领取安全扫描任务
Merger Agent 会自动领取分支和 PR 任务

广播（少见——仅用于阻塞问题）

Team Lead -> All：“发现 auth 和 dashboard 之间存在阻塞依赖”
Security Agent -> All：“共享依赖中存在严重漏洞”

创建功能 Agent

团队负责人为每个功能创建一个功能 Agent：

阅读 _project_specs/features/*.md
对每份功能规范，创建一个功能 Agent：
- name：feature-{feature-name}
- 使用 .claude/agents/feature.md 定义
- 创建提示词时包含功能名称和规范位置
为该功能创建完整的 10 个任务依赖链
将编写规范的任务分配给功能 Agent

示例

如果项目有 3 个功能：auth、dashboard、payments

创建：feature-auth、feature-dashboard、feature-payments
总共创建 30 个任务（每个功能 10 个）
每个功能 Agent 都从其规范任务开始
3 个 Agent 并行工作

分支和 PR 策略

每个功能一个分支。每个功能一个 PR。

Branch naming:  feature/{feature-name}
PR title:       feat({feature-name}): {short description}
PR body:        Generated from spec + test results + review + security results

Merger Agent：

git checkout main && git pull origin main
git checkout -b feature/{feature-name}
仅暂存此功能更改的文件（绝不使用 git add -A）
使用描述性提交信息提交，并包含验证结果
git push -u origin feature/{feature-name}
使用完整模板执行 gh pr create，包括：
- 功能规范中的摘要
- 质量验证中的测试结果
- Review Agent 的代码审查摘要
- Security Agent 的安全扫描结果
- 所有流水线步骤均已完成的检查清单

质量门禁

工作流强制执行（通过任务依赖）

任务依赖使跳过步骤在结构上不可能
质量 Agent 完成“tests-fail-verify”之前，功能 Agent 无法看到“implement”
这是主要的强制执行机制

跨 Agent 验证（信任，但要验证）

质量 Agent 独立运行测试（不信任功能 Agent 的报告）
Security Agent 独立扫描（不信任 Review Agent）
Merger Agent 会在创建分支前验证所有前置任务均已完成

阻塞规则

Quality Agent：如果测试未失败（RED）、未通过（GREEN）或覆盖率低于 80%，则阻塞
Code Review Agent：发现严重或高危问题时阻塞
Security Agent：发现严重或高危问题时阻塞
Merger Agent：如果任何前置任务未完成，则拒绝创建分支

与现有技能集成

现有技能	Agent Teams 如何使用
base.md	TDD 工作流、原子化待办事项、简洁性规则——所有 Agent 都遵循
code-review.md	Review Agent 按照此技能执行 `/code-review`
security.md	Security Agent 遵循此技能中的 OWASP 模式
session-management.md	每个 Agent 都维护自己的会话状态
iterative-development.md	功能 Agent 使用 Stop hook TDD 循环进行实现
project-tooling.md	Merger Agent 使用 `gh` CLI 创建分支和 PR
team-coordination.md	已由 agent-teams 取代，用于自动协调
icpg.md	团队负责人创建 ReasonNodes。功能 Agent 查询约束和风险。质量 Agent 检查偏差。PreToolUse hook 注入上下文。Stop hook 自动记录符号。
code-graph.md	功能 Agent 使用图进行符号查找，并结合 iCPG 获取意图上下文

环境设置

必需设置

// settings.json or environment
{
  "env": {
    "agent teams (via .claude/agents/ definitions)": "1"
  }
}

项目结构（由 /initialize-project 创建）

.claude/
  agents/            # Agent definitions (from agent-teams skill)
    team-lead.md
    quality.md
    security.md
    code-review.md
    merger.md
    feature.md
  skills/
    agent-teams/     # This skill
      SKILL.md
      agents/        # Agent definition templates
    base/
    code-review/
    security/
    ...

启动团队

自动启动（通过 /initialize-project）

项目设置完成后，Phase 6 会询问功能需求并自动启动团队。

手动启动（通过 /spawn-team）

对于现有项目：运行 /spawn-team，根据现有功能规范启动团队。

容器隔离（Polyphony）

Docker/OrbStack 可用时，默认在 Polyphony 容器中运行功能 Agent。团队负责人和共享 Agent（质量、安全、审查、合并）仍在本机运行——它们只负责读取和协调。

Polyphony 带来的变化

方面	不使用 Polyphony	使用 Polyphony
功能 Agent	共享文件系统	独立容器 + git 分支
文件冲突	团队负责人必须串行处理	不可能发生（克隆彼此隔离）
测试执行	共享环境，可能互相干扰	每个容器独立运行
分支策略	Merger Agent 创建分支	每个容器都有自己的分支

工作原理

/spawn-team 检测 Docker + polyphony CLI
对每项功能，运行 polyphony spawn "$FEATURE" --type feature
Polyphony 创建一个容器，其中包含独立的 git 克隆和分支
Agent CLI 在容器内启动
完成后，变更位于专用分支上，可用于创建 PR

回退方案

如果 Docker 不可用，/spawn-team 会回退到原生 Agent 工具（共享文件系统）。此时会显示提示：

“未使用容器隔离运行（未找到 Docker）。Agent 共享工作区。”

限制

实验性功能 - Agent 团队需要设置实验性环境变量
不支持嵌套团队 - 团队成员无法启动子团队
每个会话仅限一个团队 - 启动新团队前请先清理
不支持会话恢复 - 如果会话中断，请重新运行 /spawn-team（任务会保留）
文件冲突 - 共享文件的功能必须由团队负责人串行处理（使用 Polyphony 容器时除外）
Token 成本 - 每个 Agent 都是独立的 Claude 实例（5 + N 个实例）

支持 Markdown

登录后评论

基本信息

作者: alinaqi
仓库: alinaqi/maggy
分类: Agent 工作流
安装次数: 291
GitHub Stars: 711

报告问题