Rationalize PR creation skills with platform-specific entry points

[williamthorsen]

Problem

The current PR creation flow is fragmented. summarize-change generates a change summary, prepare-pr adds a prefix, and create-pr calls gh pr create — but they don't compose cleanly. There is no way to pass scope/type context through the flow, which blocks features like label application. prepare-pr exists as an intermediary that doesn't match a user-desired action.

Context

• summarize-change generates change-summary.md with title, body, and metadata — it's standalone and reusable
• create-pr reads the change summary and calls gh pr create, but doesn't resolve scope, type, or labels
• prepare-pr bridges summarize-change and create-pr by adding a title prefix — but it doesn't match a user action and is a candidate for absorption
• create-ticket already demonstrates the full pattern: resolves scope/type via describe-change.sh, applies labels from .meta/label-map.json
• The change summary currently has no structured frontmatter — title and metadata must be parsed from markdown

Solution

Single entry point with platform-specific delegates

Restructure into three skills following the strategy pattern:

create-pr (user-invocable) — the orchestrator. Handles the complete flow:

1. Accept optional scope/type arguments
2. Get session context
3. Call summarize-change to produce the change summary
4. Read structured frontmatter from the change summary to extract title, scope, type
5. Call describe-change.sh to resolve PR title prefix; apply to title only if non-empty
6. Resolve labels from .meta/label-map.json (if it exists), following the create-ticket pattern
7. Detect platform and delegate to the appropriate internal skill, passing: final title, body, labels, platform context

create-gh-pr (internal, user-invocable: false) — GitHub delegate. Receives fully prepared data:

• Creates PR via gh pr create --draft with --label flags for resolved labels
• Handles label application failures gracefully (proceeds without failing labels)
• Saves a PR artifact recording what was submitted (title, body, labels, PR URL)

create-bitbucket-pr (internal, user-invocable: false) — Bitbucket delegate. Receives fully prepared data:

• Creates PR using available Bitbucket tooling, applying labels
• Handles label application failures gracefully
• Saves a PR artifact recording what was submitted

Change to summarize-change

Add YAML frontmatter to the change summary artifact so downstream consumers can read structured fields without parsing markdown:

---
title: "Rationalize PR creation skills"
ticket_id: "409"
commit: "abc1234"
scope: "agents"
type: "feat"
---

Cleanup

• Retire prepare-pr — its responsibilities (prefix resolution, artifact saving) are absorbed by the orchestrator and delegates
• Revamp create-pr — from a simple GitHub-only script reader to the platform-aware orchestrator

Acceptance criteria

• summarize-change emits structured YAML frontmatter (title, ticket_id, commit, scope, type)
• create-pr orchestrates the full flow: calls summarize-change, reads frontmatter, resolves prefix and labels, detects platform, delegates
• create-gh-pr (internal) receives prepared data and creates GitHub PRs with label support
• create-bitbucket-pr (internal) receives prepared data and creates Bitbucket PRs with label support
• Delegates handle label application failures gracefully (create PR without failing labels)
• Delegates save a PR artifact recording what was submitted (title, body, labels, PR URL)
• prepare-pr is retired
• New/modified behavior in this change is covered by tests

[williamthorsen]

Insight from implementation run: describe-change.sh handles type-only calls correctly — when only --type is provided (no --scope), the prefix is always {type}: regardless of the configured convention. This enabled the create-pr orchestrator to use a conditional --scope pattern in step 6 rather than requiring both scope and type for prefix resolution. Confirmed by reading commit-format.md.