sdd-team — AI 多 Agent 开发团队

平台中立的多 Agent 研发管线。5 角色（产品/项目/架构/开发/测试）按需求难度自动选流程，以 docs/<module>/ 文档为载体，guard.mjs 为机器门禁。

深度介绍与原理分析见 PROJECT.md

安装

前置： Node.js ≥18。各平台需预装 Superpowers 插件（brainstorming / writing-plans / test-driven-development / systematic-debugging / verification-before-completion）。

方式零：npx 零安装（推荐）

npx sdd-team                          # 交互式：选全局/项目 + 平台
npx sdd-team --mode project --root <目标> --tools claude    # → <目标>/.claude/
npx sdd-team --mode project --root <目标> --tools opencode  # → <目标>/.opencode/ (自动生成 opencode.json)
npx sdd-team --mode project --root <目标> --tools codex     # → <目标>/.codex/
npx sdd-team --mode global --tools all                      # 一次装到用户目录，全项目可用
npx sdd-team --mode global --tools claude --yes             # 非交互（-y 按默认值）

已发布至 npm（[email protected]），无需 clone 仓库；npx sdd-team@latest 始终拉最新版。

方式一：源码项目级（装进目标项目）

cd <本仓库根>
node scripts/bootstrap.mjs                          # 交互式
node scripts/bootstrap.mjs --root <目标> --tools claude    # → <目标>/.claude/
node scripts/bootstrap.mjs --root <目标> --tools opencode  # → <目标>/.opencode/ (自动生成 opencode.json)
node scripts/bootstrap.mjs --root <目标> --tools codex     # → <目标>/.codex/

方式二：源码用户级（一次安装，所有项目可用）

node scripts/install-user.mjs --tools all
node scripts/install-user.mjs --tools claude|pi|opencode|codex
node scripts/install-user.mjs --uninstall --tools all

源码用户级为 junction/符号链接，源仓库更新即时生效。

使用

cd <目标项目>
/team <需求>    # 启动：分诊 → 选flow → 逐阶段交付
/team resume    # 断点续跑
/team status    # 状态查看

快捷调用（不走 workflow，临时任务）：

/team-pm <任务>    # 产品经理：澄清/分诊/SPEC
/team-plan <任务>  # 项目经理：PLAN
/team-swa <任务>   # 架构师：DESIGN
/team-dev <任务>   # 开发：TDD/修Bug
/team-qa <任务>    # 测试：REVIEW

使用规则（硬约束）

1. 读取纪律 — 按需读，不全量

| 阶段 | 允许读取 | 禁止 | |------|----------|------| | 编排器 triage 前 | ls + git ls-files \| head -30 指纹、docs/intent.json、docs/*/SPEC-*.md、workflows/*.json（≤5次） | Glob **/* 全量遍历、逐文件 Read | | 子 agent | 按 agents/*.md 读取纪律（PM不读DESIGN/PLAN，架构师XL才读码，开发按PLAN切片） | 越权读下游产物 |

阶段间传文件路径，不塞全文。详见 AGENTS.md。

2. 流程与门禁 — guard 强制，非提示词自律

# 源仓库根（未 bootstrap）：node scripts/guard.mjs ...
# 安装后在项目根（三选一）：
node .claude/scripts/guard.mjs --init --run-id <slug> --flow <flow-id>    # Claude (.claude/)
# node .opencode/scripts/guard.mjs --init --run-id <slug> --flow <flow-id> # Opencode (.opencode/)
# node .codex/scripts/guard.mjs --init --run-id <slug> --flow <flow-id>     # Codex (.codex/)
node .claude/scripts/guard.mjs handoff --enter <stage>   # 顺序校验+锁输入hash
node .claude/scripts/guard.mjs <gate> --write            # build|verify|review|plan
node .claude/scripts/guard.mjs handoff --write [--force] # 漂移+门禁必跑+产出契约

• build/verify 无 package.json 脚本记 UNVERIFIED（非通过），handoff --write 需 --force 显式豁免
• spec 必须产出 SPEC-*.md，architecture 必须产出 DESIGN-*.md，approve 必须 APPROVAL-*.json {approved:true}
• handoff --enter 精确输入缺失直接 BLOCK；输入 hash 漂移（BOM/换行也算）直接 BLOCK

3. 目录与产物

<目标>/
├── docs/
│   ├── intent.json              # 分诊：{difficulty, flow, module, summary}
│   ├── <module>/SPEC-*.md       # 契约（AC/Out of Scope/Glossary/Decision）
│   ├── <module>/DESIGN-*.md     # 技术设计
│   ├── <module>/PLAN-*.md       # 实施计划（AC追溯）
│   ├── <module>/REVIEW-*.json   # 验收 {blockers, verdict, findings: ["AC-01: PASS ..."]}
│   ├── knowledge/LESSONS.md     # 跨run记忆（分诊/写spec/验收前必读）
│   ├── review/APPROVAL-*.json   # 人工审批
│   └── scratch/<slug>/clarify.md # 模糊需求决策清单
└── .claude/ (.opencode/.codex)  # 平台目录：agents/skills/workflows/scripts

模块文件夹 docs/<module>/ 由分诊时 intent.json: module 决定，同模块多需求聚合。

4. Workflow 选型

| 难度 | 信号 | 阶段 | 数 | |------|------|------|----| | S | 单文件/小改动 | develop | 1 | | M | 多文件/新功能 | spec → develop | 2 | | L | 新模块/跨模块 | spec → develop → qa | 3 | | XL | 架构/安全/大迁移 | spec → arch → ticket → develop → qa → approve | 6 |

workflows/flow-*.json 声明式定义，改流程只改 JSON。

命令参考

| 命令 | 作用 | |------|------| | /team <需求> | 启动完整管线 | | /team resume | 断点续跑（guard --probe 探测） | | /team status | guard --status 仪表盘 | | node scripts/guard.mjs --probe | 0=可续跑 1=已完成 2=无run | | node scripts/benchmark.mjs | 评估回归 list/record/report | | node scripts/check-skills.mjs | 检测 Superpowers 插件 |

目录结构

 源仓库/                          安装后 <目标>/
 ├── agents/ (5角色)               ├── docs/ (产物+记忆+checkpoints/acp/observability)
 ├── skills/team*                  ├── .claude/ (agents/skills/workflows/scripts)
 ├── scripts/guard.mjs             └── AGENTS.md (薄定向，不整仓探索)
 ├── workflows/flow-*.json
 └── settings.json

更多原理见 PROJECT.md。