| name | shepherd-driver |
| description | Use only as the composed drive-to-merge stage of an APM batch orchestrator (batch-bug-shepherd, apm-issue-autopilot) that has already selected ONE open pull request in microsoft/apm. Do NOT use for user-facing requests to triage issues, sweep a queue, or open PRs -- the parent orchestrator owns those. Spawn one shepherd-driver subagent per PR: it classifies copilot-pull-request-reviewer[bot] inline review, runs the apm-review-panel, folds (by default) every recommendation inside the PR's stated scope, pushes to the head branch or a superseding PR that preserves authorship via commit trailers, watches CI to green, and iterates under fixed caps until ready-to-merge, advisory-with-deferred, superseded, or blocked. Also provides the cross-PR conflict-resolution and mergeability-gate phase. This is NOT a standalone entrypoint. |
shepherd-driver - per-PR drive-to-merge convergence loop
This SKILL.md is the natural-language module derived from a genesis
design packet; refactors re-run the genesis skill from that packet.
This skill is a COMPOSED BUILDING BLOCK, not a user-facing entrypoint.
It was extracted (genesis R3 EXTRACT) from batch-bug-shepherd when a
second consumer (apm-issue-autopilot) needed the same per-PR
convergence loop. Both orchestrators COMPOSE this skill; neither
re-implements the loop. It in turn COMPOSES the
apm-review-panel skill for the review
pass -- it does NOT re-implement panel review.
Boundary (what this skill does and does NOT do)
DOES: take ONE PR that already exists and drive it to a terminal
landing-ready state; resolve cross-PR merge conflicts; emit the
PR-facing advisory and supersede comments; return a schema-valid
completion_return.
Does NOT: triage issues, decide which issues are worth fixing, open
the first PR for an issue, choose the batch, or maintain the
orchestrator's ground-truth table. Those are the parent
orchestrator's responsibility. If you find yourself triaging or
opening greenfield PRs, you are in the wrong skill.
How an orchestrator composes this skill
The parent orchestrator, for each PR in its batch, spawns ONE
shepherd-driver subagent with the spawn body in
assets/shepherd-driver-prompt.md.
The orchestrator passes the inputs that prompt declares (PR_NUMBER,
ISSUE_NUMBER, AUTHOR, HEAD_REPO, HEAD_BRANCH, MAINTAINER_CAN_MODIFY,
REPO_ROOT, ORIGIN, optional PANEL_PRIOR). The subagent owns the whole
convergence loop end-to-end and returns a completion_return.
After every shepherded PR returns ready-to-merge, the orchestrator
runs the conflict-resolution phase: probe mergeability and, on
DIRTY / BEHIND / CONFLICTING, spawn one conflict-resolution subagent
per assets/conflict-resolution-prompt.md.
The step-by-step gate procedure is in
references/mergeability-gate.md
(load it when entering that phase).
Dependency declaration (read before composing)
This skill is a same-repo LOCAL SIBLING. A consuming orchestrator
MUST declare the dependency at its own distribution surface and PROBE
for this skill before spawning. The probe is a tool call, not an
assertion from recall (A9 SUPERVISED EXECUTION; truth #2 CONTEXT
EXPLICIT):
test -f ../shepherd-driver/assets/shepherd-driver-prompt.md \
&& test -f ../shepherd-driver/assets/completion-schema.json \
&& echo "shepherd-driver present" \
|| echo "MISSING shepherd-driver - stop and ask the operator"
On a probe MISS the orchestrator stops and asks the operator rather
than re-implementing the loop inline (avoids HAND-ROLLED
HALLUCINATION and PHANTOM DEPENDENCY).
This skill itself COMPOSES apm-review-panel.
A consuming orchestrator inherits that transitive dependency; the
spawned shepherd-driver subagent PROBES for it at preflight (all
load-bearing panel assets under
$REPO_ROOT/.agents/skills/apm-review-panel/) and returns
status: blocked ONLY on a genuine asset MISS, before any checkout
(see the spawn body Step 0.0). Note: a missing skill TOOL is NOT a
miss -- in the normal subagent context the panel is executed INLINE
from its on-disk SKILL.md + schemas (Step X.1.1), which is a
first-class path, not a fallback.
Convergence loop contract (per PR)
The shepherd-driver subagent runs this loop (full detail in the spawn
body):
- Phase X.0 -- fetch + classify
copilot-pull-request-reviewer[bot]
inline review per
assets/copilot-classification-prompt.md.
- Phase X.1 -- run the
apm-review-panel against the PR: via the
skill tool if present, otherwise (the normal subagent case)
execute it INLINE from its on-disk SKILL.md + schemas. Both paths
produce the same single recommendation comment.
- Phase X.2 -- merge follow-ups (LEGIT Copilot + panel
recommended_followups) and apply the fold-vs-defer rubric per
assets/fold-vs-defer-rubric.md.
- Phase X.3 -- edit code; fold every FOLD item. Run the mutation-
break gate on any new regression-trap test.
- Phase X.4 -- run the lint contract until silent.
- Phase X.5 -- push (head branch; fall back to a superseding PR that
preserves authorship via commit trailers).
- Phase X.6 -- CI watch + recovery per
assets/ci-recovery-checklist.md.
- Phase X.7 -- decide terminal vs next iteration.
- Phase X.8 -- at terminal, capture
head_sha, mergeable,
mergeStateStatus, and CI status for the completion return.
Caps (hard limits)
- Outer convergence iterations: 4.
- Copilot classification rounds: 2.
- CI recovery iterations: 3.
When a cap is hit with foldable items still open, return
advisory-with-deferred with a scope-boundary note per deferred
item. Caps exist to bound non-determinism; they are not targets.
Terminal returns
The subagent returns exactly one schema-valid completion_return
matching assets/completion-schema.json:
ready-to-merge -- clean convergence; CI observed green; lint
silent.advisory-with-deferred -- iteration cap hit with foldable items
remaining (rare); each deferred item carries a scope-boundary note.superseded -- push fell back to a superseding PR (records
superseded_by).blocked -- CI cap hit, panel assets genuinely absent (Step 0.0
probe miss -- NOT merely the skill tool being unavailable), or
unresolvable scope conflict (records a one-paragraph blocker).
The orchestrator schema-validates every return. On malformed, re-spawn
ONCE; on a second malformed return, mark the row blocked and continue.
Disciplines enforced (inherited by every consumer)
- Fold-by-default: every follow-up inside the PR's stated scope is
folded into THIS PR; only scope-crossing items are deferred, each
with a one-line boundary note.
- Mutation-break gate: every regression-trap test added is proven by
deleting the guard it protects and confirming the test fails
without it, then restoring the guard.
- Lint contract: the canonical ruff pair
(
uv run --extra dev ruff check src/ tests/ and
ruff format --check src/ tests/) must be silent before any push.
- CI-observed-green: terminal
ready-to-merge requires real CI
evidence, not an assumption.
- One advisory comment per PR per terminal pass, rendered from
assets/pr-comment-templates.md.
- Authorship preservation: superseding PRs credit the original author
via commit trailers and link back.
Consequential writes cross a deterministic tool bridge
Every side effect (push, comment, PR open/close, label, CI read,
mergeability probe) goes through a deterministic CLI (gh, git,
uv run ruff) wrapped in plan + execute + verify (A9 SUPERVISED
EXECUTION). Present-state facts (CI status, mergeable, head sha) are
READ from gh/git at terminal, never asserted from recall.
Bundled assets
