design-ship

Design Ship

1 つのコマンドで、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 — インポート

バンドル引数を指定して 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 を実行します。

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	来歴の更新

このスキルの担当外

項目	担当
バンドルの解析	design-import から呼び出される claude-design-orchestrator エージェント
コンポーネントの重複排除	design-import から呼び出される Orchestrator エージェント
テストの実行（CI）	GitHub Actions — このスキルが行うのはテストの生成のみです
PR のマージ	人間のレビュアー — 自動マージは決して行いません

制限事項

• 自動マージはありません：このスキルは PR を作成します。レビューとマージは人間が行います。
• 反復ループはありません：PR のレビューでデザインの変更が必要になった場合、現在は Claude Design から再エクスポートし、design-ship を再実行します。逆方向の処理（ライブ UI のずれ → claude.ai/design 向けの調整プロンプト）は、M124 — Claude Design Drift Sync (Bet B)：#1391（PR フック）、#1393（design-iterate）、#1395（design-drift-detector エージェント）で追跡されています。
• 単一バンドルのみ：1 回の実行につき、1 つのバンドル、1 つの PR です。複数バンドルの一括処理には対応していません。