| name | team-command-ship |
| description | Execute the ship workflow from this AI development team preset. Use when the user writes /ship, asks for ship, or wants the corresponding team process in Codex. |
team-command-ship
This skill ports the Claude Code /ship command workflow to Codex.
In Codex, invoke this as $team-command-ship. Do not rely on /ship unless Codex itself defines that slash command with the same meaning.
/ship - 发布前检查
代码发布前的全面检查和部署流程。M 及以上任务必须通过 /ship 才能发布。
Project Preset Lifecycle
开始前运行 node create-claude-team/cli.js project-preset context --json。当结果为 pass 时，按 PRESET.md -> rules -> specs -> base/技术栈 preset 顺序读取；只读取与当前发布相关的 .agents/rules/specs。结果为 needs_revision 时，不得静默把 project-preset 当作项目事实，先说明 project-preset validate 的修复项。不存在 project-preset 时，继续使用 base 和已安装技术栈 preset，不阻塞既有项目，并按需建议 /project-preset。
执行流程
1. 集成验证
├── 运行 /review-all（当前分支 diff vs main）
├── 所有测试通过？
├── 类型检查通过？（tsc --noEmit）
└── Lint 无错误？
2. 安全审计
├── npm audit（无 high/critical）
├── 无硬编码密钥/密码
├── 输入已验证（Zod schema）
└── 敏感操作已授权检查
3. 性能验证
├── Core Web Vitals 达标（LCP < 2.5s, CLS < 0.1）
├── 无 N+1 查询
├── 大列表已分页
└── 图片/资源已优化
4. 无障碍检查
├── 关键交互元素有 aria 标签
├── 颜色对比度达标（WCAG AA）
└── 键盘可操作
5. 配置检查
├── 环境变量已配置（.env.example 完整）
├── 数据库迁移已准备（含 rollback 脚本）
└── CI/CD 配置已更新
6. Git 检查
├── 分支命名规范（feature/xxx, fix/xxx）
├── commit message 清晰（符合 Conventional Commits）
└── 无敏感文件（.env, credentials, secrets）
7. 发布决策
├── 所有检查通过 → 可以发布
├── 有警告 → 按 known risk 处理规则确认 accept/mitigate/defer
└── 有严重问题 → 打回修复
8. 部署（DevOps Agent）
├── 创建发布 tag
├── 执行部署脚本
├── 验证部署成功
└── 记录发布日志
Known Risk 处理规则
/ship 不允许只写“有风险但可接受”。每个 known risk 必须有明确处置：
accept：Owner 明确接受该风险后才可继续；报告必须写清影响范围、监控信号、回滚触发条件和确认人。mitigate：发布前必须完成缓解动作；缓解未完成时 release gate 不能 pass。defer：风险转为后续任务；必须写入任务 ID、负责人/确认人和不阻塞本次发布的理由。
高风险发布必须触发 Owner Decision Brief。高风险包括：安全或隐私风险、支付/权限/数据迁移、不可逆操作、回滚不完整、SLO/性能明显不达标、合规影响、用户承诺或 MVP 验收标准改变。
## Owner Decision Brief
- Decision: [whether to release with this high risk]
- Context: [release scope, risk, impact, rollback readiness]
- Recommendation: [ship / delay / mitigate first, with reason]
- Options:
- A: [recommended option] - [trade-off]
- B: [alternative] - [trade-off]
- C: [optional] - [trade-off]
- If no reply: [pause release / safe default]
存在 .claude/workspace/planning/owner-decision-contract.md 时，高风险发布引用的 Brief 还必须通过：
node create-claude-team/cli.js decision validate <brief>
只有 confirmed、模块和类型匹配的 Brief 才能用于 N7 Readiness Brief 或 release report。AI 不能把工具权限、自动批准或自己的风险建议写成 Owner Confirmation；缺确认时发布保持 blocked。
tasks.md 状态更新
Controlled Delivery Contract
存在 .claude/workspace/planning/delivery-contract.md 时，/ship 只在发布检查和上线验证通过、Gate 结果 已包含 release pass 后运行：
node create-claude-team/cli.js delivery transition <module> <task-id> shipped
该迁移不证明部署、安全或恢复已经充分完成；它只阻止跳过已经声明的 release evidence。N7 负责进一步定义真正的运行保障门禁。
Operational Readiness Contract
存在 .claude/workspace/planning/operational-readiness-contract.md 时，涉及软件部署、外部运行环境、安全/隐私、数据、权限或用户可见行为的 M/L/XL 发布，DevOps 必须先创建并验证 Readiness Brief：
node create-claude-team/cli.js operations validate .claude/workspace/operations/<brief>.md
- release report 必须引用通过的 Brief，以及部署/回滚、观测/告警、备份/恢复、事故响应和验证证据。
Risk Level: high 必须有 Threat Model 和 Owner Decision Brief；缺任一项时 release gate 为 blocked，不能以 known risk 文字绕过。- Brief 只证明准备度声明和证据完整；真实部署、监控、备份、恢复和回滚仍由项目 CI/CD、运行环境与 DevOps 验证。
- Brief 中不得写入密钥、token、密码、连接串或未脱敏用户数据；使用 secret manager 或环境变量名称引用。
如果仓库存在 tasks.md，或用户指定了任务/模块 ID，/ship 必须把它作为执行状态源同步更新：
- 开始发布检查时，将对应任务状态更新为
release_gate，并刷新最近更新日期。
- 发布检查通过但等待人工确认部署时，记录
Gate 结果.release = pass，状态保持 release_gate，并在阻塞原因或 next action 中说明等待谁确认。
- 更新时不要删除任务条目的验收标准、验收命令、阻塞原因、Gate 结果和产物字段。
- 发布或上线验证完成后，将状态更新为
shipped；无需真实发布的文档/配置任务可在发布检查通过后更新为 done。
- 发布检查失败且可自动修复时，记录失败项和修复轮次，修复后重新检查。
- 2 轮后仍失败、存在严重风险、known risk 未处置或等待用户接受风险时，将状态更新为
blocked，写明阻塞原因、风险处置状态和下一步确认人。
tasks.md 状态必须使用：ready / needs_clarification / planned / in_progress / local_gate / review_gate / release_gate / blocked / shipped / done。
roadmap.md 状态更新
如果发布范围关联 roadmap.md 中的模块，/ship 也必须把 roadmap 作为产品模块状态源同步更新：
- 发布检查通过但等待人工确认部署时，保持模块状态为
done，刷新最近更新日期，并在风险或未决区记录等待确认。
- 发布或上线验证完成后，将对应模块状态从
done 更新为 shipped，刷新最近更新日期，并保持进度区已打勾。
- 发布检查失败、存在严重风险或等待用户接受风险时，将对应模块状态更新为
blocked，在风险或未决区记录阻塞原因。
- 更新 roadmap 时不要删除模块 ID、依赖、验收标准、风险和最近更新字段。
Release Report 契约
/ship 必须产出可沉淀的发布报告，路径为：
.claude/workspace/releases/YYYY-MM-DD-<version-or-scope>.md
命名规则：
<version-or-scope> 优先使用版本号或 tag，如 v1.2.3；没有版本时使用任务 ID、模块 ID、目录名或分支名的短横线形式。- 如果
.claude/workspace/releases/ 不存在，先创建目录。
- 报告路径必须写入 Summary 的
affected files/modules，并写入 events.jsonl.artifacts。
报告必须包含以下字段：
- 发布结论：
ready / needs_confirmation / blocked / shipped，并给一句话原因。
- 关联任务：任务 ID、模块 ID、版本号或发布范围；没有则写
无。
- 发布范围：分支、tag、变更模块、关键配置和报告关联的 review report。
- 检查结果：review、test、typecheck、lint、security、performance、accessibility、config、git、rollback 的 pass/fail/warn。
- 风险：已知风险、影响范围、风险处置（accept / mitigate / defer）、确认人和是否需要 Owner Decision Brief。
- 回滚步骤：具体命令、旧版本/tag、数据回滚方式、触发条件。
- 发布后验证：上线后要检查的页面、接口、日志、监控指标或人工验收项。
- Gate 结果：release gate 的 pass/fail、警告数、阻塞项和确认人。
- Owner Decision Brief：高风险发布时必须记录决策摘要；无高风险时写“无”。
- 下一步：执行部署、等待确认、继续修复、回滚或进入 hotfix。
标准结果摘要
/ship 完成后必须输出固定的 Summary 块，供用户阅读，并作为 events.jsonl 的字段来源。
## Summary
- status: completed / shipped / failed / blocked / skipped
- affected files/modules: [发布范围、报告路径、tag、关键配置或模块]
- checks: [review、test、typecheck、lint、security、performance、rollback 的最终结果]
- next action: [执行部署、发布后验证、继续修复或等待用户确认]
映射规则：
events.jsonl.summary 使用 status + 一句话发布结论，例如 completed: 发布检查通过，等待用户确认发布。events.jsonl.artifacts 使用 affected files/modules 中的文件路径、tag 或发布报告，必须包含 .claude/workspace/releases/YYYY-MM-DD-<version-or-scope>.md。events.jsonl.checks 使用 checks 的结构化结果。events.jsonl.next 使用 next action。
Next Best Action 契约
/ship 完成、阻塞或等待确认时必须输出固定的 Next Best Action，告诉用户下一步应该做什么、为什么、是否需要人工确认。
## Next Best Action
- action: [建议执行的命令或人工动作，如执行部署、等待用户确认、修复发布门禁、回滚]
- reason: [为什么现在应该做这一步，引用 release gate、风险、回滚准备或 release report]
- requires human confirmation: yes / no
- source: [依据来源，如 release report、review report、checks、tasks.md、events.jsonl]
写入规则：
Summary.next action 必须与 Next Best Action.action 保持一致或可直接追溯。- 如果
requires human confirmation: yes，必须说明谁需要确认什么。
- 如果发布门禁失败或回滚方案缺失，Next Best Action 不得建议继续部署。
- 如果存在未处置 known risk 或高风险发布尚未完成 Owner Decision Brief，Next Best Action 必须指向风险确认或缓解动作。
事件记录
/ship 收尾时必须向 .claude/workspace/events.jsonl 追加 1 行 JSONL 事件。该文件是 /standup 和后续 metrics 的机器可读事实来源。
events.jsonl 契约
每行是一个独立 JSON 对象，不允许跨行，不回写旧事件。
| 字段 | 必填 | 说明 |
|---|
time | 是 | UTC ISO 8601 时间，如 2026-07-09T10:00:00Z |
command | 是 | 固定为 /ship |
task | 否 | 发布关联任务、版本或模块；没有则为 null |
status | 是 | completed / shipped / failed / blocked / skipped |
summary | 是 | 一句话发布检查或发布结果摘要 |
checks | 否 | 发布门禁结果对象，如 {"test":"pass","security":"pass","rollback":"pass"} |
artifacts | 否 | 发布报告、tag、关键配置或变更文件路径数组 |
next | 否 | 发布后验证或下一步建议，或 null |
Metrics 扩展字段
events.jsonl 同时是结构化 metrics 的机器事实来源。/ship 收尾事件应尽量写入这些可选字段；未知时用 null，计数无发生时用 0：
| 字段 | 说明 |
|---|
taskId | 标准任务、模块、版本或发布范围 ID；优先等于 task |
level | 任务级别：S / M / L / XL；未知为 null |
specRejectCount | 继承任务的 spec 否决次数；未知为 null，无发生为 0 |
checkIssueCount | 发布检查发现的问题数；没有则 0 |
checkFixRounds | 发布检查自动修复轮数 |
reviewRejectCount | 发布前 /review-all 打回次数 |
testFailureCount | 发布门禁测试失败次数 |
estimateHours | 继承任务或发布估算；没有则为 null |
actualHours | 发布检查或部署实际耗时；没有记录则为 null |
失败恢复记录契约
当 /ship 遇到测试失败、CI 失败、pack 失败、hook 误拦或发布失败，并且本次流程进行了自动修复、重试、回滚或最终阻塞时，收尾事件必须写入可选对象 failureRecovery。无失败发生时省略该对象。
failureRecovery 固定字段：
| 字段 | 说明 |
|---|
failureType | test_failure / ci_failure / pack_failure / hook_false_positive / release_failure |
stage | 发生阶段，如 local_gate、review_gate、release_gate、hook、ci |
symptom | 用户可读的失败现象，避免粘贴长日志 |
rootCause | 已确认根因；未知时为 unknown |
recoveryAction | 已执行的恢复动作，如 fix、retry、rollback、mark_flaky、accept_risk |
attempts | 修复或重试次数 |
finalStatus | recovered / blocked / accepted_risk / needs_followup |
evidence | 相关命令、报告或日志路径数组，必须使用仓库相对路径 |
followUp | 后续任务、补测试、修 CI 或人工确认事项；没有则为 null |
写入规则：
- 只在发布流程收尾时追加 1 条最终事件，不记录中间步骤。
- 如果
.claude/workspace/ 或 events.jsonl 不存在，创建它们。
- 路径使用仓库相对路径，不记录绝对路径、密钥、token 或敏感数据。
- 写入失败时在最终输出中说明，但不改变发布检查结论。
示例：
{"time":"2026-07-09T10:20:00Z","command":"/ship","task":"T0.2","taskId":"T0.2","level":"M","status":"completed","summary":"completed: 发布检查通过，等待用户确认发布","checks":{"review":"pass","test":"pass","security":"pass","rollback":"pass"},"specRejectCount":0,"checkIssueCount":0,"checkFixRounds":0,"reviewRejectCount":0,"testFailureCount":0,"estimateHours":null,"actualHours":null,"artifacts":[".claude/workspace/releases/2026-07-09-t0.2.md"],"next":"用户确认后执行部署"}
自动修复机制
- 安全问题 → 自动修复 → 重新检查
- 性能问题 → 列出优化建议，用户决定
- 测试失败 → 自动修 → 重试（最多 2 轮）
- 2 轮后仍有问题 → 列出剩余问题等用户决定
回滚检查
发布前必须确认回滚方案：
发布后验证
发布后验证必须覆盖：
- 用户主流程或本次发布关联的 acceptance 场景。
- 错误率、延迟、关键业务指标或日志查询。
- 风险处置项中的监控信号和回滚触发条件。
- 需要人工确认时，写明确认人和确认窗口。
输出格式
# 发布检查报告
> 路径：.claude/workspace/releases/2026-07-09-v1.2.3.md
## 结论：✅ 可以发布 / ⚠️ 需要确认 / ❌ 需要修复
## 关联任务
- 任务：T1.5
- 版本：v1.2.3
## 发布范围
- 分支：feature/user-auth
- tag：v1.2.3
- Review report：.claude/workspace/reviews/2026-07-09-auth.md
| 检查维度 | 结果 | 详情 |
|----------|------|------|
| 代码审查 | ✅ | /review-all 通过 |
| 测试 | ✅ | 所有测试通过 |
| 类型 | ✅ | tsc 无错误 |
| 安全 | ⚠️ | 1 个中等漏洞（已确认不影响） |
| 性能 | ✅ | LCP 1.8s |
| 无障碍 | ✅ | WCAG AA 达标 |
| 配置 | ✅ | .env.example 完整 |
| Git | ✅ | 分支和 commit 规范 |
## 回滚方案
- 回滚步骤：[具体命令]
- 回滚触发条件：[如错误率 > 1%]
- 旧版本：[tag/commit]
- 数据回滚：[迁移 down 命令或无需数据回滚的说明]
## Known Risks
| 风险 | 影响 | 处置 | 确认人 | 证据/后续 |
|------|------|------|--------|-----------|
| 1 个中等漏洞 | 仅影响开发依赖，不进入生产包 | accept | Owner | npm audit 结果 + 生产包清单 |
| 首屏监控缺少告警 | 发布后发现性能回退较慢 | mitigate | DevOps | 发布前补 dashboard alert |
| 次要浏览器兼容性 | 不影响 MVP 主用户 | defer | Product Lead | 后续任务 T-browser |
## Owner Decision Brief
- Decision: 是否在中等漏洞已确认不影响生产包的前提下发布
- Context: 发布门禁其他项通过，回滚方案完整，该风险已标记为 accept
- Recommendation: 发布；发布后观察安全扫描和错误率
- Options:
- A: 发布 - 更快交付，接受已界定风险
- B: 延迟发布先升级依赖 - 风险更低，但延迟交付
- If no reply: 暂停发布
## 发布步骤
1. 合并 PR 到 main
2. 创建 tag: v1.2.3
3. 执行部署脚本
4. 验证部署
## 发布后验证
- 页面/接口：[需要验证的入口]
- 日志：[需要观察的错误日志]
- 监控：[错误率、延迟、关键业务指标]
- 人工验收：[用户或负责人确认项]
## Gate 结果
- release: pass
- warnings: 0
- blockers: 0
- approver: [用户/负责人]
## Summary
- status: completed
- affected files/modules: .claude/workspace/releases/2026-07-09-release.md, v1.2.3
- checks: review pass / test pass / typecheck pass / lint pass / security pass / rollback pass
- next action: 用户确认后执行部署
使用方式
/ship # 检查当前分支，准备发布
/ship --dry-run # 只检查，不执行部署
参与角色
| 阶段 | 角色 | 职责 |
|---|
| 集成验证 | Reviewer | 运行 /review-all（含 code-review skill 逐文件审查），确保代码质量 |
| 安全审计 | Reviewer | code-review skill 安全维度 + /review-all 跨文件安全检查 |
| 性能验证 | Reviewer | code-review skill 性能维度覆盖 |
| 无障碍检查 | Reviewer | code-review skill 无障碍维度覆盖 |
| 配置检查 | DevOps | 环境变量、迁移、CI/CD |
| 部署 | DevOps | 执行部署、验证、回滚准备 |
| 最终决策 | 用户 | 确认是否发布 |
异常路径
| 场景 | 处理方式 |
|---|
| /review-all 未通过 | 根据审查结果修复 → 重新 /ship |
| 安全漏洞无法立即修复 | 按 known risk 规则标记 accept/mitigate/defer；高风险必须 Owner Decision Brief |
| 测试偶发失败 | 重试 2 次 → 仍失败则标记 flaky test，用户决定 |
| 部署失败 | 自动回滚 → 记录失败原因 → 通知用户 |
| 发布后发现问题 | 触发回滚 → 记录问题 → 进入 hotfix 流程 |
