工程型多 Agent 协作流水线（plan → implement → test → review → integrate）。 基于 Claude Code 原生能力的主从式多智能体框架：主会话为 Master，每个阶段由独立上下文的子代理执行，靠工件文件交接，由门禁脚本确定性合并。
适用于嵌入式 / 机器人 / 通用软件工程。
完整使用指南（安装 → 初始化 → 流水线 → 故障排查）见 USAGE.md。
# 从 GitHub marketplace 安装（全局，所有项目可用）
claude plugin marketplace add MacroBright/coagent_workflow
claude plugin install coagent-workflow@MacroBright/coagent_workflow
# 仅当前项目启用
claude plugin install coagent-workflow@MacroBright/coagent_workflow --scope project
# 本地开发调试（不安装）
claude --plugin-dir ./coagent_workflow安装后需要新开一个会话（或 /reload-plugins）让命令、子代理与 hooks 生效。
coagent_workflow/
├── .claude-plugin/ # 插件/marketplace 清单（plugin.json + marketplace.json）
├── agents/ # 6 个角色子代理（独立上下文）
│ ├── architect.md # 需求拆解 → 计划 + 接口
│ ├── engineer.md # 实现代码 → handoff
│ ├── tester.md # 编译/测试 → 测试报告
│ ├── reviewer.md # diff 审查 → APPROVE/REJECT
│ ├── debugger.md # bug 调试 → 根因报告
│ └── discoverer.md # 技能/资料检索 → 候选清单
├── commands/ # 9 个命令（Master 执行）
│ ├── init-project.md plan.md implement.md test.md review.md
│ ├── debug.md integrate.md status.md discover.md
├── hooks/
│ ├── hooks.json # 插件 hooks 注册（自动加载）
│ ├── block-hardware.mjs # PreToolUse：高危指令写入前拦截
│ └── session-log.mjs # Stop：会话结束写 docs/session-log.md
├── skills/ # 2 个插件基础设施技能（通用领域技能由 /discover 按项目安装）
│ ├── hardware-safety-checklist/ # 硬件操作强制安全清单
│ └── algorithm-lab-notes/ # 算法实验记录规范 + 模板
├── lib/ # Node 核心库（orchestrator / gate-core / installer / state-schema）
├── bin/
│ ├── gate # 门禁脚本
│ └── coagent # 编排 / 安装 CLI
└── knowledge-repo.md # 知识仓库约定（~/.coagent-knowledge/）
- 技能（skills/） 存"怎么做"：方法、模板、清单。插件只随包分发基础设施技能
（硬件安全清单、实验记录）；通用领域技能在
/init-project或/discover时按项目安装到.claude/skills/。 - 知识仓库（~/.coagent-knowledge/） 存"你实际踩过的"：实例、坑、结论，跨项目积累、私有、git 版本化。约定见
knowledge-repo.md。 - 在每个项目
CLAUDE.md中加入知识仓库引用（见knowledge-repo.md）。
在一个项目的主会话里按顺序执行：
/plan "实现机械臂 CAN 收发驱动"
/implement
/test
/review
/debug # 仅测试/审查发现问题时
/integrate # 门禁判定，通过才合并每个阶段由一个子代理在独立上下文中完成，只通过工件文件交接：
docs/plans/plan-<feature>.md 计划（scope + 验收标准）
docs/design/ 接口定义
docs/plans/handoff-<feature>.md engineer 交接说明
docs/test-reports/report-<feature>.md 含 Result: PASS/FAIL
docs/reviews/review-<feature>.md 含 Verdict: APPROVE/REJECT
docs/debug/bug-<id>.md 调试根因报告
.orchestrator/state.json 流水线状态（stage 指针）
docs/session-log.md 会话台账（Stop hook 自动追加）
/integrate 调用门禁脚本，读取测试报告与审查报告做确定性判定，而非依赖对话记忆：
gate --test-report docs/test-reports/report-<feature>.md \
--review-report docs/reviews/review-<feature>.md \
--handoff docs/plans/handoff-<feature>.md \
--branch feat/<feature> --target main输出 GATE_PASS → 合并；GATE_FAIL → 打回。
新增 flags：--dry-run（只判定不合并）、--json（机器可读）、--handoff（校验 handoff 与审查 HEAD 一致）。
合并前强制工作区干净检查，冲突自动回滚，绝不留半合并状态。
Windows 注意：若
gate不在 PATH 中，可改用node <插件路径>/bin/gate ...。
新增 /status 命令查看当前 stage、各工件路径与下一步建议。state 由 bin/coagent
脚本读写，阶段前置条件由脚本强制（不满足会 REJECT 并说明缺什么）。
阶段语义为最近完成的阶段：idle → plan → implement → test → review → merged，
gate 失败进入 blocked（可 /debug 回退或清理后重跑 /integrate）。
implement/test/review 支持幂等重跑（修复循环 / 报告过期重审）。
测试/审查报告在第 1 行起提供结构化字段区（到空行或标题为止），门禁据此确定性判定：
Report: test-can-driver
Feature: can-driver
Head: a1b2c3d4
Result: PASS # 测试报告；审查报告为 Verdict: APPROVE
/init-project 生成骨架后可自动适配：检索 skills.sh / anthropics / Claude Marketplace /
GitHub 上与项目技术栈相关的候选技能与资料，同时扫描本地技能
（用户级 ~/.claude/skills + 项目 .claude/skills），并支持用户上传本地文档/文件夹
搭入知识库。经确认后项目级安装：
- 技能 →
.claude/skills/<name>/（Claude Code 自动发现；本地来源或联网来源均可） - 开源资料/本地文档 →
docs/knowledge/<name>/+docs/knowledge/INDEX.md（architect 规划输入） - 每个安装写入
.coagent-provenance.json（来源/URL或路径/日期，可审计）
也可随时用 /discover 手动触发。第三方技能含任意指令，安装前请确认并浏览其 SKILL.md。
- Block Hardware hook（PreToolUse）：在 Bash 命令执行前拦截高危操作（烧录、
rm -rf、sudo、直启电机等）。 - 硬件物理安全边界：真实电机/机械臂的安全由硬件级联锁（E-stop、电流限制、力矩上限）保证，本系统只承诺代码层不越权，高危操作需人工确认。
- 模型分层：在
agents/*.md的 frontmatter 中调整model（如 architect/debugger 用opus，其余用默认）。 - 权限规则：插件不随包分发
permissions，请在用户或项目settings.json自行配置 allow/deny。 - 领域技能：插件只分发基础设施技能（硬件安全清单 / 实验记录），通用领域技能用
/discover按项目安装到.claude/skills/。