PR Shepherd v1
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 35/100
- Issue type
- Feature
- Clarity
- Clearly specified
- Activity status
- Quiet
- Tech stack
- github, typescript
- Domain
- ai-infra-agents, backend, tooling
Research direction
Start by reading the PR Shepherd design, AGENTS.md, and the existing agent/runtime patterns. Implement the mentioned packages/agents entities, prompts, skill, event schemas, registry, and setup guide, then remove the two named Electric workflows. Done means the six workers and Shepherd handle the listed webhook and inbox flows, aggregate incremental findings, and pass the relevant tests or local checks.
Written by the indexing model from the issue text.
Description
PR Shepherd v1 — Design
Status: draft
Authors: Valter (with Claude)
Parent RFC: electric-sql/electric#4411 (Electric Factory)
Last updated: 2026-05-26
Summary
PR Shepherd is the first Electric Factory role and the first agent in the v1 cohort beyond Horton. It is a default reviewer on team PRs in electric-sql/electric: one persistent entity per open PR, woken by GitHub webhook events routed through the existing github-repo-electricsql-electric ingress in Electric Cloud. On each wake, Shepherd loads the reviewing-pull-requests skill, fans out one Electric Agents worker per review aspect (correctness, conventions, security, perf, tests, architecture), aggregates findings, and posts an incremental review comment under the ## PR Shepherd Review marker. Shepherd never merges and never pushes commits in v1. Replaces the existing claude.yml and claude-code-review.yml workflows.
Motivation
Per parent RFC #4411, PR Shepherd is one of the three v1 Factory roles (with Ops Agent and Daily Digest). The team wants:
- A default reviewer that catches concerns reliably and incrementally across pushes.
- A reusable agent shape (persistent-per-target) that other roles inherit.
- A concrete consumer of the webhook event-source primitives merged in
electric-sql/electric#4407and the webhook ingress merged instratovolt#1548. - A path off the existing Claude Code review GitHub Action onto Electric Agents.
Scope
This sub-issue covers a full PR Shepherd v1 implementation matching the RFC's role section, plus prerequisites:
- A
hortonGitHub App, manually created at theelectric-sqlorg level and installed onelectric-sql/electric. - Reuse of the existing
github-repo-electricsql-electricwebhook ingress in Electric Cloud — no changes to stratovolt code. - A new
packages/agentspackage in OpenFactory housing thepr-shepherdandpr-review-workerentities and the orchestration skill. - Removal of
claude.ymlandclaude-code-review.ymlfromelectric-sql/electric/.github/workflows/in the same PR that lands Shepherd.
Non-goals
- Other Factory roles (Ops Agent, Daily, Releaser, Issue Reproducer, Issue Groomer, Dependency Steward, Issue Enricher).
- Cross-repo support — only
electric-sql/electricin v1. - Auto-merge or auto-approve. Never, per RFC trust boundary.
- Real implementations of the
fix-ciandaddress-reviewlabel-gated write actions. Shepherd recognizes the labels in v1; the actual fix/address logic is a follow-up sub-issue. - Codebase vector index for Horton (separate Horton extension).
- Production deploy of OpenFactory entities. Running locally during v1 is acceptable; remote deploy is a follow-up.
Repo layout
OpenFactory/
packages/
agents/ ← NEW
src/
agents/
pr-shepherd.ts ← Persistent-per-PR orchestrator
pr-review-worker.ts ← Ephemeral per-aspect worker
prompts/
pr-review/
correctness.md ← pr-review.md §2.1
conventions.md ← pr-review.md §2.2
security.md ← pr-review.md §2.3
perf.md ← pr-review.md §2.4
tests.md ← pr-review.md §2.5
architecture.md ← pr-review.md §2.6 + §2.7
github-events.ts ← Bucket constants + GH event schemas
index.ts ← Entity registry export
skills/
reviewing-pull-requests.md ← Orchestration skill loaded by Shepherd
package.json ← Depends on @electric-ax/agents-runtime
discord-bot/ ← Untouched
docs/
setup-gh-app.md ← One-time GH App setup guide
AGENTS.md ← Onboarding doc
Convention introduced here and propagated to future Factory roles:
skills/*.md— runtime-loaded LLM playbooks (loaded viause_skill).src/prompts/<agent>/*.md— static prompt content bundled with agent code, passed to LLM calls by the handler.
Existing infrastructure (no changes required)
- Webhook ingress at
proj-eager-tahr-dynnheosru/env-inner-swallow-2x32fv3mfv/svc-old-ermine-krt5oggnwi. Source keygithub-repo-electricsql-electric. Catalog buckets already configured:issues→issues/:number(matchx-github-event in {issues, issue_comment})pull_requests→prs/:number(matchx-github-event in {pull_request, pull_request_review, pull_request_review_comment, issue_comment})pull_request_opened→prs/opened(matchpull_request && body.action == "opened")
- Stream-to-wake bridge in cloud-agents-server (stratovolt#1548) — already routes webhook deliveries into entity wakes.
- Runtime helpers in
@electric-ax/agents-runtime(electric#4407):webhook(endpointKey, { bucket }),list_event_sources,subscribe_event_source,list_event_source_subscriptions,unsubscribe_event_source.
Entities
pr-shepherd — persistent-per-PR orchestrator
- Entity URL:
/pr-shepherd/{repo}/{prNumber}— one entity per open PR. - Spawn trigger: an ephemeral dispatcher entity observing
webhook(..., { bucket: "prs/opened" }). Onpull_request.opened, the dispatcher resolves the Shepherd URL for that PR and sends it aninboxwake (creating the entity if it doesn't exist). - Per-PR observation: once spawned, Shepherd observes
webhook(..., { bucket: \prs/${prNumber}` })` so every subsequent event for that PR (synchronize, label, comment, review) wakes the same entity. - Death: PR
closedevent (merged or not) — finishes any in-flight aggregation, then exits.
State collections:
reviews—{ sha, commentId, postedAt, summary }. One row per posted review; drives the incremental-review marker.findings—{ wakeId, aspect, finding[] }. Rows written by workers, read by Shepherd to aggregate.meta— single row:{ repo, prNumber, isTeamPr, labels, status: 'active' | 'paused' }.
Gating logic (per RFC trust boundary):
- On first wake: classify PR as team vs community using
gh api orgs/electric-sql/members/{login}. Team → default-on. Community → only act ifshepherdlabel present. - On every wake: re-check
pause-shepherdandno-shepherdlabels inmeta. Paused → no-op.no-shepherd→ permanent exit. - Write actions (
fix-ci,address-review) only fire on label-add events whose label matches and where the entity isactive. v1 stubs only — see Non-goals.
Per-wake action:
opened→ load skill → spawn the six per-aspect workers (one-time, persistent for the PR's lifetime) → send each areviewmessage withbase..head→ wait → aggregate → post → record marker.synchronize→ load skill → send the existing workers areviewmessage withlastMarkerSha..head. Skip the message for aspects whose files weren't touched in the new range. Wait → aggregate → post → record marker.pull_request_review/issue_commentfrom a human → only act if the comment@mentionshortonorpr-shepherd; otherwise update state and idle.labeled/unlabeled→ updatemeta, react if action label.closed(merged or not) → send each worker ashutdownmessage, then exit.
pr-review-worker — persistent-per-(PR, aspect) worker
- Entity URL:
/pr-review-worker/{repo}/{prNumber}/{aspect}— one entity per PR per aspect; six per PR. - Spawn trigger: Shepherd's first wake on a PR. Shepherd spawns the full set of workers and sends each its initial
reviewmessage. - Spawn args:
{ repo, prNumber, aspect, parentUrl }. No diff range — that comes per wake in the inbox message. - Wake source: inbox messages from Shepherd. Workers do not observe webhook buckets directly; all wake fan-out is mediated by Shepherd so aggregation timing stays in one place.
- State collections:
findings_history—{ wakeId, baseSha, headSha, postedAt, findings: Finding[] }. One row per Shepherd-requested review pass. Lets the worker reference prior pushes when iterating ("flagged this in pass 1, author has not addressed").meta— single row:{ repo, prNumber, aspect, promptPath, status: 'active' | 'shutdown' }.
- Inbox message types:
{ type: 'review', wakeId, baseSha, headSha }— perform a review pass on the given range. Worker reads its priorfindings_history, fetches the diff via GH App Octokit, makes one LLM call with the aspect prompt + diff + prior-findings context, parses output, appends a newfindings_historyrow, thenctx.send(parentUrl, { type: 'worker-done', wakeId, aspect, findings }).{ type: 'shutdown' }— setstatustoshutdownand exit. Sent by Shepherd when the PR closes.
- Finding shape:
type Finding = { severity: 'critical' | 'important' | 'suggestion' file: string line?: number message: string suggestedFix?: string } - Death: on receipt of
shutdownfrom Shepherd. Worker lifetime equals PR lifetime. - No GitHub writes. Read-only. Only Shepherd ever posts comments.
The orchestration skill
packages/agents/skills/reviewing-pull-requests.md — loaded by Shepherd on every wake via use_skill.
Adapted from electric-sql/stratovolt/.claude/commands/pr-review.md. The original prompt's structure (phases, severity definitions, output format, principles, example issue format) is preserved verbatim where possible. The single change is Phase 2: the skill no longer instructs the LLM to analyze all aspects itself — it instructs the LLM to message persistent per-aspect workers and aggregate their results.
Phases:
- Phase 1 — Gather Context. Same as
pr-review.md. Sources:gh pr view,gh pr diff,gh apifor prior Shepherd comments by marker. PRD/RFC references extracted by Phase 1 (rather than a workflow pre-step). - Phase 2 — Fan out. On the first wake (PR opened), spawn the six per-aspect workers. On every wake (opened or synchronize), send each relevant worker a
reviewmessage with the current diff range (skip the message for aspects whose files weren't touched). Wait via observation on thefindingscollection with a 5-minute wall-clock timeout. - Phase 3 — Iteration Awareness. Unchanged. Marker
<!-- pr-shepherd:reviewed-sha=<sha> -->instead of the file-basedprevious_reviews.txt. - Phase 4 — Compose Review. Same template as
pr-review.mdPhase 4. Header swapped to## PR Shepherd Review. Sections per aspect, sorted by severity. - Phase 5 — Post. Same
gh apifind-existing-comment +gh pr comment/PATCHlogic.
Severity, principles, example format — copied verbatim from pr-review.md.
GitHub identity (horton App)
Manually created at the electric-sql org. Documented in docs/setup-gh-app.md. Not automated.
- App name:
horton. Reused across all Factory roles. - Webhook URL: the existing
github-repo-electricsql-electricingress URL. The path secret is the App's webhook secret. - Permissions — read: Contents, Issues, Pull requests, Checks, Metadata, Members.
- Permissions — write: Pull requests (comments + reviews), Issues (comments).
- Subscribed events:
pull_request,pull_request_review,pull_request_review_comment,issue_comment,issues,label. - Install on:
electric-sql/electriconly. - Credentials:
GH_APP_ID,GH_APP_PRIVATE_KEY,GH_APP_INSTALLATION_ID. Surfaced via env vars. 1Password for the team,.env.localfor development. - Octokit construction:
@octokit/auth-appinline inpr-shepherd.tsandpr-review-worker.ts. No shared helper module in v1.
Sub-issue text (filed under electric-sql/electric, child of #4411)
Title: PR Shepherd v1
Body:
Implements the PR Shepherd role from #4411.
Scope: see design doc at
OpenFactory/docs/superpowers/specs/2026-05-26-pr-shepherd-v1-design.md. One persistent entity per open PR; six per-aspect workers; review posted under the## PR Shepherd Reviewmarker; default-on for team PRs, opt-in (shepherdlabel) for community PRs.Non-goals: auto-merge, multi-repo, real
fix-ci/address-reviewimplementations (v1 stubs only), production deploy of OpenFactory.Dependencies:
hortonGitHub App created at electric-sql org and installed onelectric-sql/electric(manual).GH_APP_*credentials provisioned to the runtime.Exit criteria:
- Shepherd posts a review on a real PR in
electric-sql/electric.claude.ymlandclaude-code-review.ymlremoved from.github/workflows/in the same PR.- Design doc merged in OpenFactory.
Replacing existing Claude integrations
claude-code-review.ymlandclaude.ymlremoved in the same PR that lands Shepherd, per RFC §"Codebase impact".- Old
## Claude Code Reviewmarkers on closed PRs are left alone. On open PRs that already have a Claude comment, Shepherd posts a new## PR Shepherd Reviewcomment alongside without touching the old one.
Open questions
- Concrete relevance heuristics for the per-aspect "skip if no relevant files" rule. v1 starts conservative — never skip. Tune after first week of soak.
- The 5-minute aggregation timeout is a guess. Revisit after the first dozen real PRs.
- Whether
pr-review-workershould be one entity type with anaspectdiscriminator, or one entity type per aspect. v1 uses a single type with discriminator — simpler registry, no measurable downside.
Revision history
| Version | Date | Author | Changes |
|---|---|---|---|
| 0.1 | 2026-05-26 | Valter | Initial draft |
- Dominant language
- TypeScript
- Stars
- 10.4k
- Forks
- 399
- PR merge metrics
- No merged PRs in 30d
Getting set up
- No Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from electric-sql/electric
-
camelToSnake and snakeCamelMapper() drop the underscore when a digit precedes a camelCase boundaryOpen
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
electric-sql/electric#4855 ·
-
ShapeStream does not notify subscribers when it gives up on a non-Error valuePossibly taken @Tyagiquamar claimed this 19 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
electric-sql/electric#4830 ·
-
@electric-sql/client throws SecurityError on import when the browser blocks site storage (typeof localStorage outside try)Possibly taken @mohanedmoh claimed this 37 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
electric-sql/electric#4826 · 1 comment ·
-
agents-chat-starter: spawn PUT goes to the durable-streams proxy, so no entity is created and agents never wakePossibly taken @adityavkk claimed this 133 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
electric-sql/electric#4687 ·
-
Listen IP addressOpenfeature request triage
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
electric-sql/electric#4150 · 1 comment ·
All issues in electric-sql/electric
Similar issues
-
area:cli area:security bug priority:medium
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
Maintainers usually reply within 1 day
-
"code source" and "numerique.gouv" links: "new window" mention duplicated in the accessible nameOpenaccessibility
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
numerique-gouv/lasuite-landingpage#315 ·
Maintainers usually reply within 1 day
-
needs:triage
Difficulty 1/5 Under an hour Newbie friendliness 92/100
Maintainers usually reply within 1 day
-
Difficulty 1/5 Under an hour Newbie friendliness 72/100
HyeokjaeChoi/vaultme#585 ·
Maintainers usually reply within 1 day
-
enhancement priority/P2
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
beettlle/pi-smart-router#200 ·