@colin4k1024/tsp 2.4.4 → 2.4.6

package/docs/runbooks/codex-end-to-end-conversation-example.md

@@ -1,166 +0,0 @@
----
-version: "0.1.0"
-status: draft
-created: 2026-03-28
-updated: 2026-03-28
-owner: 工程团队
----
-
-# Codex 完整对话样例
-
-本文给出一份偏 Codex 使用方式的成品对话样例，重点展示“主链 + 并行分析 + handoff 收口”是怎样串起来的。
-
-## 1. 场景
-
-- 任务：修复控制台首页在 iPad 横屏下的布局溢出
-- 范围：页面布局、响应式回归、UI 验证清单
-- 不做：接口与数据结构改造
-- 约束：必须遵守 frontend-quality-gates
-
-## 2. 第一步：用户先做 intake
-
-用户可以这样说：
-
-```text
-/team-intake
-目标：修复控制台首页在 iPad 横屏下的布局溢出
-范围：页面布局、响应式回归、UI 验证清单
-不做：接口与数据结构改造
-约束：必须遵守 frontend-quality-gates
-```
-
-期望得到的结果至少包含：
-
-```text
-参与角色
-- tech-lead
-- frontend-engineer
-- qa-engineer
-
-主要风险
-- iPad 横屏下卡片栅格断裂
-- 修复后可能影响移动端按钮折行
-
-下一步建议
-- 进入 /multi-frontend，从实现、UI/UX、QA 三个视角并行拆解
-```
-
-## 3. 第二步：用户要求并行拆解
-
-```text
-/multi-frontend
-基于当前 intake 结果，从实现、UI/UX、QA 风险三个视角拆解工作。
-要求指出哪些结论必须进入最终 handoff。
-```
-
-期望得到的结果应分成两层：
-
-```text
-各视角结论
-- 实现：问题出在栅格列宽和容器最小宽度冲突
-- UI/UX：修复时需保留按钮层级和空态布局
-- QA：重点验证 iPad 横屏、移动端折行和低分辨率桌面
-
-必须进入 handoff 的内容
-- 修复点：栅格列宽策略调整
-- 验证点：iPad 横屏、移动端、桌面端
-- 风险：低分辨率桌面可能出现按钮折行
-```
-
-## 4. 第三步：用户要求回收到 handoff
-
-```text
-请把上面的多 agent 结论整理成一次正式 /handoff。
-不要重复每个 agent 的原话，只保留已确认结论、风险与依赖、下一角色动作清单。
-```
-
-期望得到：
-
-```text
-已确认结论
-- 布局溢出由栅格列宽和容器最小宽度冲突导致
-
-风险与依赖
-- 修复后需回归移动端和低分辨率桌面
-
-下一角色动作清单
-- frontend-engineer 调整栅格策略并补 UI 自测
-- qa-engineer 按 iPad 横屏、移动端、桌面端进行回归
-```
-
-## 5. 第四步：用户要求 execute
-
-```text
-/team-execute
-按当前结论执行前端修复。
-输出改动摘要、自测结论、待 QA 关注点，以及需要进入 review 的内容。
-```
-
-期望得到：
-
-```text
-改动摘要
-- 调整首页栅格列宽和容器最小宽度
-- 保持按钮区层级和空态布局不变
-
-自测结论
-- 桌面端、iPad 横屏、移动端已验证
-- ui-review-checklist 已补齐
-
-待 QA 关注点
-- 低分辨率桌面是否出现按钮折行
-```
-
-## 6. 第五步：用户要求 review
-
-```text
-/team-review
-基于当前 handoff 和 execute 结果，输出评审结论、阻塞项、放行建议和残余风险。
-```
-
-期望得到：
-
-```text
-评审结论
-- 结论：通过
-
-阻塞项
-- 无
-
-残余风险
-- 暂无新的结构性风险
-
-放行建议
-- 可合并，并保留一次低分辨率桌面 smoke
-```
-
-## 7. 第六步：如果需要发布收口
-
-如果这是一个高风险修复，用户还可以继续：
-
-```text
-/team-release
-基于当前测试结论，整理发布方案、观察窗口、回滚条件和责任链。
-如果需要 GitLab 手动流水线或 Langfuse 追踪，也请说明。
-```
-
-期望得到：
-
-```text
-发布方案
-- 先在 staging 验证，再进入小流量观察
-
-观察窗口
-- 重点观察首页渲染错误率和关键点击链路
-
-回滚条件
-- 布局异常回归或关键页面不可用
-```
-
-## 8. 这份样例说明了什么
-
-- Codex 的关键优势不是“多跑 agent”，而是“并行后还能回收成 handoff”
-- 用户在 Codex 里最好显式要求哪些结论必须进入 handoff 或 review
-- 小任务可以不走超长主链，但验证与收口不能省
-
-如果你想直接复制 Codex 的高频表达方式，继续看 [codex-parallel-prompt-recipes.md](codex-parallel-prompt-recipes.md)；如果你想看更完整的并行原则，继续看 [codex-multi-agent-orchestration.md](codex-multi-agent-orchestration.md)。

package/docs/runbooks/codex-multi-agent-orchestration.md

@@ -1,65 +0,0 @@
----
-version: "0.1.0"
-status: draft
-created: 2026-03-28
-updated: 2026-03-28
-owner: 工程团队
----
-
-# Codex 多 Agent 编排指南
-
-本文聚焦 Codex 中最有价值的能力：把多角色和 specialist 并行跑起来，再把结果结构化收口。
-
-## 1. 何时值得并行
-
-- 前后端都要动
-- 方案、实现、测试可以部分并行
-- 单个任务信息量大，串行代价高
-
-## 2. 推荐并行组合
-
-### 2.1 全栈任务
-
-- architect
-- frontend-engineer
-- backend-engineer
-- qa-engineer
-
-### 2.2 专项分析
-
-- tech-lead + planner
-- engineer + code-reviewer
-- engineer + build-error-resolver
-
-## 3. 并行前先锁定什么
-
-- 目标
-- 范围外事项
-- 依赖关系
-- 最终由谁收口
-
-如果这些不清楚，并行只会制造更多平行结论。
-
-## 4. 并行后的收口方式
-
-推荐流程：
-
-1. 每个 agent 只产出本角色视角结果
-2. 用 `/handoff` 汇总关键结论
-3. 由 tech-lead 或主链角色做最终合并
-
-## 5. 冲突怎么处理
-
-如果多 agent 给出冲突结论，优先按以下顺序处理：
-
-1. 架构与约束优先
-2. 阻塞性风险优先
-3. 最终由 tech-lead 裁决
-
-## 6. 常见错误
-
-- 没有依赖关系，盲目并行
-- 结果很多，但没有统一 handoff
-- 把 specialist 当作某个角色的替代者
-
-如果你需要更细的 specialist 分工，继续看 [specialist-commands-playbook.md](specialist-commands-playbook.md)。

package/docs/runbooks/codex-parallel-prompt-recipes.md

@@ -1,131 +0,0 @@
----
-version: "0.1.0"
-status: draft
-created: 2026-03-28
-updated: 2026-03-28
-owner: 工程团队
----
-
-# Codex 并行编排提示模板
-
-本文聚焦 Codex 里最常见的几种并行表达方式：什么时候该让多个 specialist 并行跑，什么时候必须先收口回主链。
-
-如果你想先看命令全景和对应能力，先读 [command-and-capability-matrix.md](command-and-capability-matrix.md)。如果你想先理解 observation、budget、compact、cost、instinct 这些后台机制，读 [runtime-capabilities-overview.md](runtime-capabilities-overview.md)。
-
-## 1. 先 intake，再决定是否并行
-
-```text
-先按 /team-intake 锁定目标、范围、约束和参与角色。
-只有在 intake 明确存在多视角或多子系统时，再建议进入 /multi-* 或其他 specialist。
-```
-
-适用场景：避免一上来就并行跑很多 agent，结果没有统一入口。
-
-## 2. 前端多视角并行
-
-```text
-/multi-frontend
-基于当前 intake 结果，从实现方案、UI/UX 风险、QA 验证三个视角并行拆解。
-输出时请分成两部分：
-1. 各视角结论
-2. 哪些内容必须进入最终 /handoff
-```
-
-适用场景：前端页面改动同时涉及实现、体验和验收门禁。
-
-## 3. 后端多子系统并行
-
-```text
-/multi-backend
-基于当前 intake 或 plan，把接口实现、权限边界、测试策略三部分并行分析。
-如果命中 私有流程或权限集成，请明确说明是 custom overlay 还是仅保留为候选项。
-最终请整理出可直接回写 /team-plan 的结果。
-```
-
-适用场景：后端任务跨接口、权限和 company 边界时。
-
-## 4. 复杂任务先规划再并行
-
-```text
-/plan
-请先把当前任务拆成阶段、角色职责、依赖和风险。
-然后指出哪些阶段适合并行，哪些阶段必须串行。
-输出最后补一段：建议用哪个 /multi-* 或 specialist，以及为什么。
-```
-
-适用场景：任务很大，但你不想凭感觉决定怎么并行。
-
-## 5. 并行结果回收到 handoff
-
-```text
-请把上面的多 agent 结论整理成一次正式 /handoff。
-不要重复每个 agent 的原话，只保留：
-- 已确认结论
-- 未决问题
-- 风险与依赖
-- 下一角色动作清单
-```
-
-适用场景：这是 Codex 最重要的一步，避免 specialist 输出散落在上下文里。
-
-## 6. 并行后进入 review
-
-```text
-基于当前 handoff，继续执行 /team-review。
-如果前面有 specialist 结论，请只保留那些会影响评审结论、阻塞项和放行建议的内容。
-```
-
-适用场景：多 agent 分析完成后，要把 review 聚焦在放行判断，而不是重复过程。
-
-## 7. 发布阶段的并行补充
-
-```text
-基于当前 release 输入，先判断是否需要 GitLab 手动流水线、Langfuse 追踪或其他 company/runbook 补充。
-如果需要，请给出它们在 /team-release 中的回写方式；如果不需要，也请明确说明原因。
-```
-
-适用场景：发布阶段要补企业扩展，但不想让扩展能力抢走主链。
-
-## 8. 构建失败时的编排方式
-
-```text
-先用 /build-fix 定位当前构建失败原因。
-如果修复路径仍不清楚，再补 /verify 或 /code-review。
-最后请把结论整理成可直接回到 /team-execute 的动作清单。
-```
-
-适用场景：构建故障最容易无限分叉，这个模板强调先收敛，再继续。
-
-## 9. 先测试后并行的编排方式
-
-```text
-先基于当前 /team-plan 结果执行 /tdd，锁定测试、边界和成功标准。
-只有当实现阶段明确存在多子系统或多视角时，再进入 /multi-*。
-最后请把 /tdd 和 /multi-* 的结论合并成一次正式 /handoff。
-```
-
-适用场景：任务既复杂又容易返工，先锁测试再并行能减少分叉。
-
-## 10. 平台能力自检的编排方式
-
-```text
-/harness-audit
-请从命令覆盖、skills 完整度、hooks 有效性、文档同步、集成深度五个方向审视当前平台。
-输出时按优先级分成：
-1. 必须立刻修补
-2. 可下一轮收敛
-3. 仅记录观察
-最后把高优先级项整理成文档、命令、skills、hooks 四类动作。
-```
-
-适用场景：仓库最近做过大规模能力扩充，想快速审视还有哪些入口没有同步。
-
-## 11. 常见错误
-
-- 并行前没有先做 intake，导致目标和范围不统一
-- 并行结果直接当最终结论，没有回写 handoff
-- overlay、runbook、toolkit 只在 specialist 里提到，没有进入 review 或 release 正式输出
-- 平台治理问题没有用 `/harness-audit`，反而拆成很多零散 specialist，导致结论分散
-- 任务明显适合 `/tdd`，却直接并行实现，导致后面还要回头补测试标准
-
-如果你想先看 Codex 的整体使用节奏，回到 [codex-workflow-essentials.md](codex-workflow-essentials.md)；如果你想看更短的主链骨架，回到 [team-commands-quick-prompts.md](team-commands-quick-prompts.md)；如果你想知道 specialist 的边界，继续看 [specialist-commands-playbook.md](specialist-commands-playbook.md)。

package/docs/runbooks/codex-quick-start.md

@@ -1,223 +0,0 @@
----
-version: "2.3.0"
-status: draft
-created: 2026-03-28
-updated: 2026-04-18
-owner: 工程团队
-doc_tier: entry
-last_verified: 2026-04-18
-source_of_truth:
-  - ../../README.md
-  - ../../AGENTS.md
-  - ./team-skills-usage.md
----
-
-# Codex 快速上手
-
-本文面向第一次把 Team Skills Platform 安装到 Codex 的使用者，重点说明插件目录、验证方式，以及如何在 Codex 中跑通主链、specialist 组合与新增的平台审计能力。
-
-## 1. 安装
-
-```bash
-node scripts/build-platform-artifacts.js
-CODEX_HOME_DIR="$HOME/.codex" AGENTS_HOME_DIR="$HOME/.agents" ./scripts/install-codex.sh
-```
-
-安装完成后会：
-
-- 把完整插件复制到 `$CODEX_HOME_DIR/plugins/team-skills-platform/`
-- 把 marketplace 合并到 `$AGENTS_HOME_DIR/plugins/marketplace.json`
-
-## 2. 校验安装是否成功
-
-至少确认以下路径存在：
-
-- `$CODEX_HOME_DIR/plugins/team-skills-platform/commands/team-help.md`
-- `$CODEX_HOME_DIR/plugins/team-skills-platform/agents/roles/tech-lead.md`
-- `$CODEX_HOME_DIR/plugins/team-skills-platform/examples/project-CLAUDE.md`
-- `$AGENTS_HOME_DIR/plugins/marketplace.json` 中含有 `team-skills-platform`
-
-如果命令或 agent 不可用，先检查：
-
-- `CODEX_HOME_DIR` 和 `AGENTS_HOME_DIR` 是否指向了正确目录
-- 是否重新运行了构建脚本
-- 是否误以为 Codex 只需要 `marketplace.json` 而不需要插件目录
-
-如果还没有定位到问题，继续看 [troubleshooting.md](troubleshooting.md)。
-
-### 2.1 可选能力检查：Graphify / GitNexus
-
-如果你准备在 brownfield 项目中启用代码图谱能力，安装后可以先做预检查：
-
-```bash
-npm run graphify:doctor
-npm run gitnexus:doctor
-```
-
-预检查仅验证环境，不会自动安装依赖。Graphify 适合轻量结构证据，GitNexus 适合 MCP 查询、impact 和 detect_changes；若失败，按 [troubleshooting.md](troubleshooting.md) 的对应章节处理。
-
-## 3. 在 Codex 中的推荐使用方式
-
-Codex 更适合把“主链 + specialist”连起来连续执行，所以建议按下面的节奏工作：
-
-1. 先用 `/team-help` 判断当前应该进入 intake、plan，还是先补 brownfield / memory / readiness 证据
-2. 用 `/team-intake` 锁定目标、范围和约束
-3. 用 `/team-plan` 拆角色责任与 handoff 交付物
-4. 用 `/multi-frontend`、`/multi-backend`、`/plan` 做专项分析
-5. 用 `/handoff` 把专项结论收回主链
-6. 用 `/team-review` 或 `/team-release` 收口
-
-如果你准备长期接入某个项目，建议先选一个项目级样例再改，而不是从空白文件开始：
-
-- 通用项目样例：[../../examples/project-CLAUDE.md](../../examples/project-CLAUDE.md)
-- Next.js SaaS 样例：[../../examples/saas-nextjs-CLAUDE.md](../../examples/saas-nextjs-CLAUDE.md)
-- Spring Boot 服务样例：[../../examples/springboot-service-CLAUDE.md](../../examples/springboot-service-CLAUDE.md)
-- 流程型企业项目样例：[../../examples/workflow-enterprise-CLAUDE.md](../../examples/workflow-enterprise-CLAUDE.md)
-- 平台治理仓库样例：[../../examples/platform-governance-CLAUDE.md](../../examples/platform-governance-CLAUDE.md)
-- 数据看板项目样例：[../../examples/data-analytics-dashboard-CLAUDE.md](../../examples/data-analytics-dashboard-CLAUDE.md)
-- GitHub Actions / 供应链治理仓库样例：[../../examples/github-actions-supply-chain-CLAUDE.md](../../examples/github-actions-supply-chain-CLAUDE.md)
-- AI / Eval 平台样例：[../../examples/ai-eval-platform-CLAUDE.md](../../examples/ai-eval-platform-CLAUDE.md)
-- 移动端 / 小程序项目样例：[../../examples/mobile-miniapp-CLAUDE.md](../../examples/mobile-miniapp-CLAUDE.md)
-- IaC / Kubernetes 平台仓库样例：[../../examples/iac-kubernetes-platform-CLAUDE.md](../../examples/iac-kubernetes-platform-CLAUDE.md)
-- 插件 / 扩展仓库样例：[../../examples/plugin-extension-platform-CLAUDE.md](../../examples/plugin-extension-platform-CLAUDE.md)
-- 数据 / ML pipeline 仓库样例：[../../examples/data-ml-pipeline-CLAUDE.md](../../examples/data-ml-pipeline-CLAUDE.md)
-- 安全 / 合规平台仓库样例：[../../examples/security-compliance-platform-CLAUDE.md](../../examples/security-compliance-platform-CLAUDE.md)
-- 内部开发者平台样例：[../../examples/internal-developer-platform-CLAUDE.md](../../examples/internal-developer-platform-CLAUDE.md)
-- 数据可观测性 / 质量平台样例：[../../examples/data-observability-quality-CLAUDE.md](../../examples/data-observability-quality-CLAUDE.md)
-
-如果你想按 vertical 场景成熟度决定先看模板还是先看 demo，先看 [../presentation/vertical-scenario-route-map.md](../presentation/vertical-scenario-route-map.md)。
-如果你想按表格确认每个 vertical 已补齐哪些材料，再看 [vertical-scenario-capability-matrix.md](vertical-scenario-capability-matrix.md)。
-
-正式进入任务后，PRD、delivery-plan、execute-log、handoff 等产出都要按命令说明通过 `npm run artifact:persist -- ...` 回写到项目仓库，而不是只留在对话里。
-
-## 4. 第一个最小闭环
-
-### 4.1 前端任务示例
-
-```text
-/team-help
-目标：判断当前任务入口
-现状：是否已有 brownfield 文档、project-context、handoff 证据
-输出：推荐下一条主链命令和缺失前置条件
-```
-
-随后进入：
-
-```text
-/team-intake
-目标：修复控制台首页在 iPad 横屏下的布局溢出
-范围：页面布局、响应式回归、UI 验证清单
-不做：接口与数据结构改造
-约束：必须遵守 frontend-quality-gates
-```
-
-随后进入专项拆解：
-
-```text
-/multi-frontend
-基于当前 intake 结果，从实现、UI/UX、QA 风险三个视角拆解工作。
-要求指出哪些结论必须进入最终 handoff。
-```
-
-### 4.2 后端任务示例
-
-```text
-/team-help
-目标：判断当前任务入口
-现状：是否已有 brownfield 文档、project-context、handoff 证据
-输出：推荐下一条主链命令和缺失前置条件
-```
-
-随后进入：
-
-```text
-/team-intake
-目标：新增订单审批状态流转接口
-范围：接口、权限校验、测试计划
-不做：前端页面
-约束：需要判断 私有流程与权限集成 是否启用
-```
-
-再继续：
-
-```text
-/team-plan
-基于 intake 结果，拆解 architect、backend-engineer、qa-engineer 的职责，给出依赖和风险。
-```
-
-## 5. 安装后另外三条最短体验路径
-
-### 5.1 想体验并行 + 测试先行
-
-```text
-/team-plan
-基于当前需求拆解实现任务，并给出适合进入 /tdd 的最小上下文。
-```
-
-```text
-/tdd
-目标：新增订单审批状态流转接口
-现有缺口：还没有测试先行路径和回归边界
-成功标准：给出 red-green-refactor 步骤，并整理成可直接回到 /team-execute 的动作清单
-```
-
-### 5.2 想体验平台能力自检
-
-```text
-/harness-audit
-目标：检查当前平台的命令、skills、hooks、rules、文档和集成深度。
-输出：Overall Score、Dimension Scores、Top Actions、Recommendations。
-```
-
-适合在新增命令、skills、hooks 或大量 runbook 后，快速看入口是否失联。
-
-### 5.3 想先理解 runtime 机制
-
-直接看 [runtime-capabilities-overview.md](runtime-capabilities-overview.md)。如果你更关心这些机制怎样影响 specialist 与主链，再补看 [ecc-harness-usage.md](ecc-harness-usage.md)。
-
-## 6. Codex 与 Claude 的差异
-
-- Claude 更适合通过用户级和项目级 `CLAUDE.md` 固化长期偏好
-- Codex 更适合围绕插件目录连续调用命令和 agent 资产
-- 两者都遵守同一套角色边界、handoff 契约和前端质量门禁
-- 两者中 specialist 都不是最终责任主体，最终结论都要回到主链
-
-## 7. 何时切到 specialist
-
-如果你只想快速复制命令骨架，不想先读完整示例，先看 [team-commands-quick-prompts.md](team-commands-quick-prompts.md)；如果你想看 Codex 里怎么表达并行与收口，直接看 [codex-parallel-prompt-recipes.md](codex-parallel-prompt-recipes.md)；如果你想看最短的两条上手路径，再看 [first-team-command-60-seconds.md](first-team-command-60-seconds.md)。
-
-如果你想直接看一份从 intake 到 multi-agent 再到 review 的成品对话，继续看 [codex-end-to-end-conversation-example.md](codex-end-to-end-conversation-example.md)。
-
-下列场景适合在 Codex 中插入 specialist：
-
-- 任务拆解复杂，用 `/plan` 或 `/multi-*`
-- 想先建立测试回路，用 `/tdd`
-- 代码已经改完，用 `/code-review`
-- 构建报错，用 `/build-fix`
-- 要补最终验证证据，用 `/verify`
-- 平台入口和配置刚大改过，用 `/harness-audit`
-
-每次 specialist 输出后，建议追加一句：
-
-```text
-请把上面的专项结论整理为可直接进入 /handoff 或 /team-review 的内容。
-```
-
-## 8. 常见误区
-
-- 不要把 Codex 当成只执行某一个 specialist 的单点工具
-- 不要跳过 `/handoff`，否则多角色输出难以收口
-- 不要默认每个任务都要走完整长链路，小任务可以走短链路，但验证不能省
-
-下一步建议：
-
-- 想按任务场景继续展开：看 [codex-usage-scenarios.md](codex-usage-scenarios.md)
-- 想先看所有命令和能力怎么映射：看 [command-and-capability-matrix.md](command-and-capability-matrix.md)
-- 想单独看 runtime hooks 与后台机制：看 [runtime-capabilities-overview.md](runtime-capabilities-overview.md)
-- 想直接复制 Codex 的并行编排说法：看 [codex-parallel-prompt-recipes.md](codex-parallel-prompt-recipes.md)
-- 想直接看 Codex 的完整对话示例：看 [codex-end-to-end-conversation-example.md](codex-end-to-end-conversation-example.md)
-- 想把平台正式接入项目：看 [project-onboarding.md](project-onboarding.md)
-- 想直接走一遍完整主链：看 [first-team-workflow-walkthrough.md](first-team-workflow-walkthrough.md)
-- 想查完整命令和输出规范：看 [team-skills-usage.md](team-skills-usage.md)
-
-完整说明见 [team-skills-usage.md](team-skills-usage.md)。