create-pr

name	create-pr
description	Pull-request creation workflow. Use when repositories have pending changes or unpushed commits and you want ready-for-review PRs created.

You are executing a command to create a pull request with the current changes.

<shared_core_loading> If the implement-changes skill is not currently loaded into your context, load that skill before deeper execution. When loading implement-changes from this child skill, inherit only the core-contract section and the matching parent child-path contract for this workflow. Do not execute implement-changes's default workflow from this child skill unless the caller explicitly instructed the parent default path to run first. This child skill remains the canonical owner of its delivery mechanics even when the parent skill is loaded for shared context. </shared_core_loading>

<delivery_branch_invariant> Before staging files, writing /tmp/pr-body.md, committing, pushing, or calling mcp__roomote__manage_source_control, ensure each repository is on the delivery branch for this task, created from the provided base/default branch when a new branch is needed. Do not perform delivery work directly from main or master unless the user explicitly selected that branch as the existing delivery branch for this task. </delivery_branch_invariant>

<pull_request_base_invariant> For every pull request, pass the provided base/default branch explicitly as targetBranch in the mcp__roomote__manage_source_control call; do not rely on the provider's repository default branch or the current local tracking branch to choose the PR base. Pass targetBranch on refresh calls too, so an existing pull request keeps its intended base relationship. </pull_request_base_invariant>

Create or refresh pull requests for every repository in the current workspace that has pending changes or unpushed commits. The current directory contains a `.git` directory. The current directory is not itself a git repository but contains child directories that are repositories. No repository has uncommitted changes or unpushed commits after workspace detection. Identify every repository that needs a pull request and collect the metadata required to create it safely. Detect the workspace layout and changed repositories Determine whether the workspace is a single repository or a container of multiple repositories, then enumerate every repository with pending work. Run `echo "=== Workspace Detection ===" && pwd && echo "" && if [ -d ".git" ]; then echo "WORKSPACE_TYPE: SINGLE_REPO"; echo "REPO_DIR: $(pwd)"; echo "REPO_NAME: $(git remote get-url origin 2>/dev/null | sed -E 's|.*[:/]([^/]+/[^/]+)$|\1|' | sed 's/\.git$//' || basename $(pwd))"; else echo "WORKSPACE_TYPE: MULTI_REPO"; echo "=== Repos with Changes ==="; workspace_root=$(pwd); shopt -s nullglob; for repo_dir in */; do if [ -d "$workspace_root/${repo_dir}.git" ]; then cd "$workspace_root/$repo_dir"; has_changes=false; if [ -n "$(git status --porcelain 2>/dev/null)" ]; then has_changes=true; fi; if [ -n "$(git log origin/HEAD..HEAD --oneline 2>/dev/null)" ]; then has_changes=true; fi; if [ "$has_changes" = "true" ]; then repo_name=$(git remote get-url origin 2>/dev/null | sed -E 's|.*[:/]([^/]+/[^/]+)$|\1|' | sed 's/\.git$//' || basename $(pwd)); echo "CHANGED_REPO: ${repo_dir%/} -> $repo_name"; fi; fi; done; cd "$workspace_root"; for owner_dir in */; do if [ ! -d "$workspace_root/${owner_dir}.git" ]; then cd "$workspace_root"; for repo_dir in "$owner_dir"*/; do if [ -d "$workspace_root/${repo_dir}.git" ]; then cd "$workspace_root/$repo_dir"; has_changes=false; if [ -n "$(git status --porcelain 2>/dev/null)" ]; then has_changes=true; fi; if [ -n "$(git log origin/HEAD..HEAD --oneline 2>/dev/null)" ]; then has_changes=true; fi; if [ "$has_changes" = "true" ]; then repo_name=$(git remote get-url origin 2>/dev/null | sed -E 's|.*[:/]([^/]+/[^/]+)$|\1|' | sed 's/\.git$//' || basename $(pwd)); echo "CHANGED_REPO: ${repo_dir%/} -> $repo_name"; fi; fi; done; cd "$workspace_root"; fi; done; shopt -u nullglob; cd "$workspace_root"; fi`. Capture each changed repository and conclude with a user-facing no-op explanation if no repositories require action. Every changed repository is listed explicitly and the execution path is known to be single-repo, multi-repo, or no-op. Derive branch, commit, and repository metadata for each repository Inspect the pending work in every changed repository and derive the exact metadata required before commit, push, and pull request creation. For each repository, determine the final `owner/repo` from the git remote, the current branch, and the provided base/default branch for this run. If no branch is provided for the run, use the repository default branch. For each repository, derive a branch name using `feature/-` or `fix/-` in kebab-case. Choose a conventional commit message for each repository. [Type] user-facing description New capability or behavior visible to the user. Bug fix. Description must use the pattern "... when user [does X]" or "... [user-visible symptom]" so the title names the symptom, not the code fix. Enhancement to existing behavior, UX polish, or quality-of-life change. Code restructuring with no user-visible behavior change. Documentation-only change. Dependency updates, config, CI, infra, or other non-functional maintenance. Use a single bracketed type tag such as `[Fix]` or `[Feat]`, then continue with the user-facing description in plain text. Start every title with exactly one singular bracketed type tag such as `[Fix]`, `[Feat]`, `[Improve]`, `[Refactor]`, `[Docs]`, or `[Chore]`. Keep the bracket contents to the type only, using forms like `[Fix]`, `[Feat]`, `[Improve]`, `[Refactor]`, `[Docs]`, or `[Chore]`. Follow the bracketed type tag with a space and then the description. Lead with what the user sees or can do, not the implementation detail. Write the user-facing description in sentence case. Capitalize the first word after the bracketed tag and preserve proper nouns and acronyms. For fixes, frame as the user-visible symptom: "task list fails to load when user has no environments", not "add null check to getTaskList query". For non-fix titles, use present-tense imperative mood. For features, name the capability: "Add bulk-cancel action to task dashboard", not "implement BulkCancelButton component". For improvements, name the better experience: "Show environment name in task status notifications", not "pass env name through notification context". [Fix] Task list fails to load when user has no environments [Feat] Add bulk-cancel action to task dashboard [Improve] Show environment name in task status notifications

Summarize the shipped change in reviewer-facing terms. For fixes, describe the broken behavior and the visible correction. For features or improvements, name the new capability or better experience. For refactors, docs, and chores, describe the internal or maintenance change plainly without inventing user-facing drama. Avoid file-by-file narration.

One or two sentences connecting the change to the motivation or risk it addresses. Mention the user problem, new capability, maintenance goal, or reviewer-relevant constraint as appropriate. Include implementation detail only when it helps the reviewer understand outcome or risk.

Describe the effect of the change. Lead with the concrete user-visible result when there is one. When there is no intended user-facing change (for example refactor, docs, or chore work), say so plainly and state the operational, maintenance, or reviewer-visible benefit instead.

Do not include this as a standalone PR body section for routine successful runs. Mention validation only when a check failed, was skipped or unavailable, materially changes reviewer confidence, or the user explicitly asked for it, and then fold that caveat into the relevant existing section instead of adding `## Validation`, `## Checks`, or `## Status`.

Include only when the same task ships through multiple pull requests. Link the sibling PRs with short labels such as repository names or user-facing split names like frontend/backend. Omit the current PR, and remove stale links when the task split changes.

Each repository has a complete execution bundle: repo directory, target repository, base branch, delivery branch name, and commit message. Create or reuse the delivery head branch, commit the work on that branch, push it, and create or refresh one pull request per changed repository. Create the delivery branch from the provided base branch Use the provided base/default branch for this run as the source for the delivery branch. For example, if the provided base is `develop`, create the delivery branch from `origin/develop`. For each repository, fetch the provided base branch with `cd && git fetch origin `. If a new delivery branch is needed, run `cd && git checkout -b origin/` before staging or committing pending work. If already on an explicit existing delivery branch for this task, keep that branch. Record the final delivery branch name and base branch before proceeding. Every repository that is being prepared for a pull request is on a delivery branch created from the provided base branch, or is explicitly identified as already on an existing delivery branch for this task. Commit any uncommitted work Stage and commit pending local changes repository by repository, while preserving hook-based safeguards. For repositories with uncommitted changes, run `cd && git add -A && git diff --cached --name-status`. After `git add -A`, explicitly compare `git diff --cached --name-status` against the intended deliverables for this task. If any staged path is unexpected, unstage it with `git restore --staged ` before committing. Treat generated or untracked files as excluded by default unless they are clearly part of the requested delivery. After the staged-path review is complete, run `cd && git commit -m ''`. If a repository has only unpushed commits and no working tree changes, skip the commit step for that repository. If hooks fail, fix the underlying issue instead of bypassing validation with `--no-verify` unless no other safe option remains. Every repository is either clean with a new commit or intentionally skipped because it already had the necessary commits. Push the target branch Push each repository's current HEAD to the remote after the delivery branch and commit state are correct. For each repository, run `cd && git push origin HEAD`. Record the final branch name and confirm the remote push succeeded before proceeding. Every repository that is being prepared for a pull request has a pushed remote branch. Create or refresh one pull request per repository Use the derived metadata to either open a new pull request or refresh the existing one for each repository with pending work, targeting the same provided base branch. For each repository, derive the current branch with `cd && git rev-parse --abbrev-ref HEAD`. Do not use provider-specific PR CLIs such as `gh` for creation or refresh; the `mcp__roomote__manage_source_control` tool handles open pull request lookup and provider-specific mutation server-side. Use the identical `pr-metadata-update-recipe` block below after the push and before the create or refresh call. In this ready-for-review workflow, execute the recipe's `mcp__roomote__manage_source_control` call. The platform opens new pull requests in the draft or ready-for-review state configured by the deployment PR delivery setting and preserves the existing state on refresh. Include `labels` with the conflict resolver label when one is provided, and do not pass `labels` when none is provided. When provider-compatible assignee usernames are provided for this run, pass them as `assignees` in the `mcp__roomote__manage_source_control` call so the created or refreshed pull request is assigned to those users. Before any `mcp__roomote__manage_source_control` call, run the recipe's required PR metadata contract check. If the check fails, rewrite `/tmp/pr-body.md` and the title until it passes; do not create or refresh a pull request with non-contract metadata. Collect the pull request number and URL returned by each successful `mcp__roomote__manage_source_control` result, and treat that tool result as the live pull request reference instead of treating the final message as proof that the pull request exists. After the first creation or refresh pass, if this run produced or refreshed more than one pull request for the same task, rebuild each PR body so it includes a `## Related PRs` section linking the sibling pull requests by repository or surface label, then call `mcp__roomote__manage_source_control` again for each sibling pull request to backfill those cross-links. When maintaining the `## Related PRs` section, omit self-links, keep only sibling pull requests from the current task split, and remove stale links to superseded or unrelated PRs. Run `git diff $(git merge-base HEAD origin/ 2>/dev/null || echo "HEAD~1") HEAD` to capture the full shipped diff for the branch. Use this local git diff for every provider. When an earlier delivery pass in this task produced a `/tmp/pr-body.md`, read it before overwriting it so still-applicable metadata can be recovered, including current `## Related PRs` links, `## Linked work items`, and proof sections; this workflow does not read the remote pull request body. Call the Roomote MCP tool `mcp__roomote__manage_tasks` with `action: "get_messages"` for the current task using `limit: 20`. Reverse the returned newest-first message list before extracting the original problem statement, motivation, and key decisions from the conversation history. Use the recovered conversation to choose which participant the pull request is opened on behalf of. Prefer the person who requested or explicitly authorized the implementation or PR creation; do not infer ownership from thread ownership, task initiation, or the latest comment alone. When one participant is clear, pass their conversation display name or source-control login as `prAttribution`. If the conversation is genuinely ambiguous, omit `prAttribution` so the platform retains current acting-user attribution. Before writing `/tmp/pr-body.md`, check for a checked-in repository pull request or merge request template in the locations the repository's source-control provider supports. On GitHub, inspect `.github/pull_request_template.md`, `.github/PULL_REQUEST_TEMPLATE.md`, any `.md` files inside `.github/PULL_REQUEST_TEMPLATE/`, `docs/pull_request_template.md`, `docs/PULL_REQUEST_TEMPLATE.md`, `pull_request_template.md`, and `PULL_REQUEST_TEMPLATE.md`. On GitLab, inspect the `.md` files inside `.gitlab/merge_request_templates/`, preferring `Default.md` when present. On Gitea, inspect `.gitea/pull_request_template.md`, `.gitea/PULL_REQUEST_TEMPLATE.md`, any `.md` files inside `.gitea/PULL_REQUEST_TEMPLATE/`, and the same root-level and `docs/` fallbacks GitHub supports. On Azure DevOps, inspect `.azuredevops/pull_request_template.md`, any branch-specific `.md` files inside `.azuredevops/pull_request_template/branches/`, `docs/pull_request_template.md`, and root-level `pull_request_template.md`. Match the repo's actual filename casing when present. When multiple template files exist in the directory path, choose the single template that best matches the current PR scope and treat it as the selected repo template for this run. Write `/tmp/pr-body.md` using the shipped diff, the recovered conversation, and any still-applicable metadata recovered from the previous `/tmp/pr-body.md`. When a selected repo template exists, use it as the starting scaffold for `/tmp/pr-body.md`: preserve its reviewer-facing headings, checklist items, and other required structure, replace placeholder guidance with final content, and merge the `pr-writing-guide` substance into that scaffold instead of replacing the template. When no repo template exists, structure the body per the `pr-writing-guide` section below. If the caller supplied a PR provenance block, make it the opening blockquote. Preserve or refresh `## Related PRs` when the previous `/tmp/pr-body.md` or current task context identifies sibling PRs. Preserve or refresh `## Linked work items` when the previous `/tmp/pr-body.md` or current workflow instructions identify linked work items. When the current workflow instructions include a pre-rendered linked-work-item block for this run, include that block verbatim and do not rewrite provider-specific closing or reference syntax. When the latest `capture-visual-proof` handoff reports an uploaded artifact list from `manage_artifacts` upload results, treat it as the authoritative proof-section input: render `## Screenshots` from its reported screenshots only when present, embedding each screenshot as `![]()` so the image renders inline in the PR body; do not create `## Visual proof` for screenshots and do not render screenshot artifact viewer links when `rawUrl` exists; render `## Screencasts` from its reported screencasts only when present using `[![]()]()`, plus a caption line below each embed, where `` is the clip's uploaded `viewUrl`, and explicitly remove any existing `## Screenshots` or `## Screencasts` section whose latest reported set is empty so stale evidence is not preserved. When that uploaded artifact list does not exist and the latest proof handoff is an honest no-op result because this cycle did not run `capture-visual-proof`, preserve any existing `## Screenshots` and `## Screencasts` sections from the previous `/tmp/pr-body.md` when they already contain valid artifact URLs or screencast embeds. When that uploaded artifact list does not exist and the latest proof handoff reports that browser proof is not applicable, that screenshots and screencasts are unnecessary, or that capture is blocked, explicitly remove any existing `## Screenshots` and `## Screencasts` sections instead of preserving stale proof from an earlier cycle. Only when that uploaded artifact list does not exist and screenshot `rawUrl` values are still available from the latest proof handoff should the screenshot-only fallback include `## Screenshots`, embedding each screenshot as `![]()` so the image renders inline in the PR body; do not create `## Visual proof` for screenshots and do not render screenshot artifact viewer links when `rawUrl` exists. When no previous `/tmp/pr-body.md` exists, there is no prior body to preserve, so include proof sections only when current-cycle proof links are available and include `## Linked work items` only when the current workflow instructions provide one. Derive a refreshed PR title per the `pr-writing-guide` section below. Before calling `mcp__roomote__manage_source_control`, validate the exact title and `/tmp/pr-body.md` against the PR writing guide. The title must begin with exactly one approved bracketed type tag. When a selected repo template exists, the body must preserve the template's reviewer-facing headings, checklist items, and required structure, replace placeholder guidance with final content, and cover the same reviewer substance the `pr-writing-guide` requires without forcing Roomote-only headings that the template does not use. When no repo template exists, the body must include `## What changed`, `## Why this change was made`, and `## Impact`. Do not add legacy top-level sections such as `## Summary`, `## Changes`, `## Validation`, `## Checks`, or `## Status` for routine successful runs unless the selected repo template explicitly requires them. Treat this as a hard gate: if the metadata fails, rewrite it and re-check before running the source-control mutation. Call `mcp__roomote__manage_source_control` with `action: "create_or_update_pull_request"`, `repositoryFullName: ""`, `sourceBranch: ""`, `targetBranch: ""`, `title: ""`, and `body` set to the exact `/tmp/pr-body.md` contents. Include `prAttribution` when the conversation establishes a clear participant, include `labels` only when a current conflict-resolver label is provided, and include `assignees` only when provider-compatible assignee usernames are available for this run. The tool creates a new pull request or refreshes the open one for the branch in a single call.</item> </pr-metadata-update-recipe> <validation>Every changed repository now has a corresponding created or refreshed pull request confirmed by a `mcp__roomote__manage_source_control` result, or a clearly reported blocker.</validation> </step> </steps> </phase> <phase name="validation"> <description>Verify that every repository is represented in the final result and report the created or updated pull requests clearly.</description> <steps> <step number="7"> <title>Report the created or updated pull requests Provide the user with a concise repository-by-repository summary of the created or updated pull requests. Report each created or updated pull request using the pull request title, repository name, whether it was created or refreshed, and the URL when available; if a URL cannot be recovered, report the pull request number and branch instead. State that each pull request is ready for normal review flow. The summary includes every repository processed and no successful pull request creation or update is omitted.

<completion_criteria> Every repository with changes or unpushed commits has been evaluated exactly once. The delivery branch is created from the provided base/default branch, and new pull requests target that same base branch. Each repository that required action has a pushed branch and a created or refreshed pull request. When the same task ships through multiple pull requests, each PR body links the sibling PRs with current URLs. When a single-PR refresh updates one PR from an already-split task, the refreshed PR body does not silently drop valid sibling PR links. The final response lists the resulting pull requests clearly and accurately. </completion_criteria>

<best_practices> Create or refresh a separate pull request for each changed repository rather than bundling unrelated repos together. Cross-repository work still needs per-repository review, CI, and merge tracking. None. When the same task is split across multiple pull requests, make each PR description mention the sibling PRs and keep those links current. Reviewers need to understand the full shipped surface and any coupled frontend/backend or multi-repository changes. Skip the section only when there is truly only one PR for the task or no sibling PR URL can be recovered honestly. Preserve commit and push validation hooks unless there is no safe alternative. Hook failures often indicate real formatting, linting, or typing problems that should be fixed before review. Only bypass as a last resort after diagnosing why the hook cannot be satisfied. Use descriptive branch names, conventional commit messages, and concise pull request copy. Reviewers need the branch, commit, and pull request metadata to explain intent quickly. Follow repository-specific naming conventions when they differ from the default pattern. Apply Net PR Changes Only: ground the pull request body in the final shipped diff, then add conversation context only when it matches what actually shipped. Reviewer-facing context becomes misleading when it repeats an earlier plan or conversation that the final code no longer reflects. If the change is an exact implementation of the user-stated request, use the conversation context directly. </best_practices>

Determine whether the workspace is a single repository or a multi-repository container before performing any git actions or source-control mutations. Use for any workflow that might operate across multiple repositories. Repeat the same metadata, commit, push, and creation steps for each changed repository. Use when the workspace may contain more than one repo that needs an output artifact.

<decision_guidance> Prefer the git operations that safely produce a reviewable pull request. Return early when there is no changed repository rather than creating empty pull requests. Preserve repository-specific context instead of assuming one repository's metadata applies to another. Use only script-safe git commands, pass user-controlled text through mcp__roomote__manage_source_control tool parameters instead of shell interpolation, and never skip reporting blockers. This workflow handles repository detection, commit creation, branch pushing, and pull request creation. This workflow does not decide product requirements or rewrite the requested code changes themselves. When branch protection, authentication, or remote permissions block progress, surface the exact blocker to the user and conclude with a blocked result. </decision_guidance>

A workspace contains two repositories with pending work that should each receive their own pull request. Create PRs for the current changes. Detect the workspace shape and enumerate the changed repositories. Run the workspace detection command and record both changed repositories. There is a concrete target list instead of an assumed single repository. Analyze each repository separately. Derive a branch name, commit message, pull request title, and pull request body for each repository. Each repository has a full metadata bundle ready for execution. Commit, push, and create or refresh the pull requests. Execute the git commands and `mcp__roomote__manage_source_control` calls repo by repo and capture each live pull request reference. Two distinct pull requests are created or updated and ready to report. The user receives a concise list of the created or updated pull requests, one for each repository. Multi-repository work still requires repository-specific pull request handling.

<error_handling> No repository has uncommitted or unpushed work. The workspace is already clean. All commits were already pushed and already have open pull requests. Report a no-op result and tell the user there is nothing to package into a pull request. A commit or push command fails. Pre-commit or pre-push checks failed. The branch conflicts with remote permissions or branch protection. Diagnose and fix the validation issue when possible; otherwise report the exact blocker instead of forcing completion. </error_handling>