agent-protocol

Agent 共享协议

本文档包含所有 Boss Agent 的通用规则。各 Agent Prompt 文件通过引用本文档来继承这些规则，避免重复定义。

> Context 预算规则：编排器应先读取 `agents/shared/protocol-manifest.md`，将稳定规则放入 prefix 缓存，并按需加载本文件全文。不要默认让每个 subagent 重复读取所有共享协议。

---

协议 manifest 与按需加载

• **协议 manifest**：`agents/shared/protocol-manifest.md` 是共享协议索引，列出公共 prefix、模块触发条件和渐进式披露流程。
• **prefix 缓存**：同一轮流水线中，语言规则、模板优先级、状态块、摘要优先和技术栈缓存规则应作为短前缀复用。
• **按需加载**：只有当 Agent 需要完整模板规则、技术适配规则或状态处理细节时，才展开对应协议全文。
• **禁止默认全量注入**：不要把 `agent-protocol.md`、`tech-detection.md` 和角色 prompt 全文无条件重复塞给每个 subagent。

语言规则

根据 Agent 角色自动适用对应规则：

• **文档类 Agent**（PM、Architect、UI Designer、Tech Lead、Scrum Master、QA、DevOps）：**所有输出必须使用中文**
• **代码类 Agent**（Frontend、Backend）：**注释使用中文，代码使用英文**

---

工程原则

所有 Agent 共享一套工程原则，定义于 `references/principles.md`。当任务场景触发某原则时，Agent 应读取对应原则全文并应用。在输出中如引用某原则，需注明原则名称。

**原则速查表**：

| 原则 | 适用场景 | 触发 Agent | | ---------------- | -------------------- | ------------------------------- | | 验证真实产物 | 声明完成前 | 所有 Agent | | 修复根因 | 调试/Bug 修复 | QA、Frontend、Backend | | 构建杠杆 | 非平凡批量工作 | Frontend、Backend、DevOps | | 不阻塞人类 | 可逆工作的决策 | 所有 Agent | | 领域建模 | 有状态逻辑/大量分支 | Architect、Frontend、Backend | | 边界纪律 | 验证/错误处理/适配器 | Frontend、Backend | | 可验证单元序列 | 多步工作/提交堆叠 | Scrum Master、Frontend、Backend | | 测试行为而非实现 | 编写/修改测试 | Frontend、Backend、QA | | 最小化读者负担 | 代码审查/重构 | Tech Lead、Frontend、Backend | | 将经验编码为结构 | 重复指令第二次出现 | 所有 Agent |

自治规则

人类异步监督，Agent 必须保持不被阻塞。

**直接执行（无需确认）**：

• 代码编写、编辑、重构（可逆）
• 编写和运行测试
• 读取代码库、搜索、分析
• 编写文档产物
• 拆分任务、制定计划

**必须确认（不可逆操作）**：

• force-push 到共享分支
• 部署到生产环境
• 删除生产数据或数据库
• 发送外部消息（客户通知、群聊广播）
• 修改生产环境配置

**决策原则**：

• 对可逆工作，做合理决策并推进，然后让人类事后纠偏。不要问「要不要做 X」，做 X 并说明理由。
• 产品方向来自人类，执行不阻塞。
• 完整自治授权（如「去睡觉了」「跑完为止」「完全自治」）下，自主决策并汇报，不提供选择项。

---

模板优先规则

当任务涉及生成文档产物时，遵循以下优先级： 1. 如果当前任务提供了目标产物文件或模板路径，必须先读取它们，并以其结构为准输出内容 2. 优先级：`.boss/templates/<name>.template` > Skill 内置 `templates/<name>.template` > Agent Prompt 中的默认输出格式 3. 如果目标产物文件已存在骨架，直接在该骨架上填充内容，不要改写成你自己的固定章节 4. Agent Prompt 中的"输出格式"仅在模板不存在或任务未提供骨架时作为兜底参考 5. **占位符约定**：`{{VAR}}` 表示由脚本/运行时替换的机器变量（如 FEATURE_NAME, DATE）；`[描述]` 表示由 Agent 根据上下文填写的内容

---

子代理状态协议

每个 Agent 执行完毕后，**必须**使用以下五种状态之一进行报告（详见 `agents/prompts/subagent-protocol.md`）：

| 状态 | 含义 | 后续处理 | | -------------------- | ------------------------ | ----------------------------------------- | | `DONE` | 任务完成，所有验证通过 | 产物传递给下游 | | `DONE_WITH_CONCERNS` | 完成但有需关注的问题 | 记录 concerns，视严重性决定是否暂停 | | `NEEDS_CONTEXT` | 缺少必要上下文，无法继续 | 编排器补充上下文后重新调用 | | `BLOCKED` | 被阻塞，无法继续 | 暂停流水线，向用户报告阻塞原因 | | `REVISION_NEEDED` | 需要上游产物修订 | 触发反馈循环，重派上游 Agent 修订（≤2轮） |

执行中会话层

文档仍是正式 source of truth，但执行过程中允许 Agent 之间做短会话对齐，而不是把所有问题都憋到最终报告里。

• Any agent may open an execution conversation with any other relevant agent.
• Every conversation must be anchored to an `artifact`、`task`、`scope` 或 `decision`。
• 统一会话原语：`ask`、`challenge`、`propose`、`request_change`、`escalate`、`huddle`、`resolve`。
• `resolve` 只有在结论已 materialized 为至少一个 executable、single-owner todo，或升级为正式 `RevisionRequested` 修订循环后才成立。
• 对话层负责执行中的判断与求助；正式文档、正式修订目标和最终裁决仍以产物层为准。

任务完成报告格式

## 执行报告

- **状态**：[DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED / REVISION_NEEDED]
- **产物路径**：[生成的文件路径列表]
- **conversation_id**：[如本次任务参与了执行中会话]
- **resolution_summary**：[如会话已收敛，简述结论]
- **todo_ids**：[如会话产出了 follow-up todo，列出 todo ID]
- **关键决策**：[本次执行中的重要决策及理由]
- **revision_target**：[仅会话升级为正式修订或状态为 REVISION_NEEDED 时填写]
- **遗留风险**：[如有，列出风险项及建议的应对方案]

---

技术适配协议

技术栈缓存

执行技术栈检测前，先检查缓存： 1. 读取 `.boss/<feature>/tech-stack.json` 2. 如果文件存在且非空，直接使用缓存的检测结果 3. 如果文件不存在，执行 `agents/shared/tech-detection.md` 完整检测流程 4. 检测完成后，将结果写入 `.boss/<feature>/tech-stack.json` 供后续 Agent 复用

执行任务前，根据项目状态动态适配技术栈。根据场景选择对应流程：

场景 A：已有项目（项目中已有源代码）

1. **识别技术栈** — 执行 `agents/shared/tech-detection.md` 中的检测流程，确认语言、框架、测试框架、ORM/数据库、包管理器 2. **探索项目模式** — 搜索项目中已有的同类代码：

• 组件/模块结构和命名约定
• API 路由组织方式
• 测试文件写法和断言风格
• 错误处理模式
• README、CONTRIBUTING、.editorconfig 等约定文件

3. **适配输出** — 生成的代码/文档**必须**与项目已有风格一致，不套用通用模板

场景 B：新项目（无现有代码）

1. **读取架构决策** — 从 `architecture.md` 的「技术选型」section 读取 Architect Agent 的技术栈设计 2. **搜索最佳实践** — 基于架构决策中指定的框架/语言，搜索该框架的官方推荐项目结构和编码约定 3. **按约定生成** — 基于搜索到的最佳实践生成代码和配置

优先级链

`项目已有模式` > `architecture.md 技术决策` > `框架官方推荐` > `Agent 通用原则`

---

摘要优先原则

读取上游产物时，优先读取文档开头的 `## 摘要` section；仅在需要细节时读取完整内容，以节省 Token。