PR Shepherd v1
还没有人认领这个 Issue。
评估
- 难度
- 5/5
- 预计耗时
- 一周以上
- 新手友好度
- 35/100
- Issue 类型
- 功能
- 描述清晰度
- 描述清楚
- 活跃度
- 冷清
- 技术栈
- github, typescript
调研方向
首先阅读 PR Shepherd 设计、AGENTS.md 以及现有的 agent/runtime 模式。实现提到的 packages/agents 实体、prompts、skill、事件 schema、registry 和 setup guide,然后移除提到名称的两个 Electric workflows。完成的标准是六个 workers 和 Shepherd 能够处理列出的 webhook 和 inbox flows,聚合增量 findings,并通过相关 tests 或 local checks。
由索引模型根据 Issue 内容生成。
描述
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 |
- 主要语言
- TypeScript
- 星标
- 10.4k
- 派生
- 399
- PR 合并指标
- 30 天内没有已合并 PR
环境准备
- 没有 Dockerfile 或 Docker Compose 文件
- 没有 Pull Request 模板
- 阅读贡献指南
从这里开始
- 先读完整个 Issue,再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库,在一个分支上完成修改。
- 提交 Pull Request,并在描述里引用这个 Issue 编号。
electric-sql/electric 的其他 Issue
-
camelToSnake and snakeCamelMapper() drop the underscore when a digit precedes a camelCase boundary未关闭
难度 2/5 1-3 小时 新手友好度 85/100
electric-sql/electric#4855 ·
-
ShapeStream does not notify subscribers when it gives up on a non-Error value可能已有人在做 @Tyagiquamar 于 19 天前认领。 未关闭
难度 2/5 1-3 小时 新手友好度 72/100
electric-sql/electric#4830 ·
-
@electric-sql/client throws SecurityError on import when the browser blocks site storage (typeof localStorage outside try)可能已有人在做 @mohanedmoh 于 37 天前认领。 未关闭
难度 2/5 1-3 小时 新手友好度 72/100
electric-sql/electric#4826 · 1 条评论 ·
-
agents-chat-starter: spawn PUT goes to the durable-streams proxy, so no entity is created and agents never wake可能已有人在做 @adityavkk 于 133 天前认领。 未关闭
难度 2/5 1-3 小时 新手友好度 78/100
electric-sql/electric#4687 ·
-
feature request triage
难度 2/5 1-3 小时 新手友好度 68/100
electric-sql/electric#4150 · 1 条评论 ·
查看 electric-sql/electric 的全部 Issue
相似的 Issue
-
难度 2/5 1-3 小时 新手友好度 82/100
SocialGouv/egapro#5212 ·
维护者通常 2 天内回复
-
area:filesystem bug need-triage
难度 2/5 1-3 小时 新手友好度 85/100
维护者通常 1 天内回复
-
Captions panel does not offer to show an existing transcript可能已有人在做 @thedavidweng 今天认领。 未关闭
难度 2/5 1-3 小时 新手友好度 72/100
CapSoftware/Cap#4276 · 1 条评论 ·
维护者通常 1 天内回复
-
bug from-app needs-triage
难度 2/5 1-3 小时 新手友好度 65/100
nightly-labs/openbot#10242 ·
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 67/100
维护者通常 1 天内回复