diff --git a/plugins/copilot-dreaming/skills/open-pull-request/SKILL.md b/plugins/copilot-dreaming/skills/open-pull-request/SKILL.md new file mode 100644 index 0000000..2e4c364 --- /dev/null +++ b/plugins/copilot-dreaming/skills/open-pull-request/SKILL.md @@ -0,0 +1,120 @@ +--- +name: open-pull-request +description: "Open a single pull request for the current job branch by committing and pushing the changes already in the checkout and creating the PR with the built-in `report_progress` and `create_pull_request` tools. Use as the shared publication step for Dreaming tasks that produce file changes." +user-invocable: false +--- + +# Open Pull Request + +Publish file changes produced by a Dreaming task as exactly one reviewable pull +request, using the platform's built-in runtime tools. + +## Purpose + +Provide one reusable way to turn work in the repository checkout into a pull +request on the current job branch, without GitHub MCP, `gh`, or independently +authenticated scripts. + +## Conditions (C) + +Use this skill only when: + +- the task has produced file changes that should land as a reviewable PR; +- the run executes as a `task` action — `create_pull_request` is only available + then; +- the built-in `report_progress` and `create_pull_request` tools are enabled for + the run. + +Do not use this skill for tasks that only return a summary. + +## Required tools + +This skill relies on two built-in runtime tools, which must be enabled for the +run: + +- `report_progress` — commits and pushes the pending changes on the job branch. +- `create_pull_request` — opens a pull request for the current branch, setting + its title and body. Calling it again for a branch that already has a PR safely + returns that PR instead of failing or opening a duplicate; it does not + re-apply the title or body to an already-open PR. + +No `gh`, authenticated `curl`, or GitHub MCP write tools are used. + +## Interface (R) + +Inputs: + +- `title`: the pull request title. +- `summary`: the pull request body in markdown, with the context reviewers need. +- `draft` (optional): whether to open the pull request as a draft. + +Outputs: + +- exactly one open pull request for the current branch containing the task's + files; or +- an explicit no-op or blocked summary when there is nothing to publish or the + required tools are unavailable. + +## Steps + +### 1. Confirm the task's files are in the checkout + +Confirm the file(s) the calling task produced are present in the checkout — the +task writes them as it does its work; this skill does not author file content. If +there are no files to publish, do not open a pull request; report the run as a +no-op. + +### 2. Commit and push with `report_progress` + +`report_progress` commits everything pending in the checkout. Before calling it, +run `git status` and confirm the pending files are the ones you intend to +publish. If unrelated, generated, or scratch files are present, remove them from +the checkout (or keep them outside it) before publishing. + +Then call `report_progress` with: + +- `commitMessage`: a short, single-line commit message; +- `prDescription`: the `summary` input, so it matches the PR body opened in + step 3. + +This commits and pushes the changes to the job branch. + +### 3. Open the pull request with `create_pull_request` + +Call `create_pull_request` with `title`, `description` (the body from the +`summary` input), and `draft` when the work should open as a draft. This creates +the pull request for the current branch with that title and body. Each scheduled +run uses its own fresh branch, so this creates one new PR per run. If a PR +already exists for the branch, the call safely returns it without changing its +title or body. + +## Termination (T) + +Success requires: + +- the task's files are committed and pushed on the job branch; +- exactly one pull request is open for that branch. + +No-op or blocked outcomes are explicit: when there are no file changes to +publish, or the required tools are unavailable, do not open a pull request and +report the outcome. Never report a pull request that was not created. + +## Never do + +- Never author or modify the task's file content; the calling task owns that. +- Never commit files other than the task's files; verify the working tree with + `git status` before publishing. +- Never use `gh`, authenticated `curl`, or scripts that obtain GitHub + credentials. +- Never open more than one pull request per run for the same change. + +## Scope boundaries + +This skill owns turning committed checkout changes into a single pull request. +It creates a new pull request for the current branch; updating the title or body +of a pull request that already exists (for example, revising an earlier run's PR) +is out of scope. The calling task owns deciding what to publish and composing the +title and body. The Dreaming host owns branch provisioning, tool availability, +and authentication. + +**Abstraction level:** tactical