Skip to content

Commit 4901b67

Browse files
cliffhallclaude
andauthored
feat(skills): add the pr-flow skill (#4867)
Adapt the Inspector's pr-flow skill for this repo: read the issue and every comment, assign it and move the card to In Progress, branch v2/<type>/<N>-<slug> from origin/v2/main (stacking included), sign off every commit (DCO, with the rebase --signoff repair and why format.signOff does nothing), run the gate, record client evidence in place of screenshots, open the PR with Closes #N first and link it with addCloseIssueReferences, move the card to In Review, and run the Copilot review loop to one of its four documented exits (clean round, out-of-scope only, two silent rounds, timeout). Close-out on merge is by hand, with the card moved to Done. The DCO app is not installed yet, so the skill says so and AGENTS.md does not gain the signoff rule; that waits for the app to enforce it. Adds the skills-index row and the timeout exit to AGENTS.md, plus eight eval cases (six positive, two negative), all passing at RUNS=5. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Signed-off-by: cliffhall <[email protected]>
1 parent 9b734b9 commit 4901b67

3 files changed

Lines changed: 359 additions & 1 deletion

File tree

‎.claude/skills/pr-flow/SKILL.md‎

Lines changed: 321 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,321 @@
1+
---
2+
name: pr-flow
3+
description: "Take an issue through to a PR in this repo and close it out after merge. Use when asked to open, create or submit a PR; when naming a branch; when signing off commits or repairing a missing Signed-off-by; when recording client evidence for a PR; when requesting a Copilot review, answering its comments or deciding whether to run another round; or when closing out after a merge."
4+
disable-model-invocation: false
5+
---
6+
7+
# PR flow
8+
9+
The rules this procedure carries out live in [`AGENTS.md`](../../../AGENTS.md)
10+
(**Contributing**, **Issue-driven work style**, **Responding to code reviews**,
11+
**Waiting on long-running work**). Board mechanics, including every board ID,
12+
are in `/board-ops`; creating a missing issue is `/issue-create`. This file names
13+
board columns and nothing else.
14+
15+
**Pull requests against this repo are opened by the maintainers only.** Write
16+
access is not authorization to open one. Anyone else files a detailed issue
17+
(`/issue-create`) and a maintainer takes it from there.
18+
19+
## 1. Start from an issue
20+
21+
**Every PR closes an issue.** A PR with no linked issue has no board card, so
22+
the work is invisible to the board. If there is no issue yet, create one first
23+
with `/issue-create`; never open the PR and backfill.
24+
25+
**Read the issue in full, every comment included.** Scope changes, maintainer
26+
decisions and "not this, that" corrections are usually in the comments, not the
27+
body:
28+
29+
```sh
30+
gh issue view <N> --repo modelcontextprotocol/servers --comments
31+
```
32+
33+
Then assign it to yourself and move its card to **In Progress** (the
34+
move-a-card recipe in `/board-ops`):
35+
36+
```sh
37+
gh issue edit <N> --repo modelcontextprotocol/servers --add-assignee @me
38+
```
39+
40+
## 2. Branch
41+
42+
`v2/<type>/<N>-<slug>`, cut from **`origin/v2/main`**:
43+
44+
```sh
45+
git fetch origin v2/main
46+
git switch -c v2/fix/4810-filesystem-symlink-escape origin/v2/main
47+
```
48+
49+
`<type>` follows the issue's type label: `bug` → `fix`, `enhancement` → `feat`,
50+
`documentation` → `docs`, `chore` → `chore`. The `v2/` prefix matches the base
51+
branch and keeps the work legible in `git branch -a` next to `main`.
52+
53+
**Never cut from `main`.** It is the release line and does not carry `v2/main`'s
54+
history, so the PR diff would show unrelated changes.
55+
56+
**Stacking.** When one issue's work depends on another PR that has not merged
57+
yet, branch from that PR's branch and open the PR with `--base` set to it. Say
58+
in the body that it is stacked and on which PR. When the lower PR merges,
59+
retarget the stacked one to `v2/main` (`gh pr edit <PR> --base v2/main`) and
60+
rebase it if GitHub reports conflicts.
61+
62+
## 3. Sign off every commit (DCO)
63+
64+
This repo adopted the [Developer Certificate of
65+
Origin](https://developercertificate.org/) (maintainer decision on #4861).
66+
Commit with **`git commit -s`**, every time.
67+
68+
⚠️ **The [probot DCO app](https://probot.github.io/apps/dco/) is not installed on
69+
this repo yet**, so today nothing fails an unsigned commit. Installing it is an
70+
org-admin step (#4867). Sign off anyway: once the app is on, it checks
71+
every commit in a PR, so an unsigned commit pushed today becomes a red check
72+
that can only be cleared by rewriting history. Once the app enforces the check,
73+
`AGENTS.md` gains the signoff rule and this paragraph goes.
74+
75+
What the app checks: each commit carries a `Signed-off-by: Name <email>` trailer
76+
whose name **and** email match the commit's author or its committer. Merge
77+
commits and bot-authored commits are exempt. There is no partial credit: one
78+
unsigned commit out of six fails the whole check.
79+
80+
Two things that look like automation and are not:
81+
82+
- ⚠️ **`git config format.signOff true` does nothing here.** Despite the name,
83+
it only defaults the `-s` flag for `git format-patch`. `git commit` never reads
84+
it, and there is no `commit.signoff` equivalent.
85+
- ⚠️ **A `prepare-commit-msg` hook works, but think before installing one.** The
86+
trailer is a certification, and a hook makes it on your behalf for _every_
87+
commit, including work you merely cherry-picked. Inside that hook,
88+
`git var GIT_AUTHOR_IDENT` returns your config identity rather than the
89+
preserved author, so it cannot even tell it is signing for someone else.
90+
91+
**Repairing commits already pushed** means rewriting them:
92+
93+
```sh
94+
git rebase HEAD~<n> --signoff
95+
git push --force-with-lease
96+
```
97+
98+
Use `--force-with-lease` rather than `--force`, and rewrite only when you are the
99+
sole author and nobody has based work on the branch (a stacked PR above yours
100+
has). The two apparent alternatives are not alternatives: the app's empty
101+
"remediation commit" flow needs `allowRemediationCommits.individual`, and this
102+
repo ships no `.github/dco.yml`, so it is disabled; and the override button that
103+
anyone with write access sees only silences the check, with nobody certifying
104+
anything.
105+
106+
The signoff is a DCO assertion made in **your own name**. It does not claim you
107+
wrote the code, so signing off a cherry-pick is legitimate. Fabricating
108+
_someone else's_ certification never is.
109+
110+
## 4. Run the gate
111+
112+
Run what CI runs for everything the change touches, and fix what fails before
113+
pushing:
114+
115+
| Change touches | Command |
116+
| --- | --- |
117+
| Anything (always) | `npm run validate:guards` (CI's "Root guards" job: root format and lint, the coverage guards, `verify:skills`, the script tests) |
118+
| A TypeScript server | `npm run validate -w src/<server>` (format check, lint, typecheck, build, test) |
119+
| A Python server | `npm run validate:py -- <server>` (locked sync, ruff, ruff format, pyright, pytest, build) |
120+
| A skill's description, or a new skill | `npm run skills:eval` for the **whole** suite (spends model calls; not in CI). See `AGENTS.md` **Maintaining the skills** |
121+
122+
Verify by exit code, not by grepping the output. Formatting failures are fixed
123+
with `npm run format` (TypeScript) or `uv run ruff format .` (Python).
124+
125+
## 5. Client evidence
126+
127+
A PR shows the change working, as the PR template's **How Has This Been
128+
Tested?** section asks. Here that means evidence from clients, not screenshots.
129+
130+
**A change to server behavior** (a tool, resource, prompt, capability,
131+
transport or error it returns) records, for **both** the Inspector V2 and an
132+
LLM client, in **both** spec eras (a 2026-07-28 client and a 2025-11-25 client,
133+
per #4857):
134+
135+
- what the client was asked to do (the Inspector action, or the prompt given to
136+
the LLM client), and
137+
- what it returned (the result, trimmed to what shows the change).
138+
139+
A before/after pair is best when the change fixes a bug: the same request
140+
against `v2/main` and against the branch.
141+
142+
**A change with no client-observable surface** (docs, skills, workflows, gate
143+
tooling, CI) carries a **targeted probe** instead: the one thing that proves
144+
it. For example, the guard made to fire on a planted defect and then pass, the
145+
workflow run that exercised the new job, the query that reads back the state a
146+
skill's recipe produced, or the `skills:eval` scores for a skill.
147+
148+
Put the evidence in the PR body under **How Has This Been Tested?**.
149+
150+
## 6. Open the PR
151+
152+
Base **`v2/main`** (or the lower branch, when stacked). **Never `main`.** Label
153+
it `v2`. The body's **first line is `Closes #<N>`**.
154+
155+
```sh
156+
gh pr create --repo modelcontextprotocol/servers \
157+
--base v2/main --label v2 \
158+
--title "<title>" --body "Closes #<N>
159+
160+
<what changed and why, then the template's sections, with the evidence>"
161+
```
162+
163+
⚠️ Closing keywords only link and auto-close for PRs that target the default
164+
branch (`main`). Against `v2/main`, `Closes #N` is only a cross-reference.
165+
Keep the line anyway, and **link the PR to the issue explicitly** right after
166+
opening it:
167+
168+
```sh
169+
PR=<PR_NUMBER>; N=<ISSUE_NUMBER>
170+
PR_ID=$(gh pr view "$PR" --repo modelcontextprotocol/servers --json id --jq .id)
171+
ISSUE_ID=$(gh issue view "$N" --repo modelcontextprotocol/servers --json id --jq .id)
172+
gh api graphql -f query='
173+
mutation($issue:ID!,$pr:ID!) {
174+
addCloseIssueReferences(input:{issueId:$issue, pullRequestIds:[$pr]}) {
175+
issue { number }
176+
}
177+
}' -f issue="$ISSUE_ID" -f pr="$PR_ID"
178+
179+
# Read the link back: the issue number must be listed.
180+
gh pr view "$PR" --repo modelcontextprotocol/servers \
181+
--json closingIssuesReferences --jq '[.closingIssuesReferences[].number]'
182+
```
183+
184+
The link does **not** make the issue close on merge into `v2/main`; that is
185+
still done by hand in step 9.
186+
187+
Then move the card to **In Review** (`/board-ops`). The PR itself never goes on
188+
the board.
189+
190+
## 7. Request a Copilot review
191+
192+
Only the GraphQL `requestReviews` mutation with the Copilot **bot id** works.
193+
REST, `gh pr edit --add-reviewer`, `userIds` and `copilot-swe-agent` all fail or
194+
silently drop the request.
195+
196+
```sh
197+
PR_ID=$(gh pr view <PR> --repo modelcontextprotocol/servers --json id --jq .id)
198+
gh api graphql -f query='
199+
mutation($pr:ID!,$bot:[ID!]!) {
200+
requestReviews(input:{pullRequestId:$pr, botIds:$bot, union:true}) {
201+
pullRequest { id }
202+
}
203+
}' -f pr="$PR_ID" -f bot='BOT_kgDOCnlnWA'
204+
```
205+
206+
A round usually lands in about five minutes. Wait for it with **one backgrounded
207+
loop that exits when the round lands, or when its deadline passes**, and wait
208+
for its notification rather than re-fetching once per turn. A review is remote
209+
state the harness cannot observe, which is the exception in `AGENTS.md`
210+
**Waiting on long-running work**, and this loop is where that poll belongs.
211+
212+
```sh
213+
PR=<PR>
214+
EXPECTED=1 # the review COUNT to reach; see below
215+
DEADLINE=$(( $(date +%s) + 20*60 ))
216+
while :; do
217+
# Capture first, so a gh failure stops the loop instead of being swallowed by
218+
# a pipeline. --slurp cannot be combined with --jq, hence the separate jq.
219+
raw=$(gh api --paginate --slurp \
220+
repos/modelcontextprotocol/servers/pulls/$PR/reviews) || {
221+
echo "gh api failed ($?); not retrying blind" >&2; exit 1; }
222+
n=$(jq '[.[][] | select(.user.login | startswith("copilot-pull-request-reviewer"))] | length' <<<"$raw") || {
223+
echo "jq failed ($?) on an unexpected response shape" >&2; exit 1; }
224+
case $n in '' | *[!0-9]*) echo "not a count: '$n'" >&2; exit 1 ;; esac
225+
[ "$n" -ge "$EXPECTED" ] && { echo "round landed ($n reviews)"; break; }
226+
[ "$(date +%s)" -ge "$DEADLINE" ] && { echo "SILENT: no review by the deadline"; break; }
227+
sleep 30
228+
done
229+
```
230+
231+
`EXPECTED` is the review **count** to reach, so it is `1` only on the first
232+
round; on round two the first round's review is still there, and an existence
233+
check would return at once. Match the login with `startswith`: it carries a
234+
`[bot]` suffix. `sleep 30` is the remote-API floor `AGENTS.md` sets. **Every
235+
step that can fail exits the loop rather than retrying**: piping the count into
236+
`awk` would make an auth error read as `0`, and an empty count from a `jq`
237+
failure would make the comparison fail forever, so the job sleeps and retries
238+
without end. A background task that can never succeed is worse than none,
239+
because it looks like progress.
240+
241+
Once the body lands, give the inline comments about another 60 seconds: they
242+
arrive after it (step 8).
243+
244+
## 8. Respond to the review
245+
246+
Judge each finding against **the issue the PR closes**, as `AGENTS.md`
247+
**Responding to code reviews** says: fix defects in what the PR added; decline
248+
scope creep (pre-existing behavior, new capabilities, hardening the issue did
249+
not ask for) with a reason, and file an issue (`/issue-create`) for any that is
250+
worth doing on its own. Implementing a suggestion differently is fine.
251+
252+
- **Reply to each review comment in its own thread**, saying what was done (with
253+
the commit) or why it was declined. That reply is the primary response, and it
254+
is not optional: each comment is a thread with its own resolve state, and a
255+
reply _in_ it is the only thing a reader of that thread sees. Replying does
256+
not resolve the thread; resolving is the reviewer's act.
257+
258+
```sh
259+
# The round's comments, by REVIEW id. The unpaginated /reviews listing hides
260+
# later rounds behind your own replies, and this endpoint returns 30 per page:
261+
# a round you only half fetch is a round you only half answer.
262+
gh api --paginate repos/modelcontextprotocol/servers/pulls/<PR>/reviews/<REVIEW_ID>/comments \
263+
--jq '.[]|"\(.id) \(.path):\(.line)\n\(.body)\n"'
264+
265+
# Reply into one thread, keyed by the comment id from above.
266+
gh api repos/modelcontextprotocol/servers/pulls/<PR>/comments/<COMMENT_ID>/replies \
267+
-f body='Fixed in <sha>: …'
268+
```
269+
270+
- ⚠️ **Then post a PR-level summary of the round, in addition, never instead.**
271+
Inline replies go hidden once the fix is pushed, because the threads become
272+
outdated, so the summary is what keeps the round readable afterwards. It does
273+
not replace the per-thread replies: a summary bullet cannot be connected back
274+
to the thread it answers.
275+
276+
```sh
277+
gh pr comment <PR> --repo modelcontextprotocol/servers --body "Copilot round <k>: …"
278+
```
279+
280+
- ⚠️ **Read the "Suppressed comments" block in the review body.** Those findings
281+
have no comment id, so no thread to reply into. The PR-level summary is the
282+
only place to answer them.
283+
- ⚠️ **Inline comments lag the review body.** The body's "generated N comments"
284+
count lands first. Fetch by review id, and reconcile the count before
285+
answering.
286+
287+
Push the fixes (signed off, step 3) before requesting the next round.
288+
289+
## 9. Another round, or stop
290+
291+
Request another round (step 7, with `EXPECTED` one higher) **only when you
292+
pushed a fix** in response to the last one. The loop stops at the **first** of:
293+
294+
| Exit | When | Then |
295+
| --- | --- | --- |
296+
| **Clean round** | A review with no findings. No confirming round is needed | Stop |
297+
| **Out of scope only** | Every finding in the round was declined as outside the issue | Reply in each thread, stop. Nothing was pushed, so there is nothing new to review |
298+
| **Two silent rounds** | Two requests in a row end with no review: the poll's deadline passed, or Copilot's session ended without posting | Stop, and say so in the summary |
299+
| **Timeout** | The loop's overall budget is spent: about ten rounds, or the session is ending, while findings keep coming | Stop, and list what is still open in the summary so a human can pick it up |
300+
301+
A round that posted nothing new is still reported in the PR-level summary, so
302+
the PR shows why the loop ended.
303+
304+
## 10. Merge and close out
305+
306+
Merging is a maintainer's decision. Do not merge on your own initiative.
307+
308+
**On merge into `v2/main`, close the issue by hand and move its card to
309+
Done**, since auto-close does not fire there:
310+
311+
```sh
312+
gh issue close <N> --repo modelcontextprotocol/servers --reason completed
313+
```
314+
315+
Then Status → **Done** with the move-a-card recipe in `/board-ops`.
316+
317+
`Done` means the work **shipped**. If the PR is closed without merging and the
318+
issue will not be done, the issue shipped nothing: close it as not planned and
319+
**delete its card** (`/board-ops`) rather than moving it to Done.
320+
321+
If PRs were stacked on this one, retarget each to `v2/main` (step 2).
Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
[
2+
{
3+
"prompt": "I've finished the fix for issue 4810. Take it through to a pull request.",
4+
"expect": "pr-flow"
5+
},
6+
{
7+
"prompt": "gh pr edit --add-reviewer copilot didn't request anything on my PR. How do I get Copilot to review it in this repo?",
8+
"expect": "pr-flow"
9+
},
10+
{
11+
"prompt": "I forgot to sign off the last three commits on a branch I already pushed. How do I fix them?",
12+
"expect": "pr-flow"
13+
},
14+
{
15+
"prompt": "What evidence should my PR body show for a change to the memory server's search_nodes tool? There's no UI to screenshot.",
16+
"expect": "pr-flow"
17+
},
18+
{
19+
"prompt": "Copilot left eight comments on my PR, two of them in a Suppressed comments block. How do I answer them so nothing gets lost?",
20+
"expect": "pr-flow"
21+
},
22+
{
23+
"prompt": "My PR into v2/main just merged. What do I still need to do to close it out?",
24+
"expect": "pr-flow"
25+
},
26+
{
27+
"prompt": "What does this regex match? /^[a-z]+$/",
28+
"expect": null
29+
},
30+
{
31+
"prompt": "Translate 'good morning' into Spanish.",
32+
"expect": null
33+
}
34+
]

‎AGENTS.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ not in advance.
2323
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
2424
| [`board-ops`](.claude/skills/board-ops/SKILL.md) | `gh project` recipes and the IDs for the Servers V2 board (#43); resolving option IDs by name; the option-deletion hazard and its recovery | Model-invoked, or `/board-ops` |
2525
| [`issue-create`](.claude/skills/issue-create/SKILL.md) | The create flow: duplicate check, `v2` + type + server-scope labels, milestone, board card, Status + Priority, and the query that verifies them | Model-invoked, or `/issue-create` |
26+
| [`pr-flow`](.claude/skills/pr-flow/SKILL.md) | Issue to PR: branch, DCO signoff and repair, the gate, client evidence, `addCloseIssueReferences`, the Copilot loop and its exits, close-out on merge | Model-invoked, or `/pr-flow` |
2627

2728
A PR that adds a skill under `.claude/skills/<name>/SKILL.md` adds its row to
2829
this table in the same change, and the table never lists a skill that does not
@@ -276,7 +277,9 @@ here.
276277
Request a review, wait for the round to post or for Copilot's session to end
277278
without one, answer every comment, and request again only when you pushed a
278279
fix. Stop on the **first** clean round (no confirming round), a round holding
279-
only out-of-scope findings, or two rounds in a row that end without a review.
280+
only out-of-scope findings, two rounds in a row that end without a review, or
281+
a timeout (the loop's budget is spent while findings keep coming). The recipe
282+
is the `pr-flow` skill.
280283
- **If new tasks are discovered during development, create issues** for them
281284
and put them on the board, rather than widening the current PR.
282285

0 commit comments

Comments
 (0)