Design Ship
One command: Claude Design handoff URL โ reviewable GitHub PR.
/ork:design-ship https://claude.ai/design/abc123
/ork:design-ship /tmp/handoff-bundle.json
When to use
You have a Claude Design handoff URL (or file) and want a PR opened against the current branch. No intermediate steps, no manual test generation, no manual PR drafting.
For just-the-import (no tests, no PR), use /ork:design-import instead.
Pipeline
Handoff bundle (URL or file)
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ 1. /ork:design-import โ Scaffold components, write provenance
โ (delegates to orchestrator โ Tokens reconciled
โ for parse + dedup) โ Components written or reused
โโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ 2. /ork:cover โ Storybook stories per new component
โ (Storybook + Playwright) โ Playwright E2E for new routes/views
โโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ 3. /ork:expect โ Diff-aware browser verification
โ (CDP + ARIA-tree-first) โ Screenshots saved for PR body
โโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ 4. /ork: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
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Pre-flight
Before starting the pipeline, verify the working tree is clean enough to ship:
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 /ork: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
}])
Phase 1 โ Import
Delegate to /ork:design-import with the bundle argument. Capture its output (the import manifest) โ it includes the bundle_id, list of components written, and the provenance file path.
If import fails, stop. Do NOT proceed to test generation against partially-imported components.
Phase 2 โ Cover
Run /ork:cover scoped to the components written by phase 1:
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)
"""
)
Phase 3 โ Expect
Run /ork:expect to do diff-aware browser verification. This produces the screenshots that go into the PR body:
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.
"""
)
Phase 4 โ Create PR
Use /ork:create-pr with a body templated from the bundle and verification results:
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 (`/ork:expect`)
{expect_summary}
## Coverage delta (`/ork:cover`)
{coverage_delta}
## Screenshots
{screenshot_table}
---
๐ค Opened by `/ork:design-ship` ยท Closes: (none โ link issues manually)
"""
Bash(f"gh pr create --title '{pr_title}' --body @- <<< '{pr_body}' --label claude-design")
Phase 5 โ Update provenance
Patch the provenance file with the opened PR number and 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)
Failure modes
| Phase | Failure | Behavior |
|---|
| Pre-flight | Dirty tree, on main | AskUserQuestion, do not proceed silently |
| 1. Import | Schema deviation, token conflict | design-import already prompts; if user cancels, abort |
| 2. Cover | Test generation fails | Continue to expect โ tests are recoverable in PR review |
| 3. Expect | Browser verification fails | Continue to PR โ failures noted in PR body |
| 4. Create PR | gh not authenticated | Stop, surface auth error |
| 5. Provenance | File not writable | Warn but do not fail (PR is already open) |
Composition
| Skill | Role |
|---|
design-import | Phase 1 โ scaffold components |
cover | Phase 2 โ Storybook + Playwright |
expect | Phase 3 โ diff-aware browser verification |
create-pr | Phase 4 โ open PR with templated body |
remember / memory | Provenance updates |
NOT this skill's job
| Concern | Owned by |
|---|
| Parsing bundles | claude-design-orchestrator agent (called by design-import) |
| Component dedup | Orchestrator agent (called by design-import) |
| Test execution (CI) | GitHub Actions โ this skill only generates tests |
| Merging the PR | Human reviewer โ never auto-merge |
Limitations
- No auto-merge: this skill opens the PR; humans review and merge.
- No iteration loop: if the PR review surfaces design changes, you currently re-export from Claude Design and re-run
/ork:design-ship. The reverse-path (live UI drift โ refinement prompt for claude.ai/design) is tracked in M124 โ Claude Design Drift Sync (Bet B): #1391 (PR hook), #1393 (/ork:design-iterate), #1395 (design-drift-detector agent).
- Single-bundle scope: one invocation, one bundle, one PR. Multi-bundle batches are not supported.
