角色预设

| 预设 | 包含角色 | 适用场景 | |------|---------|---------| | full（默认） | PM、Architect、UI Designer、Tech Lead、Scrum Master、Frontend、Backend、QA、DevOps | 完整项目，质量优先 | | core | PM、Architect、Frontend/Backend、QA | 快速迭代，跳过 UI/评审/拆解层 |

语言规则

所有生成的文档必须使用中文。

Harness 状态机

每个阶段（Stage）遵循以下状态转换：

pending → running → completed
                  → failed → retrying → running → ...
pending → skipped（被 --skip-* 或 --continue-from 跳过）

合法转换：

• pending → running：阶段开始执行
• pending → skipped：阶段被跳过
• running → completed：阶段成功完成
• running → failed：阶段执行失败
• failed → retrying：准备重试
• retrying → running：重试开始
• completed → running：回退重跑

每次状态变更通过 runtime CLI 追加事件并物化 .meta/execution.json。

DAG 驱动工作流

流水线由 Artifact DAG（harness/artifact-dag.json）驱动。每个产物声明其输入依赖和对应 Agent，依赖就绪即可执行，无需等待整个阶段完成。

默认 DAG

design-brief → prd.md → architecture.md ─┬→ tech-review.md → tasks.md → [code] → qa-report.md → deploy-report.md
                       └→ ui-spec.md(opt) ┘

Copy this checklist and check off items as you complete them:

Boss Pipeline Progress:

• [ ] Step -1: 模板初始化（若传入 --template）

  • [ ] -1.1 调用 scripts/init-project.sh <feature-name> --template
  • [ ] -1.2 确认 .boss/templates/ 已创建，并包含默认模板副本
  • [ ] -1.3 提示用户先修改模板，再重新运行 /boss ...
  • [ ] -1.4 ⛔ 本次执行到此结束，不进入 DAG 执行循环

• [ ] Step 0: 需求澄清 ⚠️ REQUIRED (除非 --quick)

  • [ ] 0.1 判断需求完整度：用户给的信息是否包含"做什么 + 给谁用 + 核心场景"？
    • ✅ 三者都有 → 跳到 0.4
    • ❌ 缺任何一项 → 进入 brainstorming
  • [ ] 0.2 Brainstorming 需求澄清：读取 skills/brainstorming/SKILL.md 的流程，以 Boss 的身份执行需求澄清（不需要启动子 Agent，你自己来问）。已有项目先执行 SKILL.md 中的"项目环境感知"步骤，再进入提问环节。一次一个问题，优先给选项，只问业务问题不问技术问题。
  • [ ] 0.3 输出设计简报：澄清完毕后，写入 .boss/<feature>/design-brief.md，向用户确认
  • [ ] 0.4 若不是 --continue-from 且 .boss/<feature>/ 不存在，调用 scripts/init-project.sh <feature-name> 创建占位产物骨架
  • [ ] 0.4a 🎯 Pipeline Pack 自动检测：调用 scripts/harness/detect-pack.sh <project-dir> 自动检测最佳 pipeline pack。若检测到匹配的 pack（非 default），使用该 pack 的 config 覆盖默认配置（agents、gates、skipUI 等）。用户通过 --roles 显式指定时覆盖自动检测结果。
  • [ ] 0.4b 📐 加载 Artifact DAG：读取 harness/artifact-dag.json（或 pipeline pack 自定义 DAG），确定产物依赖图
  • [ ] 0.5 🔌 扫描 harness/plugins/ 目录，识别已注册插件，记录到 execution.json 的 plugins 字段
  • [ ] 0.6 将 design-brief.md（如有）作为上下文传递给后续 Agent
  • [ ] 0.7 Step 0 → DAG 过渡：确认 Step 0 产物已就绪（design-brief 已写入、execution.json 已初始化、DAG 已加载），标记阶段 1 开始：runtime/cli/update-stage.js <feature> 1 running，进入 DAG 执行循环 ↓

• [ ] DAG 执行循环 — 重复以下步骤直到所有产物完成或被跳过：

  • [ ] D.1 查询就绪产物：调用 runtime/cli/get-ready-artifacts.js <feature> --ready --json 获取当前所有输入依赖已满足的产物列表
  • [ ] D.2 阶段状态管理：对就绪产物所属的阶段，若阶段状态为 pending，调用 runtime/cli/update-stage.js <feature> <N> running 标记阶段开始
  • [ ] D.3 准备产物骨架：对每个就绪产物调用 scripts/prepare-artifact.sh <feature-name> <artifact-name>
  • [ ] D.4 并行派发 Agent：
    • Load references/artifact-guide.md 获取产物保存规范
    • 对同一阶段的就绪产物，并行调用对应 Agent（如 architecture.md + ui-spec.md 可并行）
    • 不同阶段的就绪产物也可并行（DAG 保证依赖已满足）
    • 每个 Agent 调用前 Load 对应的 Agent Prompt 文件 + agents/shared/agent-protocol.md + agents/shared/tech-detection.md
    • 🧠 注入 Memory 上下文：调用 runtime/cli/query-memory.js <feature> --agent <agent-name> --json，将返回的相关记忆摘要追加到 Agent 上下文。若无结果则跳过。
    • 若产物为 code，根据任务类型调用 boss-frontend / boss-backend（全栈项目并行），同时 Load references/testing-standards.md
  • [ ] D.5 保存产物：Agent 完成后将产物保存到 .boss/<feature>/
  • [ ] D.6 标记产物完成：调用 runtime/cli/update-stage.js <feature> <N> completed --artifact <name> 记录产物（当阶段内所有产物都完成时标记阶段 completed）
  • [ ] D.7 ❌ 失败处理：若 Agent 失败，先调用 runtime/cli/check-stage.js <feature> <N> --agents 检查哪些 Agent 已完成，仅对失败的 Agent 调用 runtime/cli/retry-agent.js <feature> <N> <agent-name> 重试；若 agent 重试上限已达，才用 runtime/cli/retry-stage.js <feature> <N> 重试整个阶段；若阶段重试上限也达，暂停并报告
  • [ ] D.7a 🔄 反馈循环：若 Agent 报告 REVISION_NEEDED（仅 Tech Lead / QA 可发起）：
    1. 调用 runtime/cli/record-feedback.js <feature> --from <critic-agent> --to <target-agent> --artifact <name> --reason "<原因>" 记录反馈请求
    2. 若返回错误（轮次已达上限），暂停并报告用户
    3. 重新派发目标 Agent 修订上游产物（将修订原因作为额外上下文传入）
    4. 修订完成后，重新派发 Critic Agent 验证
    5. 若验证通过（DONE/DONE_WITH_CONCERNS），结束循环继续 DAG
  • [ ] D.7b ⏱ 超时检测：周期性调用 checkStall(feature, { maxDurationMs }) 检测停滞 Agent。若 Agent 超过阈值（默认 30 分钟）无响应，标记 AgentFailed（reason: timeout）并进入 D.7 失败处理流程。
  • [ ] D.8 确认节点（仅在阶段边界且非 --quick 时）：
    • 阶段 1 完成后 → 确认规划结果 ⚠️ REQUIRED
    • 阶段 3 门禁后 → 可选确认
  • [ ] D.9 🚦 门禁（阶段 3 产物完成后）：
    • 读取 DAG 中 type: "gate" 的条目，对 inputs 已满足的 gate 依次调用 runtime/cli/evaluate-gates.js <feature> <gate-name>
    • gate0：代码质量检查（编译 + Lint + 安全扫描）
    • gate1：测试门禁（覆盖率 + 通过率 + E2E）
    • gate2：性能门禁（Lighthouse + API P99，仅 Web 项目，optional）
    • 扫描 harness/plugins/ 中 type=gate 的插件，依次执行
    • 门禁失败时修复后重新执行门禁
  • [ ] D.10 回到 D.1：重新查询就绪产物，直到 DAG 中所有非跳过产物都已完成
  • [ ] D.11 🧠 记忆提取：DAG 所有产物完成后，调用 runtime/cli/extract-memory.js <feature> 提取本次流水线的关键决策和经验，写入全局记忆库供后续 feature 参考。

• [ ] 收尾

  • [ ] F.1 📊 调用 runtime/cli/generate-summary.js <feature> 生成最终流水线报告
  • [ ] F.2 输出最终结果（文档位置 + 测试摘要 + 门禁结果 + 访问 URL + 流水线耗时）

Agent 角色表

| Agent | 文件 | 职责 | |-------|------|------| | PM | agents/boss-pm.md | 需求穿透，洞悉显性和隐性需求 | | Architect | agents/boss-architect.md | 架构设计、技术选型、API 设计 | | UI Designer | agents/boss-ui-designer.md | UI/UX 设计规范 | | Tech Lead | agents/boss-tech-lead.md | 技术评审、风险评估 | | Scrum Master | agents/boss-scrum-master.md | 任务分解、测试用例定义 | | Frontend | agents/boss-frontend.md | UI 组件、状态管理、前端测试 | | Backend | agents/boss-backend.md | API、数据库、后端测试 | | QA | agents/boss-qa.md | 测试执行、Bug 报告 | | DevOps | agents/boss-devops.md | 构建部署、健康检查 |

Runtime / Internal Helpers

Canonical Runtime Surface

| 编排动作 | Runtime CLI | Runtime API | |---------|-------------|-------------| | 初始化流水线 | runtime/cli/init-pipeline.js | initPipeline(feature) | | 查询 ready artifacts | runtime/cli/get-ready-artifacts.js | getReadyArtifacts(feature, options) | | 阶段状态变更 | runtime/cli/update-stage.js | updateStage(feature, stage, status, options) | | 记录产物 | runtime/cli/record-artifact.js | recordArtifact(feature, artifact, stage) | | Agent 状态变更 | runtime/cli/update-agent.js | updateAgent(feature, stage, agent, status, options) | | 门禁评估 | runtime/cli/evaluate-gates.js | evaluateGates(feature, gate, options) | | 插件注册 | runtime/cli/register-plugins.js | registerPlugins(feature, options) | | 插件 Hook 执行 | runtime/cli/run-plugin-hook.js | runHook(hook, feature, options) | | 阶段状态检查 | runtime/cli/check-stage.js | checkStage(feature, stage, options) | | 事件回放 | runtime/cli/replay-events.js | replayEvents(feature, options), replaySnapshot(feature, at, options) | | Progress 诊断 | runtime/cli/inspect-progress.js | inspectProgress(feature, options) | | 生成流水线报告 | runtime/cli/generate-summary.js | buildSummaryModel(feature), renderMarkdown(model), renderJson(model) | | 生成诊断页 | runtime/cli/render-diagnostics.js | renderHtml(model) |

Internal Shell Helpers

| 辅助脚本 | 用途 | |------|------| | scripts/harness/retry-stage.sh | 阶段重试（检查上限 → retrying → running） | | scripts/harness/retry-agent.sh | 单个 Agent 重试（不重跑整个阶段） | | scripts/harness/detect-pack.sh | Pipeline Pack 自动检测（匹配项目文件） | | scripts/harness/watch-progress.sh | 实时进度监控（tail -f progress.jsonl） | | scripts/harness/record-feedback.sh | Agent 间反馈循环记录（REVISION_NEEDED） | | scripts/gates/gate0-code-quality.sh | Gate 0：代码质量（编译 + Lint） | | scripts/gates/gate1-testing.sh | Gate 1：测试门禁（覆盖率 + 通过率 + E2E） | | scripts/gates/gate2-performance.sh | Gate 2：性能门禁（Lighthouse + API P99） |

Runtime/CLI 编排对照

运行时编排以 runtime/cli/*.js + runtime/cli/lib/pipeline-runtime.js 为准；shell helper 不是 public contract。

Pack 选择与插件生命周期都应进入事件流，而不是停留在 shell 日志里：

• pack 应通过 PackApplied 进入 execution.json read model。
• 插件发现/激活应通过 PluginDiscovered / PluginActivated 进入 pluginLifecycle。
• 插件 hook 执行应通过 PluginHookExecuted / PluginHookFailed 进入 pluginLifecycle。

报告生成也应走 runtime，而不是在 shell 中直接拼接状态：

• runtime/report/summary-model.js 从 execution.json 构建统一 summary model。
• runtime/report/render-markdown.js / runtime/report/render-json.js 负责不同输出格式。
• runtime/report/render-html.js 负责最小 HTML 诊断页。

Claude Code Hooks（Agent 生命周期集成）

Boss Skill 通过 Claude Code 的 hooks 机制，在 Agent 生命周期的关键节点自动介入流水线管控。

所有 hooks 脚本使用 Node.js 实现（跨平台），通过 run-with-flags.js 中间件统一调度。

Hook Profile 分级

通过环境变量控制 hook 的运行级别：

| 环境变量 | 说明 | 值 | |----------|------|-----| | BOSS_HOOK_PROFILE | Hook 运行级别 | minimal / standard（默认）/ strict | | BOSS_DISABLED_HOOKS | 禁用指定 hook | 逗号分隔的 Hook ID，如 post:bash:context,notification:log |

Hook 列表

hooks 定义在两处：

• .claude/settings.json：项目级全局 hooks（SessionStart/End、Notification 等）
• SKILL.md frontmatter：Skill 级 hooks（PreToolUse、PostToolUse、Stop），仅在 Boss Skill 激活时生效

| Hook ID | 事件 | Profile | 作用 | |---------|------|---------|------| | session:start | SessionStart (startup) | all | 检测活跃流水线 + 加载上次 session 状态，注入上下文 | | session:resume | SessionStart (resume) | all | 恢复会话时提示未完成的流水线 | | pre:write:artifact-guard | PreToolUse (Write|Edit) | standard,strict | 阻止直接编辑 execution.json；写入产物时校验阶段状态 | | post:write:artifact-track | PostToolUse (Write) | standard,strict | 文件写入 .boss/ 后自动追加产物事件并物化 execution.json read model | | post:bash:context | PostToolUse (Bash) | standard,strict | 捕获门禁/测试/harness 命令执行，注入上下文 | | subagent:start | SubagentStart | all | 子 Agent 启动时注入当前流水线阶段上下文 | | subagent:stop | SubagentStop | all | 子 Agent 结束后记录执行日志到 agent-log.jsonl | | stop:pipeline-guard | Stop | standard,strict | Agent 停止时检查是否有 running 阶段，阻止过早退出 | | notification:log | Notification (async) | all | 记录通知到流水线日志 notifications.jsonl | | session:end | SessionEnd | all | 保存 session 状态到 .session-state.json，生成报告 |

Session 记忆持久化

• SessionEnd 保存当前 session 状态到 .boss/.session-state.json（feature、pipeline 状态、阶段摘要、cwd/worktree、时间戳）
• SessionStart 加载 .boss/.session-state.json 恢复上下文，使跨 session 的流水线可以无缝继续

Subagent Prompt Templates

调用子代理时，使用标准化的 prompt 模板确保一致性和质量：

| 模板 | 文件 | 用途 | |------|------|------| | 实现者 | agents/prompts/implementer-prompt.md | 派发实现任务的子代理 | | 规格审查 | agents/prompts/spec-reviewer-prompt.md | 审查实现是否符合规格 | | 质量审查 | agents/prompts/code-quality-reviewer-prompt.md | 审查代码质量 | | 协议文档 | agents/prompts/subagent-protocol.md | 状态协议 + 模型选择策略 |

子代理二阶段审查流程：实现 → 规格审查 → 代码质量审查 → 通过/修复

调用 Agent 的标准格式

1. 读取共享协议文件 agents/shared/agent-protocol.md（语言规则、模板优先级、状态协议）
2. 读取技术栈检测协议 agents/shared/tech-detection.md
3. 读取对应的 Agent Prompt 文件（如 agents/boss-pm.md）
4. 将 [共享协议] + [技术栈检测协议] + [Agent Prompt] + 当前任务说��� 组合为 Prompt，调用一个子 Agent 执行
5. 任务说明追加格式：

[共享协议内容]

[技术栈检测协议内容]

[Agent Prompt 文件内容]

---

## Skill 发现

执行任务前，先检查当前环境中可用的 Skill（斜杠命令、插件、扩展等），识别能辅助本任务的能力（如搜索、代码生成、测试、部署等），按需调用以增强执行效果。

## 当前任务

[具体任务描述，包含所需上下文、输入产物路径、输出产物路径]

如果当前任务会生成文档产物，在 ## 当前任务 中额外附加：

## 模板上下文

- 当前产物：`.boss/<feature>/<artifact>.md`
- 产物骨架：已通过 `scripts/prepare-artifact.sh <feature-name> <artifact>.md` 按模板优先级准备完成
- 执行要求：先读取当前产物文件，再在该骨架基础上填充真实内容
- 冲突处理：若骨架结构与 Agent Prompt 中的默认输出格式冲突，以骨架/模板为准

并行调用：需要同时执行多个 Agent 时（如阶段 1 的 Architect + UI Designer、阶段 3 的 Frontend + Backend），在同一步骤内同时发起多个子 Agent 调用，无需等待其中一个完成再启动另一个。

重试机制：若子 Agent 执行失败，优先通过 runtime 状态检查后决定是调用内部 retry-agent.sh 还是 retry-stage.sh；shell helper 只负责执行重试，不承担对外编排语义。若已达上限，暂停并向用户报告失败原因及已完成的产物路径。

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

模板落文：正常执行 /boss 时，先用 scripts/init-project.sh <feature-name> 创建轻量占位文件；真正写某个文档前，再单独调用 scripts/prepare-artifact.sh <feature-name> <artifact-name> 准备当前文档骨架。不要在初始化阶段一次性把全部模板正文落入 .boss/<feature>/。

产物目录结构

.boss/templates/         # 项目级模板（可选，优先于内置 templates/）
.boss/<feature-name>/
├── design-brief.md     # Step 0（brainstorming 产出，可选）
├── prd.md              # 阶段 1
├── architecture.md     # 阶段 1
├── ui-spec.md          # 阶段 1（可选）
├── tech-review.md      # 阶段 2
├── tasks.md            # 阶段 2
├── qa-report.md        # 阶段 3
├── deploy-report.md    # 阶段 4
├── summary-report.md   # 流水线报告（由 Harness 自动生成）
└── .meta/
    └── execution.json  # Harness 执行追踪（状态机 + 门禁 + 指标）

快速开始

当用户触发 Boss Skill 后：

第一步：判断需求完整度

用户的输入是否包含以下三要素？

• ✅ 做什么（要构建的东西是什么）
• ✅ 给谁用（目标用户是谁）
• ✅ 核心场景（用户拿它干嘛）

三个都有 → 直接确认后进入四阶段流水线。

缺任何一个 → 启动 brainstorming 需求澄清（读取 skills/brainstorming/SKILL.md 流程，你自己来问，不用启动子 Agent）。

--quick 模式 → 跳过澄清和所有确认节点，用用户原话直接开跑。

用户典型输入和处理方式：

| 用户说了什么 | 判断 | 处理 | |------------|------|------| | "帮我做个记账 APP" | 缺「给谁用」和「核心场景」 | → brainstorming | | "做一个面向设计师的素材管理工具，能上传、搜索、分类" | 三要素齐全 | → 确认后直接开跑 | | "帮我做个东西" | 什么都缺 | → brainstorming | | "给我们团队做个 API 监控面板，能看延迟和错误率" | 三要素齐全 | → 确认后直接开跑 |

brainstorming 结束后，产出 .boss/<feature>/design-brief.md → 用户确认 → 自动衔接进入四阶段流水线。

🚀 Boss Mode 已激活！（Harness Engine v3.0）

💡 Hook Profile: ${BOSS_HOOK_PROFILE:-standard}
💡 Session 持久化: 已启用

获取信息后，立即开始四阶段流水线。

如果用户使用 --template，则不要进入四阶段流水线，只执行模板初始化并返回：

已初始化项目级模板目录：
- .boss/templates/prd.md.template
- .boss/templates/architecture.md.template
- ...

请先按团队规范修改这些模板，再重新运行 /boss 开始开发。

启动后即可使用 /boss 命令、9 个 Agent、所有 hooks 和 skills。

升级：

npm update -g @blade-ai/boss-skill

工作原理

用户一句话 → [需求澄清] → [PM → Architect → UI] → [Tech Lead → Scrum Master] → [Dev → QA] → [DevOps] → 交付
              Step 0        阶段 1: 规划              阶段 2: 评审+拆解          阶段 3: 开发    阶段 4: 部署

需求澄清（Brainstorming）

用户只说了一句话（如"帮我做个记账 APP"），Boss 会自动判断需求完整度：

| 用户输入 | 判断 | 处理 | |---------|------|------| | "帮我做个记账 APP" | 缺「给谁用」和「核心场景」 | → 自动启动需求澄清 | | "做一个面向设计师的素材管理工具，能上传、搜索、分类" | 三要素齐全 | → 确认后直接开跑 |

三要素检查：做什么 + 给谁用 + 核心场景。缺任何一个就自动触发 brainstorming，把一句话翻译成一页纸的 design-brief.md。

四阶段流水线

• 阶段 1 — 规划：PM 需求穿透 → Architect 架构设计 → UI Designer 设计规范（并行）
• 阶段 2 — 评审：Tech Lead 技术评审 → Scrum Master 任务拆解
• 阶段 3 — 开发：Frontend + Backend 并行开发 → QA 测试 → 质量门禁
• 阶段 4 — 部署：DevOps 构建部署 → 最终报告

每个阶段由 Harness Engine 驱动，状态机追踪，门禁不可绕过。

9 个专业 Agent

| Agent | 职责 | |-------|------| | PM | 需求穿透 — 显性、隐性、潜在、惊喜需求 | | Architect | 架构设计、技术选型、API 设计 | | UI Designer | UI/UX 设计规范 | | Tech Lead | 技术评审、风险评估 | | Scrum Master | 任务分解、测试用例定义 | | Frontend | UI 组件、状态管理、前端测试 | | Backend | API、数据库、后端测试 | | QA | 测试执行、Bug 报告 | | DevOps | 构建部署、健康检查 |

使用方式

触发词：boss mode、/boss、全自动开发、从需求到部署

/boss 做一个 Todo 应用
/boss 用户认证 --template
/boss 给现有项目加用户认证 --skip-ui
/boss 快速搭建 API 服务 --skip-deploy --quick
/boss 继续上次中断的任务 --continue-from 3
/boss 轻量模式 --roles core --hitl-level off

| 参数 | 说明 | |------|------| | --skip-ui | 跳过 UI 设计（纯 API/CLI） | | --skip-deploy | 跳过部署阶段 | | --quick | 跳过确认节点和需求澄清，全自动 | | --template | 初始化项目级模板目录（.boss/templates/）并暂停流水线 | | --continue-from <1-4> | 从指定阶段继续，跳过已完成阶段 | | --hitl-level <level> | 人机协作：auto（默认）/ interactive / off | | --roles <preset> | 角色预设：full（默认，9 个）/ core（PM/Architect/Dev/QA） |

Harness Engine

状态机

每个阶段遵循状态转换：pending → running → completed/failed → retrying → running

状态变更通过 runtime 直接追加到 .meta/events.jsonl，再由 runtime/projectors/materialize-state.js 物化为只读的 .meta/execution.json。

Runtime / CLI 编排面

runtime/cli/*.js 与 runtime/cli/lib/pipeline-runtime.js 是唯一的 runtime-first surface。对外能力以 runtime CLI 为准，不再把 shell wrapper 视为兼容契约。

| 编排动作 | Runtime CLI | |------|------| | 初始化流水线 | runtime/cli/init-pipeline.js | | 查询 ready artifacts | runtime/cli/get-ready-artifacts.js | | 记录产物完成 | runtime/cli/record-artifact.js | | 更新阶段状态 | runtime/cli/update-stage.js | | 更新 Agent 状态 | runtime/cli/update-agent.js | | 执行门禁 | runtime/cli/evaluate-gates.js | | 注册插件 | runtime/cli/register-plugins.js | | 执行插件 Hook | runtime/cli/run-plugin-hook.js | | 检查阶段状态 | runtime/cli/check-stage.js | | 回放事件/快照 | runtime/cli/replay-events.js | | 诊断流水线状态 | runtime/cli/inspect-pipeline.js | | 查看最近事件 | runtime/cli/inspect-events.js | | 查看 progress 流 | runtime/cli/inspect-progress.js | | 查看插件生命周期 | runtime/cli/inspect-plugins.js | | 生成流水线报告 | runtime/cli/generate-summary.js | | 生成诊断页 | runtime/cli/render-diagnostics.js |

Pack 选择和插件生命周期现在都是 runtime 事件，不再只是 shell 侧副作用：

• pack 选择通过 PackApplied 进入状态真相。
• 插件发现/激活通过 PluginDiscovered / PluginActivated 进入事件流。
• 插件 hook 执行通过 PluginHookExecuted / PluginHookFailed 进入事件流。

四期排障 CLI 已开始补齐：

• runtime/cli/inspect-pipeline.js 查看当前阶段、ready artifacts、active agents、pack、plugins、metrics。
• runtime/cli/inspect-events.js 查看最近事件并支持按类型过滤。
• runtime/cli/inspect-progress.js 查看 progress flow。
• runtime/cli/inspect-plugins.js 查看 active/discovered/activated/executed/failed 插件状态。
• runtime/cli/check-stage.js / runtime/cli/replay-events.js 直接承担状态排障和事件回放。

四期报告 runtime 已抽离为独立的 summary model + renderer：

• runtime/cli/generate-summary.js 是 canonical summary surface，默认输出 Markdown，也支持 --json 和 --stdout。
• runtime/report/summary-model.js 负责从 execution.json 构建统一 summary model。
• runtime/report/render-markdown.js 负责渲染 summary-report.md。
• runtime/report/render-json.js 负责渲染机器可读的 JSON 报告。
• runtime/report/render-html.js + runtime/cli/render-diagnostics.js 负责生成最小 HTML 诊断页。

质量门禁

三层门禁，不可绕过：

| 门禁 | 时机 | 检查内容 | |------|------|---------| | Gate 0 | 开发后、测试前 | TypeScript 编译、Lint | | Gate 1 | QA 后、部署前 | 测试覆盖率 ≥ 70%、无 P0/P1 Bug、E2E 通过 | | Gate 2 | 部署前（Web） | Lighthouse ≥ 80、API P99 < 500ms |

支持通过插件扩展自定义门禁。

Hook Profile

通过环境变量控制 hook 运行级别：

| 环境变量 | 说明 | 值 | |----------|------|-----| | BOSS_HOOK_PROFILE | Hook 运行级别 | minimal / standard（默认）/ strict | | BOSS_DISABLED_HOOKS | 禁用指定 hook | 逗号分隔的 Hook ID |

10 个 Node.js hooks 覆盖完整 Agent 生命周期：session 启停、文件读写守卫、bash 命令捕获、子 Agent 调度、流水线退出保护。

子代理协议

所有子代理使用标准化状态报告：

| 状态 | 含义 | |------|------| | DONE | 任务完成 | | DONE_WITH_CONCERNS | 完成但有疑虑 | | NEEDS_CONTEXT | 需要更多上下文 | | BLOCKED | 被阻塞，无法继续 |

Session 记忆持久化

• SessionEnd 保存流水线状态到 .boss/.session-state.json
• SessionStart 加载状态恢复上下文，跨 session 无缝继续

插件系统

通过 harness/plugins/ 注册自定义 gate、agent 或 pipeline 模板包。内置 4 套 Pipeline Pack（default、core、api-only、solana-contract）。

模板系统

Boss 支持项目级模板覆盖：

/boss 用户认证 --template    # 初始化 .boss/templates/

模板查找优先级：.boss/templates/ > 内置 templates/。

产物目录

.boss/<feature>/
├── design-brief.md     # 需求澄清产出（可选）
├── prd.md              # 阶段 1: 产品需求
├── architecture.md     # 阶段 1: 系统架构
├── ui-spec.md          # 阶段 1: UI 规范（可选）
├── tech-review.md      # 阶段 2: 技术评审
├── tasks.md            # 阶段 2: 开发任务
├── qa-report.md        # 阶段 3: QA 报告
├── deploy-report.md    # 阶段 4: 部署报告
├── summary-report.md   # 流水线报告（Harness 自动生成）
└── .meta/
    └── execution.json  # 执行追踪（状态机 + 门禁 + 指标）

开发

环境要求

• Node.js >= 20
• jq（Shell 脚本依赖，brew install jq）

安装与测试

git clone https://github.com/echoVic/boss-skill.git
cd boss-skill
npm install
npm run build
npm run typecheck
npm test

源码与产物布局

• src/ 是 CLI 和 runtime 的 TypeScript/ESM 源码入口。
• dist/ 是 npm publish 和包内 bin 指向的构建产物，不要手改。
• runtime/cli/*.js 与 runtime/cli/lib/*.js 保留为稳定的 ESM wrapper，供 shell/hook 入口继续调用。
• npm test 运行 Vitest；测试文件统一放在 test/**/*.test.ts。

发布

使用统一发布脚本，自动同步所有文件的版本号（package.json、SKILL.md、plugin.json、marketplace.json）：

# 语义化升级
npm run release -- patch          # 3.2.0 → 3.2.1
npm run release -- minor          # 3.2.0 → 3.3.0
npm run release -- major          # 3.2.0 → 4.0.0

# 指定版本号
npm run release -- 3.5.0

# 预览（不改任何文件）
npm run release -- 3.5.0 --dry-run

# 只改版本 + 提交 + tag，不发 npm
npm run release -- 3.5.0 --no-publish

发布流程：检查工作区干净 → 运行测试 → 同步版本号 → 验证一致性 → git commit + tag → npm publish。

详见 CONTRIBUTING.md。

文件结构

boss-skill/
├── src/
│   └── bin/
│       └── boss-skill.ts                # CLI TypeScript 源码
├── dist/
│   └── bin/
│       └── boss-skill.js                # CLI 编译产物（npm bin）
├── SKILL.md                          # 核心编排流程（通用 frontmatter，无平台 metadata）
├── skills/
│   └── brainstorming/
│       └── SKILL.md                  # 需求澄清 Skill
├── agents/                           # 9 个 Agent Prompt
│   ├── boss-pm.md
│   ├── boss-architect.md
│   ├── boss-ui-designer.md
│   ├── boss-tech-lead.md
│   ├── boss-scrum-master.md
│   ├── boss-frontend.md
│   ├── boss-backend.md
│   ├── boss-qa.md
│   ├── boss-devops.md
│   └── prompts/                      # 子代理 Prompt 模板
├── commands/                         # 斜杠命令（/boss、/boss:upgrade）
│   ├── boss.md
│   └── boss-upgrade.md
├── hooks/
│   └── hooks.json                    # Claude Code Plugin hooks（使用 ${CLAUDE_PLUGIN_ROOT}）
├── harness/                          # 流水线编排与插件系统
│   ├── plugin-schema.json
│   ├── plugins/
│   │   └── security-audit/
│   └── pipeline-packs/               # 4 套流水线预设
├── runtime/                          # Canonical runtime surface
│   ├── cli/                          # Runtime CLI 编排命令
│   └── report/                       # 报告生成器
├── references/                       # 按需加载的规范文档
├── templates/                        # 7 个产物模板
├── scripts/
│   ├── release.js                    # 统一发布脚本
│   ├── lib/                          # 共享库（run-with-flags、hook-flags、boss-utils）
│   ├── hooks/                        # 10 个 Node.js Hook 脚本
│   ├── harness/                      # 事件追加、物化、重试等辅助脚本
│   ├── gates/                        # 具体 gate 实现脚本
│   └── report/                       # 报告相关脚本
├── .claude-plugin/
│   ├── plugin.json                   # Claude Code Plugin 清单
│   └── marketplace.json
└── package.json

设计理念

基于 BMAD（Breakthrough Method of Agile AI-Driven Development）方法论，详见 references/bmad-methodology.md 和 DESIGN.md。

贡献

欢迎贡献！请阅读 [CONTRIBUTING.