name: create-pr description: Validate tests and docs, then create a GitHub PR with conventional commit formatting disable-model-invocation: true argument-hint: [base branch]
Create Pull Request
Validate that all tests and documentation pass, then create a well-formatted GitHub PR for the current branch.
Context
Current branch:
!git branch --show-current
Repository:
!git remote get-url origin 2>&1
Commits on this branch (vs main):
!git log --oneline main..HEAD 2>&1 || git log --oneline origin/main..HEAD 2>&1 || echo "Could not determine commits"
Changed files (vs main):
!git diff --stat main..HEAD 2>&1 || git diff --stat origin/main..HEAD 2>&1 || echo "Could not determine changes"
Existing open PR for this branch:
!gh pr view --json number,title,url,state 2>&1 || echo "NO_EXISTING_PR"
Arguments
$ARGUMENTS
If $ARGUMENTS specifies a base branch, use that instead of the default branch.
Workflow
Follow these steps in strict order. Do NOT skip ahead.
Step 0: Pre-flight checks
- Verify the current branch is NOT
main. If it is, stop and tell the user to create a feature branch first. - If a PR already exists for this branch, inform the user and ask whether to update the existing PR description or stop.
- Ensure all changes are committed. If there are uncommitted changes, inform the user and stop.
- DCO sign-off check: Verify that every commit on this branch has a
Signed-off-by:line:
git log main..HEAD --format="%h %s" --no-merges | while read hash rest; do
if ! git log -1 --format="%b" "$hash" | grep -q "^Signed-off-by:"; then
echo "MISSING DCO: $hash $rest"
fi
done
If any commits are missing DCO sign-off, report them and stop. Instruct the user to fix with:
git rebase main --exec "git commit --amend --signoff --no-edit"
Do NOT create the PR until all commits have DCO sign-off.
Step 1: Identify affected packages
Examine the commit history and changed files to determine which libs/* packages were modified. This determines which workspaces need building, testing, and which scopes to use in the PR title.
Step 2: Build affected packages
Build each affected package:
npm run build -w libs/<package>
If a build fails, report the error and stop. Do NOT create the PR.
Step 3: Run tests
Run tests for each affected package:
npm test -w libs/<package>
If any test fails, report the error and stop. Do NOT create the PR.
Step 4: Run typecheck
npm run typecheck
If the typecheck fails on files within libs/ (ignore pre-existing errors in node_modules), report the error and stop. Do NOT create the PR.
Step 5: Build and validate documentation
Build the documentation to catch TSDoc errors, broken {@includeCode} references, and missing documentation:
npm run build -w docs
Review the output for warnings and errors. If there are documentation errors related to the changed packages, report them and stop. Do NOT create the PR.
Step 6: Find related GitHub issues
Search for related open issues in the repository:
gh issue list --state open --json number,title --limit 50
Also check the commit messages and branch name for issue references (e.g., #123, issue-123, fixes-123).
Present any potentially related issues to the user and ask which (if any) should be referenced in the PR.
Step 7: Draft the PR title and description
Title Format
Follow conventional commit format. The title must be under 70 characters.
Pattern: <type>(<scope>): <short description>
Types:
feat- New feature or public API additionfix- Bug fixrefactor- Code change that neither fixes a bug nor adds a featuredocs- Documentation only changestest- Adding or correcting testschore- Maintenance, tooling, or dependency updatesbuild- Changes that affect the build systemperf- Performance improvement
Scope: The package name without the libs/ prefix (e.g., cmcd, iso-bmff, utils). If multiple packages are affected, use the primary package or omit the scope.
Examples:
feat(cmcd): add CmcdReporter classfix(iso-bmff): handle non-zero byteOffset in parsePsshListrefactor(utils): rename RequestType to ResponseTypefeat: add throughput measurement library
Description Format
Use this template:
## Summary
<1-4 bullet points describing what changed and why>
## Packages Changed
| Package | Version | Change Type |
|---------|---------|-------------|
| @svta/cml-<name> | x.x.x | feat/fix/etc |
## Test Plan
- [ ] <specific test scenarios that validate the changes>
Refs: <issue references>
Refs footer rules:
- Use
Fixes #Nif the PR fully resolves an issue (this auto-closes the issue on merge) - Use
Refs #Nif the PR is related but does not fully resolve the issue - Multiple references are comma-separated:
Refs: #12, #34, Fixes #56 - Only include issue references confirmed by the user in Step 6
- Omit the
Refs:line entirely if there are no related issues
Step 8: Present for approval
Show the user the complete PR title and description. Ask for approval or revisions. The user may:
- Approve as-is
- Modify the title, description, or issue references
- Request changes to the scope or type
Do NOT create the PR until the user explicitly approves.
Step 9: Push and create the PR
- Ensure the branch is pushed to the remote:
git push -u origin <branch-name>
- Create the PR:
gh pr create --base <base-branch> --title "<title>" --body "$(cat <<'EOF'
<description>
EOF
)"
- Display the PR URL to the user.
Important Notes
- Never create a PR with failing tests or documentation errors.
- The conventional commit type in the PR title should reflect the primary change, not every change.
- Keep the title under 70 characters. Use the description for details.
- The summary bullets should explain why the changes were made, not just what files changed.
- If builds are slow, only build packages that are directly affected by the changes and their dependents.
- Always push with
-uto set up tracking if not already configured. - Every commit must have DCO sign-off. Always use
git commit -sand includeCo-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>in the message body. If you need to fix issues discovered during validation (Steps 2-5), commit the fixes with these requirements before proceeding.