GitHub PR Creation

Stack tooling

This repository ships .agents/skills/gh-stack/SKILL.md as a public project skill; developers do not install the agent skill separately. Read it before operating on stacked branches or PRs. Agents that consume .agents/skills/ discover it directly. If a Claude checkout is missing .claude/skills/gh-stack, run pnpm skills:sync followed by pnpm skills:check; do not download a separate global copy.

Before the first gh stack command in a task, verify the GitHub CLI and install the official extension if it is missing:

command -v gh >/dev/null 2>&1 || {
  echo "GitHub CLI is required: https://cli.github.com/" >&2
  exit 1
}
gh auth status
if ! gh stack --help >/dev/null 2>&1; then
  gh extension install github/gh-stack
fi
gh stack --help >/dev/null

Stop if authentication, installation, or the final verification fails. Do not infer a stack with ad hoc Git commands. For human-authored Cherry PRs, use gh stack push, create each compliant PR through this skill from bottom to top, then link the existing PRs with gh stack link; gh stack submit --auto creates PRs outside the template-compliant body flow and must not bypass this workflow.

Workflow

1. Read .github/pull_request_template.md before drafting the PR body.
2. Collect PR context from the current branch (base/head, scope, linked issues, testing status, breaking changes, release note content). Resolve the live base and run pnpm change:scope --base <verified-base-ref>; do not infer scope from the latest commit alone.
3. Read .agents/notes/README.md and classify the change:
   • Fill Agent Note with the repository path, or N/A — <reason> for a local/mechanical change.
   • For a Spec PR, fill Spec PR: This PR and list every AC.
   • For an implementation layer, link the Spec PR and list only the AC IDs covered by this layer. Verify an APPROVED review whose commit_id equals the current Spec head; a stale approval does not authorize implementation.
   • For a direct bug fix with durable rationale, link its implemented bug-fix note and use Spec PR: N/A.
   • Automation-authored PRs (repository workflows and Dependabot) are exempt from these metadata fields. Do not make their bodies imitate a human-authored PR.
4. For an implementation PR, complete the stack tooling preflight, then run gh stack view --json. If it exits 2, follow the gh-stack skill's remote-discovery procedure; missing local metadata does not prove the PR is standalone. Inspect every downstack implementation PR and aggregate only ACs backed by actual verification. Keep the note proposed on intermediate layers. If the current PR is the final layer and cumulative evidence covers the complete approved Spec, move the bilingual triplet to implemented/ and run pnpm agent-notes:check-transition --base <verified-spec-ref> before publishing.
5. Fill Verification with commands and scenarios actually run. Never present a planned, pending, skipped, or CI-only check as passed.
6. Check if the current branch has been pushed to remote. If not, push it first:
   • Default remote is origin, but ask the user if they want to use a different remote.

   git push -u <remote> <head-branch>
   

7. Determine the base branch:
   • Inspect the head branch before applying any default. If the head is release/v<version>, stop: never open a pull request from a release branch, especially not to main. Put an isolated fix on a topic branch and target the release branch, or let Post Release create the metadata sync branch.
   • Before defaulting an arbitrary topic branch to main, inspect its merge base and upstream. A product-code fix that started from release/v<version> must stop and be recreated from main as a hotfix; only a release-only repair or explicit backport recovery topic may target that exact release branch.
   • A backport/v<version>/pr-<number> head must target the matching release/v<version> base and its body must contain <!-- release-backport-source-pr: <number> --> on its own line for the exact source hotfix PR. A release-sync/v<version> head must target main, use the exact title chore(release): sync v<version> metadata, retain the release-metadata-boundary: v<version> body marker, and be squash-merged.
   • For official repo(CherryHQ/cherry-studio) as origin: default base is main from origin, but allow the user to explicitly indicate a base branch.
   • main is the active development line, including hotfix PRs. Do not target an old maintenance branch unless the user explicitly requests it.
   • Only classify a PR as a release hotfix when the user explicitly says it must be included in the active draft release. Use the title hotfix: <description> or hotfix(<kebab-case-scope>): <description> with a lowercase alphanumeric kebab-case scope, exactly one space after the colon, and a non-empty description. The title grammar synchronizes the hotfix label automatically. Merging opens a separate backport PR only when exactly one draft semantic-version release has a matching active release/v<version> branch; otherwise automation stops without guessing a target.
   • If the hotfix is user-facing, provide one release-note line in each language so automation can update the active draft and stable release history. Put this exact structure inside the template's existing release-note fence; do not include bullet prefixes:

     <!--LANG:en-->
     [Component] English description.
     <!--LANG:zh-CN-->
     [组件] 中文说明。
     <!--LANG:END-->
     

   • If the hotfix has no user-facing release note, keep NONE in the template's release-note fence. The code is still backported, but release metadata is unchanged. A provided bilingual block must satisfy the exact structure above.
   • For fork repo as origin: check available remotes with git remote -v, default base may be upstream/main or another remote. Always assume that user wants to merge head to CherryHQ/cherry-studio/main, unless the user explicitly indicates a base branch.
   • Ask the user to confirm the base branch if it's not the default.
8. Create a temp file and write the PR body using a single Bash heredoc (avoids mktemp + Write tool path-mismatch on Windows):

   pr_body_file="/tmp/gh-pr-body-$(date +%s).md"
   cat > "$pr_body_file" <<'EOF'
   ...filled template body...
   EOF
   

   Fill content using the template structure exactly (keep section order, headings, checkbox formatting). If not applicable, write N/A or None.
9. Inspect the temp file content via Bash cat "$pr_body_file" (the Read tool can fail on /tmp/... paths on Windows). If the user requests a preview or confirmation, show the full body and follow that request; otherwise, proceed with the authorized PR creation.
10. Create the PR, adding --draft when the user requests a draft:

gh pr create --base <base> --head <head> --title "<title>" --body-file "$pr_body_file"

For a release hotfix, use an exact classifier-compatible title so the workflow synchronizes the label and separately validates any provided bilingual note:

gh pr create --base main --head <head> --title "hotfix: <description>" --body-file "$pr_body_file"

After creation, verify that the classifier added hotfix; if it did not, fix the title instead of adding the label manually. Also fix any malformed optional release-note block reported by the workflow. 11. Clean up the temp file: rm -f "$pr_body_file" 12. Report the created PR URL and summarize title/base/head, Agent Note/Spec, AC coverage, actual verification, and any required follow-up.

Constraints

• Never skip template sections.

• Never rewrite the template format.

• Keep content concise and specific to the current change set.

• PR title and body must be written in English.

• Never use a hotfix title or label for an ordinary bug fix. It opts the PR into an automatic backport PR after merge when one matching draft release is active.

• A release hotfix may use NONE when it has no user-facing release note. Never provide a partial, single-language, or otherwise malformed bilingual note; the backport workflow fails closed on malformed content.

• Never default a release/v<version> head to main; a release branch is not a pull request source branch.

• Never publish an implementation PR as ready when its current Spec head lacks an exact-head Approval. A Spec may remain unmerged and serve as the stack base.

• Every human-authored PR fills Agent Note, Spec PR, and Acceptance criteria; N/A requires a concise reason. Automation-authored PRs (repository workflows and Dependabot) are exempt from this metadata requirement.

• Release note & Documentation checkbox — both are driven by whether the change is user-facing. Use the table below:

  Change type	Release note	Docs [x]
  New user-facing feature / setting / UI	Describe the change	✅
  Bug fix visible to users	Describe the fix	✅ if behavior changed
  Behavior change / default value change	Describe + action required	✅
  Security fix in a user-facing dependency	Describe the fix	✅ if usage changed
  CI / GitHub Actions changes	NONE	❌
  Internal refactoring (user cannot tell)	NONE	❌
  Dev / build tooling changes	NONE	❌
  Dev-only dependency bump	NONE	❌
  Test-only / code style changes	NONE	❌

Command Pattern

# read template
cat .github/pull_request_template.md

# prepare and inspect the PR body
pr_body_file="/tmp/gh-pr-body-$(date +%s).md"
cat > "$pr_body_file" <<'EOF'
...filled template body...
EOF
cat "$pr_body_file"

# create the authorized PR; add --draft when requested
gh pr create --base <base> --head <head> --title "<title>" --body-file "$pr_body_file"
rm -f "$pr_body_file"