skills.rest
microsoft
microsoftOFFICIAL
Explore all skills by this author →
Website𝕏@OpenAtMicrosoftGitHub

shepherd-driver

Drives one selected pull request to mergeable state through review, fold, push, and CI-watch loops.

3.7k|344|Updated Sep 18, 2025
Search Tags:#Rebase#gitHub# orchestration#merge automation#ci recovery#Code review#Pull request
One-click install
npx skills add https://github.com/microsoft/apm --skill shepherd-driver
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: shepherd-driver
Source: https://github.com/microsoft/apm/tree/main/.agents/skills/shepherd-driver
Command: npx skills add https://github.com/microsoft/apm --skill shepherd-driver

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) and assets (resource) components.

What problem does it solve?

Pull requests in microsoft/apm stall after automated review because Copilot bot comments, panel follow-ups, lint failures, and CI flakes each require manual iteration. This Skill automates the per-PR convergence loop so a parent orchestrator can drive one PR to a terminal ready-to-merge, advisory-with-deferred, superseded, or blocked state without human babysitting.

Core Features & Use Cases

  • Per-PR convergence loop: Classifies copilot-pull-request-reviewer[bot] inline review, runs the apm-review-panel, folds in-scope follow-ups by default, pushes to the head branch or a superseding PR preserving authorship via commit trailers, and watches CI to green under fixed iteration caps.
  • Deterministic owner-touch gate: Runs scripts/owner_touch_gate.py to parse the canonical architecture owner table and require executed functional test evidence for every touched owner before a terminal return.
  • Cross-PR conflict resolution: Probes mergeability and rebases conflicting PRs with --force-with-lease, faithful conflict resolution, and a trust-but-verify re-probe.
  • Use Case: A batch orchestrator like batch-bug-shepherd selects five open PRs, spawns one shepherd-driver subagent per PR, and receives schema-validated completion returns it aggregates into a mergeability table.

Quick Start

Ask the parent orchestrator to spawn a shepherd-driver subagent for PR 1234 with the issue number, author, head repo, head branch, and repo root so it drives that PR to a mergeable terminal state.

Frequently Asked Questions about shepherd-driver

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I drive a GitHub pull request to mergeable automatically?▼

Spawn one shepherd-driver subagent per PR with PR number, issue number, author, head repo, head branch, and repo root. It classifies Copilot review, runs the review panel, folds in-scope follow-ups, pushes, and watches CI until a terminal status is reached.

What does the fold-vs-defer rubric decide for PR review follow-ups?▼

The rubric folds every follow-up inside the PR's stated scope into the current PR and defers only items that introduce a new theme or domain. Each deferred item must carry a one-line scope-boundary note explaining the crossing.

Can I use shepherd-driver as a standalone skill for triaging issues?▼

No. It is a composed building block, not a user-facing entrypoint. A parent orchestrator such as batch-bug-shepherd or apm-issue-autopilot must select the PR first; the driver never triages issues or opens greenfield PRs.

What happens when CI keeps failing after a push?▼

Failures are classified into lint, test, transient infra, or persistent-unknown buckets with specific recovery steps. After three CI fix iterations the loop stops and returns status blocked with the failing job and log excerpt.

How are cross-PR merge conflicts resolved after PRs are ready?▼

A mergeability gate probes each ready PR, then spawns one conflict-resolution subagent per conflicting PR to rebase onto main, resolve conflicts faithfully, push with --force-with-lease, and re-probe mergeStateStatus.

What are the iteration caps and terminal statuses of the loop?▼

Caps are 4 outer iterations, 2 Copilot classification rounds, and 3 CI recovery iterations. Terminal returns are ready-to-merge, advisory-with-deferred, superseded, or blocked, each schema-validated against completion-schema.json.

Related Skills

Explore More Software Engineering Skills→
steipetesteipete
388.4k

openclaw-repair-sweep

Orchestrate worker fleets to diagnose, refactor, and land verified OpenClaw issue and PR repairs.

Community
Advanced
mitchlabeetchmitchlabeetch

pr-verify

Analyze GitHub PR changes, CI status, and mergeability to verify merge readiness.

Community
Advanced
TobiasPerryTobiasPerry

review

Analyze branch diffs for SQL safety, LLM trust boundaries, and side effects.

Community
Advanced
BluMintIncBluMintInc
2

automated-review-addressing

Automate pull request review feedback by updating the PR head branch.

Official
Advanced