design-ship

设计交付

一条命令：Claude Design 交接 URL → 可供审核的 GitHub PR。

design-ship https://claude.ai/design/abc123     # From handoff URL
design-ship /tmp/handoff-bundle.json            # From local file

适用场景

你有一个 Claude Design 交接 URL（或文件），并希望针对当前分支创建 PR。无需中间步骤，无需手动生成测试，也无需手动起草 PR。

如果只需导入（不需要测试或 PR），请改用 design-import。

流程

Handoff bundle (URL or file)
  │
  ▼
┌──────────────────────────────┐
│ 1. design-import         │  Scaffold components, write provenance
│    (delegates to orchestrator │  Tokens reconciled
│     for parse + dedup)        │  Components written or reused
└──────────┬───────────────────┘
           │
           ▼
┌──────────────────────────────┐
│ 2. cover                 │  Storybook stories per new component
│    (Storybook + Playwright)   │  Playwright E2E for new routes/views
└──────────┬───────────────────┘
           │
           ▼
┌──────────────────────────────┐
│ 3. expect                │  Diff-aware browser verification
│    (CDP + ARIA-tree-first)    │  Screenshots saved for PR body
└──────────┬───────────────────┘
           │
           ▼
┌──────────────────────────────┐
│ 4. create-pr             │  PR opened with:
│                               │   - Claude Design URL link
│                               │   - Before/after screenshots
│                               │   - Component scaffold list
│                               │   - Coverage delta
│                               │   - Label: claude-design
└──────────┬───────────────────┘
           │
           ▼
┌──────────────────────────────┐
│ 5. UPDATE PROVENANCE          │  Patch .claude/design-handoffs/<id>.json
│                               │  with the opened PR number + URL
└──────────────────────────────┘

预检

启动流程前，请确认工作区足够干净，可以交付：

status = Bash("git status --porcelain")
if status:
    AskUserQuestion(questions=[{
      "question": "Working tree has uncommitted changes. How to proceed?",
      "header": "Pre-flight",
      "options": [
        {"label": "Commit them first", "description": "Run commit, then proceed with ship"},
        {"label": "Stash and restore", "description": "Stash now, restore after PR opens"},
        {"label": "Include in this PR", "description": "Risky — only if changes are related"},
        {"label": "Cancel", "description": "Abort design-ship"}
      ],
      "multiSelect": False
    }])

current_branch = Bash("git branch --show-current")
if current_branch in ("main", "master", "dev"):
    AskUserQuestion(questions=[{
      "question": f"You're on {current_branch}. Create a feature branch?",
      "header": "Branch",
      "options": [
        {"label": "Yes — feat/design-ship-<bundle-id>", "description": "Recommended"},
        {"label": "Cancel", "description": "Switch branch yourself first"}
      ],
      "multiSelect": False
    }])

阶段 1 — 导入

使用 bundle 参数委派给 design-import。记录其输出（导入清单）——其中包含 bundle_id、写入的组件列表和溯源文件路径。

如果导入失败，请停止。不要基于仅部分导入的组件继续生成测试。

阶段 2 — 覆盖

针对阶段 1 写入的组件运行 cover：

component_paths = [c["path"] for c in import_result["components"] if c["decision"] != "reuse"]

Agent(
  subagent_type="ork:test-generator",
  description="Cover the freshly-imported components",
  prompt=f"""Use the cover skill to generate tests for these components (scoped — do not regenerate suites for unrelated files):
  {component_paths}

  Tiers needed:
  - Storybook stories per component (mandatory)
  - Playwright E2E if any new route was registered (check src/app or src/pages)
  - Unit tests if the components include non-trivial logic (skip for pure-presentation)
  """
)

阶段 3 — 验证

运行 expect，执行感知差异的浏览器验证。此步骤会生成放入 PR 正文的截图：

Agent(
  subagent_type="ork:expect-agent",
  description="Diff-aware verification of imported components",
  prompt=f"""Use the expect skill on the current diff.

  Extra: capture before/after screenshots for each new component
  and save them to .claude/design-handoffs/{bundle_id}/screenshots/.
  These will be uploaded to the PR body.

  If verification fails, do not block — report findings and continue.
  Failures will surface in the PR review.
  """
)

阶段 4 — 创建 PR

使用 create-pr，根据 bundle 和验证结果生成正文模板：

pr_body = f"""## Summary
Generated from Claude Design handoff: {bundle_url}

Bundle ID: `{bundle_id}` · Provenance: `.claude/design-handoffs/{bundle_id}.json`

## Components
| Decision | Component | Path |
|---|---|---|
{table_from(import_result['components'])}

## Tokens
- Added: {len(token_diff['added'])}
- Modified: {len(token_diff['modified'])}
- Conflicts (resolved): {len(token_diff['conflicts'])}

## Verification (`expect`)
{expect_summary}

## Coverage delta (`cover`)
{coverage_delta}

## Screenshots
{screenshot_table}

---
🤖 Opened by `design-ship` · Closes: (none — link issues manually)
"""

Bash(f"gh pr create --title '{pr_title}' --body @- <<< '{pr_body}' --label claude-design")

阶段 5 — 更新溯源信息

在溯源文件中补充已创建的 PR 编号和 URL：

provenance = Read(f".claude/design-handoffs/{bundle_id}.json")
provenance["pr"] = {"number": pr_number, "url": pr_url, "opened_at": now()}
Write(f".claude/design-handoffs/{bundle_id}.json", provenance)

失败情况

阶段	失败情况	处理方式
预检	工作区不干净，位于 main 分支	使用 AskUserQuestion 询问，不要悄悄继续
1. 导入	架构偏差、令牌冲突	design-import 已会提示；如果用户取消，则中止
2. 覆盖	测试生成失败	继续执行验证——测试可以在 PR 审核中补救
3. 验证	浏览器验证失败	继续创建 PR——在 PR 正文中注明失败情况
4. 创建 PR	gh 未通过身份验证	停止并显示身份验证错误
5. 溯源信息	文件不可写	发出警告，但不要判定失败（PR 已创建）

组合

技能	作用
design-import	阶段 1 — 搭建组件框架
cover	阶段 2 — Storybook + Playwright
expect	阶段 3 — 感知差异的浏览器验证
create-pr	阶段 4 — 使用模板正文创建 PR
remember / memory	更新溯源信息

本技能不负责的事项

事项	负责方
解析 bundle	claude-design-orchestrator Agent（由 design-import 调用）
组件去重	Orchestrator Agent（由 design-import 调用）
执行测试（CI）	GitHub Actions——本技能只生成测试
合并 PR	人工审核者——绝不自动合并

限制

• 不自动合并：本技能会创建 PR，由人工审核并合并。
• 无迭代循环：如果 PR 审核发现设计需要修改，目前需要从 Claude Design 重新导出并重新运行 design-ship。反向路径（实时 UI 偏差 → 为 claude.ai/design 生成优化提示词）正在 M124 — Claude Design Drift Sync（Bet B）中跟踪：#1391（PR hook）、#1393（design-iterate）、#1395（design-drift-detector Agent）。
• 仅支持单个 bundle：每次调用处理一个 bundle，创建一个 PR。不支持批量处理多个 bundle。