@colin4k1024/tsp 2.4.1 → 2.4.2

package/docs/runbooks/mobile-miniapp-demo-script.md

@@ -0,0 +1,129 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-29
+updated: 2026-03-29
+owner: 工程团队
+---
+
+# 移动端与小程序交付演示剧本
+
+本文是一份可直接照着讲的演示脚本，面向移动端 / 小程序项目的终端边界、弱网、权限路径、多尺寸适配和 QA 验证场景。
+
+## 1. 演示目标
+
+- 说明移动端项目为什么不能只讲桌面端 happy path
+- 说明 `/tdd` 如何前置锁定终端风险与异常态
+- 说明 `/multi-frontend` 如何帮助并行识别交互、适配和 QA 风险
+
+## 2. 适用对象
+
+- 需要介绍移动端交付方法的 Tech Lead
+- 需要讲终端适配与 QA 协作的前端负责人
+- 需要向团队解释 handoff 为什么必须写清终端范围的讲解人
+
+## 3. 演示时长建议
+
+- 5 分钟：只讲终端边界、弱网、权限三类风险
+- 10 分钟：再讲 `/tdd` 与 `/multi-frontend`
+- 15 分钟：完整走一遍 intake -> plan -> tdd -> multi-frontend -> execute -> handoff -> review
+
+## 4. 演示脚本
+
+### Step 1. 先用 1 分钟讲清移动端交付的风险在哪
+
+建议讲法：
+
+```text
+移动端项目最容易被低估的不是页面本身，而是终端差异、弱网、权限拒绝和容器环境差异。
+如果这些不前置，最后 QA 和上线阶段才会集中暴露问题。
+```
+
+配套材料：
+
+- [frontend-engineer-daily-operations.md](frontend-engineer-daily-operations.md)
+- [qa-engineer-daily-operations.md](qa-engineer-daily-operations.md)
+
+### Step 2. 用 `/team-intake` 讲清任务范围和边界
+
+建议输入：
+
+```text
+/team-intake
+目标：新增移动端报销申请页与提交流程
+范围：页面结构、表单交互、授权路径、多尺寸适配、测试计划
+不做：后端流程引擎改造
+约束：必须覆盖弱网、拒绝态、加载态、真机范围和容器差异
+```
+
+讲解重点：
+
+- 终端范围和异常态必须在 intake 就说清楚
+- 不然 plan 和 handoff 都会失焦
+
+### Step 3. 用 `/team-plan` 讲如何拆交付任务
+
+建议输入：
+
+```text
+/team-plan
+基于当前 intake 结果，拆页面结构、终端适配、权限路径、弱网验证、QA 回归和 handoff 节点。
+输出必须指出哪些风险先进入 /tdd，哪些内容适合通过 /multi-frontend 并行分析。
+```
+
+讲解重点：
+
+- 不能只拆前端开发动作
+- QA 验证范围和 handoff 节点必须提前进入计划
+
+### Step 4. 用 `/tdd` 讲“先锁终端与异常态标准”
+
+建议输入：
+
+```text
+/tdd
+基于当前 /team-plan 结果，先锁机型范围、容器范围、弱网场景、权限拒绝态、加载态、异常态和成功标准。
+```
+
+讲解重点：
+
+- `/tdd` 在这里锁的是多终端交付标准
+- 这样可以避免后面只剩 UI 表面讨论
+
+### Step 5. 用 `/multi-frontend` 讲并行识别风险
+
+建议输入：
+
+```text
+/multi-frontend
+基于当前 intake 或 tdd 结果，从交互体验、终端适配、QA 风险三个视角并行拆解，并整理成可直接进入 /handoff 的内容。
+```
+
+讲解重点：
+
+- 交互、适配、QA 三个视角适合并行，不必串行等待
+- 最终结果要落到 handoff，而不是停留在并行分析里
+
+### Step 6. 用 `/team-execute`、`/handoff`、`/team-review` 收尾
+
+建议讲法：
+
+```text
+执行阶段重点是把真机范围、弱网结果、权限拒绝行为和剩余风险写清楚；
+handoff 要让 QA 能直接接住；
+review 再决定还有没有阻塞上线的终端风险。
+```
+
+## 5. 建议演示顺序
+
+1. 先讲终端边界、弱网、权限三类风险
+2. 再展示 `/team-intake` 与 `/team-plan`
+3. 然后讲 `/tdd`
+4. 再讲 `/multi-frontend`
+5. 最后讲 `/team-execute`、`/handoff` 和 `/team-review`
+
+## 6. 演示后建议发给观众的材料
+
+- [mobile-miniapp-demo-execution-log.md](mobile-miniapp-demo-execution-log.md)
+- [mobile-miniapp-delivery-walkthrough.md](mobile-miniapp-delivery-walkthrough.md)
+- [../../examples/mobile-miniapp-CLAUDE.md](../../examples/mobile-miniapp-CLAUDE.md)

package/docs/runbooks/multi-service-backend-integration-walkthrough.md

@@ -0,0 +1,61 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-28
+updated: 2026-03-28
+owner: 工程团队
+---
+
+# 多服务后端集成演练
+
+本文面向后端或全栈项目，演示一个涉及多个服务或多个模块的集成任务应该怎样拆解、执行和验证。
+
+## 1. 场景
+
+- 任务：订单服务新增审批记录查询能力，并与权限服务联动
+- 涉及：接口契约、权限判断、测试和发布风险
+- 可能命中：custom overlay 候选项
+
+## 2. 推荐链路
+
+1. `/team-intake`
+2. `/team-plan`
+3. `/multi-backend`
+4. `/team-execute`
+5. `/verify`
+6. `/handoff`
+7. `/team-review`
+
+## 3. intake 阶段要锁定什么
+
+- 哪些服务或模块会受影响
+- 接口契约由谁收口
+- 是否命中 私有流程或权限集成 这类 overlay 候选项
+
+## 4. multi-backend 阶段要输出什么
+
+- 服务边界
+- 数据流
+- 测试策略
+- 发布和回滚风险
+
+## 5. execute 阶段要特别记录什么
+
+- 接口兼容性说明
+- 集成测试结果
+- 权限边界结果
+- 如果启用了 custom overlay，补执行记录
+
+## 6. verify 阶段要特别验证什么
+
+- 跨服务调用是否通
+- 错误路径是否一致
+- 关键边界态是否被覆盖
+
+## 7. 常见错误
+
+- 只有本服务视角，没有跨服务依赖视角
+- 接口改了，但没有给消费方明确 handoff
+- custom overlay 已经命中，却没有任何记录
+
+与后端日常说明配合阅读：[backend-engineer-daily-operations.md](backend-engineer-daily-operations.md)

package/docs/runbooks/open-design-integration.md

@@ -0,0 +1,163 @@
+# Open Design Integration
+
+本手册说明如何把 [nexu-io/open-design](https://github.com/nexu-io/open-design) 作为 TSP 的外部设计工作台接入。目标是让 TSP 管需求、角色协作、handoff 和质量门禁，让 Open Design 管可预览、可导出的高保真设计 artifact。
+
+## 采用边界
+
+| 项 | 结论 |
+|---|---|
+| 上游 | `nexu-io/open-design` |
+| License | `Apache-2.0` |
+| 接入方式 | `reference-only controlled integration` |
+| TSP 落点 | `skills/open-design` + 本 runbook + install manifest |
+| 默认安装 | `team` 安装 TSP thin skill / runbook；`full` 额外自动 clone/update Open Design 到 `~/.tsp/open-design` |
+| 本仓库依赖 | 不新增 npm 依赖，不 vendoring OD 源码、skills、design-systems 或 daemon；OD 作为外部 checkout 管理 |
+
+## 为什么这样接入
+
+Evidence：Open Design 是独立产品形态，包含 Next.js web、Node daemon、SQLite、PATH agent detection、31 skills、100+ design systems、artifact export，以及 Node `~24` / pnpm `10.33.x` 要求。
+
+Reasoning：如果把它当普通 skill 复制进 TSP，会把上游运行时、依赖、生成数据和设计资产生命周期绑进本仓库，增加验证和许可证归属成本。更合理的方式是让 TSP 提供调用协议、证据回写和安装发现入口。
+
+Implications：`full` profile 会自动准备 Open Design checkout，但 TSP 不替它长期托管 daemon 生命周期。好处是 TSP 的 `node scripts/validate-library.js`、hooks 契约和平台发布节奏保持稳定，同时 full 用户开箱就有 OD 源码与依赖准备路径。
+
+## 使用前检查
+
+安装 TSP full profile 时会自动执行：
+
+```bash
+node scripts/install-open-design.js
+```
+
+默认安装目录是 `~/.tsp/open-design`。可通过环境变量覆盖：
+
+```bash
+TSP_OPEN_DESIGN_HOME=/path/to/open-design node scripts/install-apply.js --profile full --target codex
+```
+
+脚本行为：
+
+- 目录不存在：`git clone --depth 1 --branch main https://github.com/nexu-io/open-design.git ~/.tsp/open-design`
+- 目录已存在且 origin 是 Open Design：fetch 并 checkout 最新 `main`
+- `corepack` / `pnpm` 可用时：自动执行 `corepack enable` 与 `pnpm install`
+- `corepack` / `pnpm` 不可用时：保留源码 checkout 并提示手动补依赖
+
+也可以手动在独立目录中准备 Open Design：
+
+```bash
+git clone https://github.com/nexu-io/open-design.git
+cd open-design
+corepack enable
+pnpm install
+pnpm tools-dev
+```
+
+上游当前要求 Node `~24` 与 pnpm `>=10.33.2 <11`。如果本机默认 Node 版本低于要求，用 `nvm`、`fnm` 或 Volta 进入 OD 目录后再切换版本。
+
+## TSP 主链接入
+
+### `/team-intake`
+
+在需求 intake 阶段补齐：
+
+- artifact 类型：prototype、dashboard、mobile、deck、poster、document-like output。
+- 受众与使用场景：销售、融资、内部评审、产品验证、实现交接。
+- 品牌输入：现有 `DESIGN.md`、品牌 URL、截图、素材包、竞品参考。
+- 约束：响应式范围、A11y、导出格式、真实数据要求、素材授权。
+
+### `/team-plan`
+
+把 Open Design 作为设计证据任务，而不是实现任务：
+
+- `product-manager` 锁定内容和验收标准。
+- `frontend-engineer` 选择 OD skill、design system 和视觉方向。
+- `qa-engineer` 定义 artifact 评审清单。
+- `tech-lead` 决定 OD 产物是探索、交接参考，还是实现输入。
+
+### `/team-execute`
+
+执行时遵循：
+
+1. 在 OD 中创建或打开项目。
+2. 导入/选择 `DESIGN.md`。
+3. 选择合适 skill：例如 `web-prototype`、`dashboard`、`mobile-app`、`guizang-ppt`、`pm-spec`。
+4. 生成 artifact 后记录：
+   - OD skill
+   - design system
+   - visual direction
+   - artifact/export 路径
+   - 截图或预览 URL
+5. 若进入代码实现，继续走本仓库 `frontend-engineering` 与 `frontend-ui-ux-system` 门禁。
+
+### `/team-review`
+
+评审不只看“好不好看”，必须覆盖：
+
+- 需求覆盖：artifact 是否响应 intake 中的核心场景。
+- 视觉系统：是否遵守 `DESIGN.md`，有没有随机色值、随机字体、AI 默认视觉模式。
+- 响应式：桌面、平板、手机关键断点是否可用。
+- 可访问性：对比度、键盘、焦点、语义结构。
+- 导出完整性：HTML/PDF/PPTX/ZIP/图片/视频是否能打开，素材路径是否完整。
+- 实现风险：哪些只是 demo 表现，不能直接进入生产代码。
+
+### `/team-release`
+
+若 OD 产物作为对外材料发布，release 记录需要包含：
+
+- 产物版本与导出格式。
+- 素材授权来源。
+- 验证人和验证命令/方式。
+- 回退方案：保留上一版导出或静态文件。
+
+## Artifact 回写模板
+
+```markdown
+# Open Design Artifact Brief
+
+## Goal
+
+## Inputs
+- TSP command:
+- OD skill:
+- Design system:
+- Visual direction:
+- Source materials:
+
+## Outputs
+- Preview/export path:
+- Screenshots:
+- Target format:
+
+## Decisions
+- Evidence:
+- Reasoning:
+- Implications:
+
+## Review
+- Responsive:
+- A11y:
+- Visual quality:
+- Data/material authorization:
+- Implementation risks:
+
+## Next Step
+```
+
+## 与现有 TSP 能力组合
+
+| 场景 | 推荐组合 |
+|---|---|
+| 先收敛视觉系统 | `frontend-ui-ux-system -> open-design design-system -> /team-plan` |
+| 做高保真网页原型 | `/team-intake -> open-design web-prototype -> /team-execute` |
+| 做 dashboard / admin UI | `frontend-engineering -> open-design dashboard -> browser-smoke-testing` |
+| 做汇报材料 | `frontend-slides -> open-design deck mode -> /team-review` |
+| 做产品文档或 PM spec | `product-manager -> open-design pm-spec -> doc-architecture` |
+
+## 禁用项
+
+- 不复制 Open Design 上游源码、skills、design-systems、SQLite 数据或生成项目到 TSP canonical source。
+- `full` profile 可以自动 clone/update Open Design；其他 profile 不自动拉取上游源码。
+- 不把 Open Design 运行时加入 TSP 默认 npm 依赖或本仓库源码树。
+- 不用 OD artifact 代替 TSP 的需求、交接、评审和发布记录。
+- 不在 TSP 仓库中执行可能改写 AGENTS、hooks、MCP 或 agent 全局配置的外部 setup 命令。
+- 不发布未确认授权的品牌资产、字体、图片、视频或第三方截图。

package/docs/runbooks/open-source-release-checklist.md

@@ -0,0 +1,90 @@
+---
+version: "2.4.1"
+status: active
+created: 2026-04-22
+updated: 2026-05-06
+owner: 工程团队
+doc_tier: entry
+last_verified: 2026-05-06
+source_of_truth:
+  - ../../README.md
+  - ../../package.json
+  - ../../.github/workflows/publish.yml
+  - ../../scripts/release-health-summary.js
+---
+
+# 开源发布收尾清单
+
+本文用于把当前仓库作为公开开源项目发布前的最后收尾动作固定下来。它不替代通用发布方案，而是专门覆盖 public README / support / tarball / install surface / community entry points 这些开源发布面。
+
+## 1. 最短执行顺序
+
+1. 先跑 `npm run release:health`
+2. 若已经生成 tarball，再跑 `npm run release:health -- --pack-json .npm-pack.json`
+3. 处理所有 `FAIL` 项；`WARN` 项需要明确记录是否接受
+4. 再过一次 [pre-release-checklist.md](pre-release-checklist.md)
+
+## 2. 这条命令会帮你看什么
+
+- `validate-library`
+- `validate-doc-freshness`
+- `validate-file-references --strict`
+- `tests/test_public_release_surface.js`
+- `tests/test_tsp_create_surface.js`
+- `tests/test_codex_install_plan.js`
+- `validate-prebuilt`
+- `validate-packed-tarball`（若提供 tarball 或 pack-json）
+- 公开 target support summary（默认按 `team` profile）
+
+## 3. Maintainer Checklist
+
+### 3.1 入口与社区面
+
+- [ ] `README.md`、`SUPPORT.md`、`CONTRIBUTING.md`、`SECURITY.md` 入口齐全且互相可达
+- [ ] README 中的 target/profile/support-level 口径与当前 manifests/runtime 一致
+- [ ] GitHub issue contact links、PR template、CI checks 与公开协作方式一致
+
+### 3.2 安装与能力面
+
+- [ ] `tsp-create --help`、wizard、README、SUPPORT 对 target/profile 口径一致
+- [ ] Codex `commands-core` regression test 仍为绿色
+- [ ] partial / baseline targets 没有被文档误写成 full parity
+
+### 3.3 打包与发布面
+
+- [ ] `validate-prebuilt` 为绿色
+- [ ] 若已打包 tarball，`validate-packed-tarball` 为绿色
+- [ ] prebuilt source of truth 仍是 workflow/release staging + npm tarball，而不是 Git 回写目录
+- [ ] publish workflow 与本地说明没有再次漂移
+
+### 3.4 文档卫生
+
+- [ ] `validate-doc-freshness` 为绿色
+- [ ] `AGENTS.md`、README、runbooks 没有 session residue、临时记录或会话记忆块
+- [ ] strict reference validation 为绿色
+
+## 4. 怎样理解结果
+
+- `PASS`：当前可直接进入发布或合并前最后确认
+- `WARN`：不是硬阻塞，但要么当场修，要么在 release notes / backlog 中显式接受
+- `FAIL`：不应继续做公开发布
+- `SKIP`：通常表示你还没提供 tarball；如果当前要发 npm，这一项不能跳过
+
+## 5. 当前公开支持口径
+
+- `Recommended`：`claude`、`cursor`
+- `Strong`：`codex`、`opencode`
+- `Partial`：`antigravity`、`codebuddy`
+- `Baseline`：`gemini`、`copilot`、`windsurf`、`augment`
+
+如果 support matrix 发生变化，必须同步更新：
+
+1. `README.md`
+2. `SUPPORT.md`
+3. `scripts/release-health-summary.js` 的 support summary 输出
+
+## 6. 相关文档
+
+- 通用发布检查：[pre-release-checklist.md](pre-release-checklist.md)
+- 发布收口一页：[release-closure-one-page.md](release-closure-one-page.md)
+- npm / release automation：[release-notes-automation.md](release-notes-automation.md)

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

@@ -0,0 +1,128 @@
+---
+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
+---
+
+# OpenCode Quick Start — Team Skills Platform
+
+> 参考对象：需要在 OpenCode 中使用 Team Skills Platform 的工程师。
+
+## 1. 安装
+
+```bash
+node scripts/build-platform-artifacts.js
+./scripts/install-opencode.sh
+
+# 指定自定义路径
+OPENCODE_CONFIG_DIR=/path/to/opencode ./scripts/install-opencode.sh
+```
+
+## 2. 安装后目录结构
+
+```text
+~/.config/opencode/
+├── plugins/team-skills-platform/
+│   ├── .opencode-plugin/
+│   ├── skills/                     # 当前正式技能目录（统一平铺）
+│   ├── commands/
+│   ├── rules/
+│   ├── agents/
+│   │   ├── roles/
+│   │   └── specialists/
+│   ├── hooks/
+│   ├── contexts/
+│   ├── examples/
+│   └── mcp-configs/
+└── AGENTS.md                       # 自动合并的角色 / 命令入口
+```
+
+OpenCode 公开表面只保留当前 `skills/` 目录和 JS runtime 入口，不再把旧三层 skill 目录或 Python hook 文件名当成现行结构。
+
+### 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. AGENTS.md 会写入什么
+
+安装脚本会在 `~/.config/opencode/AGENTS.md` 自动写入 Team Skills Platform 区块，至少包括：
+
+- 角色引用路径
+- `/team-help` 在内的核心主链命令速查表
+- 插件根路径说明
+
+## 4. 在 OpenCode 中怎么用
+
+- 公开入口统一从 `/team-help` 开始
+- 正式任务产出要通过 `npm run artifact:persist -- ...` 回写到项目仓库
+- specialist 结论仍需回落到 `/handoff` 或 `/team-*`
+
+### 4.1 通过 AGENTS.md 激活角色
+
+```text
+请以 Tech Lead 角色帮我拆解这个需求，参考 AGENTS.md 中的角色定义。
+```
+
+### 4.2 直接引用命令定义
+
+```text
+先执行 /team-help，判断当前该进入 intake、plan，还是先补 readiness 证据。
+```
+
+```text
+执行 /team-plan 流程，定义见：
+~/.config/opencode/plugins/team-skills-platform/commands/team-plan.md
+```
+
+### 4.3 引用 Skill
+
+```text
+读取并应用以下 skill：
+~/.config/opencode/plugins/team-skills-platform/skills/systematic-debugging/SKILL.md
+```
+
+## 5. 常用命令速查
+
+| 命令 | 用途 |
+|------|------|
+| `/team-help` | 根据当前阶段、artifacts 与阻塞项推荐下一步 |
+| `/team-intake` | 接收需求并锁定目标、范围、约束 |
+| `/team-plan` | 收口 challenge / design / readiness，并拆解里程碑 |
+| `/team-execute` | 消费 readiness proof 执行实现 |
+| `/team-review` | 做方案、质量、测试和放行评审 |
+| `/team-release` | 做发布准备、上线检查与回滚保障 |
+| `/team-closeout` | 在观察窗口结束后做最终收口 |
+| `/handoff` | 在角色间做结构化交接 |
+| `/plan` | Planner specialist 规划入口 |
+| `/code-review` | Code Reviewer specialist 入口 |
+| `/tdd` | TDD 先行入口 |
+| `/build-fix` | 构建错误修复入口 |
+
+## 6. 重新安装 / 更新
+
+```bash
+node scripts/build-platform-artifacts.js
+./scripts/install-opencode.sh
+```
+
+## 7. 相关文档
+
+- [AGENTS.md](../../AGENTS.md) — 平台总览
+- [claude-quick-start.md](claude-quick-start.md) — Claude 快速上手
+- [cursor-quick-start.md](cursor-quick-start.md) — Cursor 快速上手
+- [team-skills-usage.md](team-skills-usage.md) — 完整使用手册

package/docs/runbooks/parallel-development-coordination-walkthrough.md

@@ -0,0 +1,47 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-28
+updated: 2026-03-28
+owner: 工程团队
+---
+
+# 并行研发协调演练
+
+本文演示一个需求由多个角色并行推进时，如何管理依赖、同步点和阶段性风险，避免各自推进后在末端集中碰撞。
+
+## 1. 场景
+
+- 任务：审批中心新增筛选、导出和权限限制
+- 前端、后端、QA、架构师都需并行参与
+- 风险在于依赖和边界很容易中途漂移
+
+## 2. 推荐链路
+
+1. `/team-intake`
+2. `/team-plan`
+3. `/team-execute`
+4. `/handoff`
+5. `/team-review`
+
+## 3. 关键协调点
+
+- 哪些事项必须先定，再并行开工
+- 哪些事项允许局部占位或 Mock
+- 每个阶段的同步节点和责任人
+- 哪些偏差必须升级给 tech-lead
+
+## 4. 关键输出
+
+- 依赖顺序和里程碑
+- 阶段性 handoff 清单
+- 已知阻塞和替代方案
+- 进入 QA 前的最小完备条件
+
+## 5. 常见错误
+
+- 只做任务分配，不做同步节点设计
+- 出现偏差后继续各自推进
+- QA 最后才第一次看到全局状态
+
+与这些文档配合阅读：[project-manager-daily-operations.md](project-manager-daily-operations.md)、[tech-lead-daily-operations.md](tech-lead-daily-operations.md)