SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsship-workflow-ship

ship-workflow-ship

Deployment & operations

View repository

Updated 10-16 10:20

About this skill

Ship — Release and Delivery

Entry/Exit

  • Entry: Code that passed review
  • Exit: docs/features/<name>/05-ship.md + docs/features/<name>/README.md(aggregated README + retrospective)
  • Points to: After completion, proceed to reflect-team-retro(optional)
  • Output path: → ship-workflow-land
  • Preload: CANON.md + verify-workflow-review/SKILL.md

When not to use

  • Pure configuration changes (environment variables, DNS) — can be changed directly under monitoring
  • Feature has not passed review — review must be completed first
  • Dependencies are not ready (database migration not approved, third-party service not configured)

Iron Law

Process

Phase A: Pre-release Check

First read the spec's artifact_type：

  • software(default) → load ship-infrastructure-deploy, and execute code quality, security, performance, infrastructure, and documentation verification item by item according to its Pre-Launch checklist
  • document / article / deck / visual → load ship-artifact-export, and execute export, preview, archive, and delivery checks

Verification commands (must run):

npm test && npm run build && npm run lint && npx tsc --noEmit

Phase B: Quality Gate — Ship Audit Army

After the pre-release check passes, dispatch the corresponding auditors in parallel according to artifact type to perform pre-release specialized audits:

Pre-launch checks (Phase A passed)
    │
    ├── agents/ship-security-auditor.md      → 安全审计: OWASP、输入边界、认证授权、数据暴露、依赖
    ├── agents/ship-performance-auditor.md   → 性能审计: 关键路径、N+1查询、内存资源、Bundle影响、退化
    ├── agents/ship-accessibility-auditor.md → 无障碍审计: WCAG合规、屏幕阅读器、表单错误、动态内容
    ├── agents/ship-docs-auditor.md          → 文档审计: CHANGELOG、README、迁移指南、API文档、错误信息
    └── agents/ship-artifact-export-auditor.md → 非 software 导出 QA: source/final 对齐、格式、归档、交付包验证
            │
            ▼
    收集审计结果 → 分级合并 → 修正 → 进入 Staging（Phase B.5）

Each auditor outputs three levels of feedback: Blocking / Important / Suggestion.

The phase skill only dispatches auditors that have been selected by the minimum trigger conditions; auditors not selected do not produce placeholder feedback.

Feedback handling rules:

  • Blocking — must be resolved; do not ship until fixed
  • Important — strongly must be fixed; if not fixed, the reason for risk acceptance must be recorded in the ship report
  • Suggestion — judge independently; if adopted, annotate the source

Minimum trigger conditions:

  • Small changes (single file, no security/UI sensitivity) → may skip Audit Army
  • software Standard changes → at least security + docs dual audit
  • Non-software standard changes → at least artifact-export + docs dual audit
  • UI changes → add accessibility
  • Performance-sensitive changes (data processing, queries, frontend bundle) → add performance
  • User specifies --full → all roles related to the current artifact type are enabled

Maintain backward compatibility: High-risk changes may also load specialized review skills:

  • verify-quality-security/SKILL.md — in-depth security specialization
  • verify-quality-performance/SKILL.md — in-depth performance specialization
  • verify-frontend-accessibility/SKILL.md — in-depth accessibility specialization

Phase B.5: Staging Verification (only software mandatory)

software Before going live, staging environment verification must be performed:

Verification steps:

  1. Deploy to the staging environment
  2. Run the full test suite on staging data:npm test
  3. Manually smoke test critical paths (user registration, login, core flows)
  4. Verify integration with downstream dependencies (API mock disabled, real calls)
  5. Confirm data migration is forward compatible
  6. Confirm the rollback script is available

staging is not fully == do not ship. All software verifications must all be green before entering Go/No-Go.

Non-software artifacts at this stage instead perform final delivery package verification:

  1. Open the final file or preview
  2. Check whether the source / final / review / ship records can trace each other
  3. Verify the file name, format, path, and version notes
  4. Mark the final open verification results of the human partner / CI

Phase C: Go/No-Go decision

Documentation:

## Go/No-Go
- [ ] 阻塞项：无未解决的 Critical 问题
- [ ] 已知风险：[列出]
- [ ] 回滚计划：已准备（强制！）

Rollback plan template:

## 回滚计划

### 触发条件
- 错误率 > 2x 基准
- P95 延迟 > [X]ms

### 回滚步骤
1. 禁用 feature flag（如适用）
   或
1. 部署上一版本：`git revert <commit> && git push`
2. 验证回滚：健康检查、错误监控
3. 沟通：通知团队

### 数据库执行
- Migration [X] 有 rollback
- 新功能插入的数据：[保留 / 清理]

### 回滚时间
- Feature flag: < 1 分钟
- 重部署前一版本: < 5 分钟
- DB rollback: < 15 分钟

Phase D: Documentation aggregation

Automatically generate docs/features/<name>/README.md, including:

  • Feature Summary: owner, date, status, artifact_type, final result, source target
  • Document Index：00-brainstorm.md stage evidence status through to 07-deploy-report.md phase evidence status
  • Timeline: key phase dates, evidence paths, and notes
  • Key Decisions: ADR / design / ship decision index, rationale, and current status
  • Delivery Outcome: delivered, not delivered, final artifacts, user-visible changes, project documentation, and change statistics
  • Verification Evidence: review / ship / canary / deploy gate evidence, results, and owner
  • Residual Risks: remaining risks, impact, owner, and tracking
  • Follow-up Actions: follow-up actions, owner, due date, and tracking
  • Retro Notes: what went well, what should change, reusable lessons

Also check and record Documentation Sync：

  • Updated project docs
  • Deferred project docs
  • CHANGELOG.md updated
  • README verified
  • project-level document statuses that other review / plan records mark as requiring synchronization

Phase E: Post-release closed loop (recommended)

After release is complete, the post-release closed loop must be executed:

  • ship-workflow-canary — canary monitoring, curl key endpoints and compare against baseline
  • ship-workflow-land — merge PR, wait for CI, verify production environment
  • ship-workflow-doc-sync — cross-reference changes, synchronously update outdated documentation

For phased rollout strategy, Feature Flag lifecycle, and promotion/rollback thresholds, see ship-infrastructure-deploy。

Good/bad examples

Good example: structured Go/No-Go + rollback plan

## Go/No-Go — 任务管理 v2.3
- [x] 阻塞项：无未解决 Critical
- [x] 已知风险：旧版 API 兼容窗口 48h，已准备 fallback 路由
- [x] 回滚计划：feature flag 关闭 < 1min；git revert + redeploy < 5min
- [x] Staging 全绿，冒烟测试通过
- 决策：GO

Advantages: each item is verifiable, rollback time is quantified, risks are explicitly recorded.

Bad example: "Just ship it"

代码能跑了，周五之前上线吧。出问题再修。

Problems: no rollback plan, no staging verification, no monitoring confirmation, no Go/No-Go decision record. After launch, failures cannot be quickly rolled back.

Output template

Template starting point:

  • templates/feature/05-ship.md
  • templates/feature/README.md(aggregate README)
# Ship Report — <feature-name>

## 基本信息
- artifact_type: software / document / article / deck / visual
- 版本: <version>
- 发布时间: YYYY-MM-DD HH:MM

## Delivery Scope
- Deliverables:
- Commit / version / artifact path:
- Target users / audience:
- Explicitly out of scope:

## Review Carryover
- Review verdict:
- Blocking remaining:
- Important / deferred risks:
- Review conditions:

## Pre-ship Evidence
| Check | Command / Evidence | Result | Owner |
|-------|--------------------|--------|-------|

## Ship Audit Results
| Audit | Required | Auditor | Result | Blocking findings | Accepted risks |
|-------|----------|---------|--------|-------------------|----------------|

## Final Verification
- software staging:
- smoke / integration verification:
- migration / data compatibility:
- feature flag / kill switch:
- artifact export verification:
- final file / delivery package path:

## Go / No-Go Decision
| Criterion | Required | Status | Evidence |
|-----------|----------|--------|----------|
- Decision: GO / NO-GO
- Decision owner:
- Decision time:

## Rollback / Recovery Plan
- Trigger conditions:
- Recovery steps:
- Data handling:
- Expected recovery time:
- Owner:
- Non-software replacement / re-export plan:

## Documentation Sync
- Updated project docs: [paths or none]
- Deferred project docs: [paths + reasons or none]
- CHANGELOG.md updated: yes / no / n/a
- README verified: yes / no / n/a

## Post-ship Monitoring
- Observation window:
- Health checks / metrics:
- Alert thresholds:
- Monitoring owner:
- First check time:

## Handoff / Archive
- Final artifact / release path:
- Release notes / changelog path:
- Archived evidence path:
- Next command: canary / land / doc-sync / export
- Owner:

The aggregate README must use templates/feature/README.md, and retain at least:

  • Feature Summary
  • Document Index
  • Timeline
  • Key Decisions
  • Delivery Outcome
  • Verification Evidence
  • Residual Risks
  • Follow-up Actions
  • Retro Notes

Monitoring and observability

Application-level metrics

├── 错误率（总数 + 按端点）
├── 响应时间（p50 / p95 / p99）
├── 请求量
├── 活跃用户
└── 关键业务指标（转化率、参与度）

Post-launch verification

Within 1 hour after launch:

  1. Health check 200
  2. Error monitoring dashboard (no new error types)
  3. Latency dashboard (no regression)
  4. Manually test key user flows
  5. Confirm logs are flowing normally
  6. Confirm the rollback mechanism is ready

Verification failure handling

Failure scenario Handling method
Staging test failure Block. After fixing, redeploy staging; do not skip and go directly to launch
Go/No-Go rejected Return to the corresponding phase to fix (review / build), and go through pre-release checks again
Post-launch error rate spikes Roll back immediately (disable the feature flag or revert); do not "observe for a while"
Feature flag not ready Block. Do not launch. Verify in staging that the flag toggle function works properly
DB migration is not forward-compatible Blocked. Fix the migration to be forward-compatible, or split it into a two-phase deployment
Rollback plan is incomplete Blocked. Trigger conditions and steps must be completed before release

Verification evidence

The output or record must include:

  • Input/source: the spec, plan, code, feedback, or release context that was read.
  • Actions performed: the checks, generation, fixes, exports, or release steps actually completed.
  • Verification results: commands, review conclusions, artifact paths, screenshots, or manual confirmation.
  • Blockers/fallback: failed items, fallback paths, or issues requiring a decision by a human partner.

Common excuses

Excuse Reality Consequence
"It's Friday afternoon, let's ship it" No releases on Fridays. If you launch on Friday, no one is monitoring over the weekend, so the failure isn't discovered until Monday, leaving users affected for 48-72 hours.
"No feature flag needed" Every feature needs a kill switch. When a feature without a kill switch has problems, the only option is redeployment and rollback, and rollback time balloons from < 1 minute (turning off the flag) to 15-30 minutes (revert + redeploy).
"Monitoring is an extra cost" Without monitoring, failures are discovered from user complaints instead of a dashboard. From user complaint to problem localization averages 2-4 hours; with monitoring, from dashboard discovery to localization averages 5 minutes. The MTTR gap is 24-48x.
"Rollback is admitting failure" Rollback is responsible engineering. Shipping a broken feature is the failure. Refusing to roll back = letting all users keep suffering. Every extra minute of hesitation is another minute of user churn. Incident duration is positively correlated with loss of user trust.

Violating the letter of the rule is violating its spirit. There is no gray area.

Red flags

  • Deploying without a rollback plan
  • Going live without monitoring or error reporting
  • Big-bang release (all at once, with no staging)
  • Feature flag with no owner or expiration time
  • No one monitoring during the first hour after launch
  • Production configuration relies on memory instead of code
  • "It's Friday afternoon, let's ship it"

Verification checklist

Before launch:

  • Pre-release checklist complete (all green)
  • Delivery Scope clearly states deliverables, target environment, and out-of-scope items
  • Review Carryover has brought in 04-review.md verdict, conditions, and residual risks
  • Pre-ship Evidence records commands, paths, results, and owner
  • Go/No-Go Decision records criterion, evidence, owner, and time
  • Feature flag configured (if applicable)
  • Rollback / Recovery Plan documented, including trigger conditions, steps, data handling, and owner
  • Documentation Sync complete; the status of project docs that must be synchronized is clear
  • Post-ship Monitoring clearly states the observation window, metrics, thresholds, and owner
  • Handoff / Archive has clearly documented the final path and next command.
  • Aggregated README has covered 00-brainstorm.md to 07-deploy-report.md evidence status
  • The aggregated README has clearly documented the remaining risks, follow-up actions, owners, and tracking.
  • The team has been notified of the launch

After launch:

  • Health check 200
  • Error rate normal
  • Latency normal
  • Key user flows work
  • Logs flowing normally