Draft
Conversation
Reactive blackboard architecture for shepherding GitHub PRs through gates (template, CI, conflicts, threads, docs) using independent observer agents that wake on signals. Phase 1 polls; phase 2 will swap in webhooks without changing the observer contracts. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Replace the dedicated pr-observer entity with the existing generic worker entity. Each role becomes a skill under skills/pr/ that the worker loads via use_skill on spawn. pr-manager owns the only persistent subscription to the signals collection and dispatches a fresh worker per signal+role pair, with iteration counters persisted in agent_state so caps work across spawns. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Consolidate seven roles into three long-lived worker entities (pr-reviewer, pr-build-doctor, pr-doc-editor) plus pr-manager that absorbs the four mechanical roles (sync, description, gates, lifecycle). All five entities are hybrid: small TS shell wires subscriptions/tools/prelude, agent reasoning lives in a markdown skill at packages/agents/skills/pr/<role>.md. Each entity has its own persistent timeline so it can reason about prior work on the PR. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Drop historical references to prior design drafts. - Add per-watcher state schema (managed_prs ledger). - Clarify reviewer skill decision tree to handle new_human_comment and continue_granted signals correctly (review pass and address pass decided independently). - Document signal payload shapes (head_sha_changed, ci_failed, new_human_comment, commits_pushed, human_input_required, continue_granted). - Fix role-naming convention: entity = pr-<role>, role name in state/payloads/slash-commands = short form. - Detect human-authored pushes by checking head_sha against the agent-authored commits table. - Consistency: 'observers' -> 'workers'; 'emit/write a signal' -> 'insert' where appropriate. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- §15 Templates defines the six concrete artifacts agents produce or consume: gate computation rules, PR description template (default + repo override path), review-thread comment, status comment, commit message, thread reply, slash-command grammar. - Spell out what ready_to_merge does: apply 'agents:ready' label, update status comment. No auto-merge, no LGTM, no draft removal. - Add 2s wake debounce to the manager so chatty PRs don't burn through one agent run per signal. - Add mergeable + status_comment_id to pr_meta schema since they're now referenced. - Drop the now-defined items from §14 Items deferred. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The primary goal is exercising the Electric Agents framework on a real workload to find platform bugs, not building a fully autonomous PR-shipping system. Spell out the deliberate limits up front: no coding agent, one repo per watcher, no webhooks, no automerge. Also drop redundant non-goals now covered by §1's limits. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The "no coding agent / one repo / no webhooks / no automerge" items are scope decisions, not goals. Consolidate them into §2 with the rest of the non-goals so the goal section stays focused on intent. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Existing fixtures (runtime-dsl tests, process-wake tests) all set 'type'
on every SharedStateCollectionSchema entry. The plan omitted it, which
typechecks today only because no consumer wires the schema yet — the
moment Tasks 13-18 do db('pr-...', schema), strict structural matching
against SharedStateCollectionSchema would fail.
Set distinct event-type strings (pr:meta, pr:check, pr:signal, etc.) so
collectionNameByEventType in entity-stream-db.ts can route change events
deterministically, instead of relying on the state:${name} fallback.
pr_synced has Record<string, never> per spec §3.3 so {foo:1} no longer
type-checks. Switch to head_sha_changed which has a typed payload to
exercise the same generic-payload-passthrough behavior.
…to-discovers them
SkillsRegistry.scanDir is non-recursive — skills under skills/pr/ would
not have been loaded into the catalog, so use_skill('pr-reviewer') would
return null. Move the four worker skills to skills/pr-<role>.md (flat).
Templates stay at skills/pr/templates/ since they're not registered
skills, just data files the skills reference.
execFile's promisified return is { stdout: string | NonSharedBuffer }
when no encoding is specified. GhRunner expects string. Coerce explicitly.
Register all 5 PR shepherd entities (pr-watcher, pr-manager, pr-reviewer, pr-build-doctor, pr-doc-editor) in the bootstrap registry alongside horton and worker. Includes comprehensive test to ensure all entity types are properly exposed. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
… idempotent firstWake
Three correctness fixes from final review:
1. ctx.observe now passes { wake: { on: 'change', collections: ['signals'] } }
so the manager wakes on any worker-emitted signal (commits_pushed,
review_complete, human_input_required), not just timer/inbox.
2. Insert gate_state_changed when a gate flips and ready_to_merge when
it newly becomes true — spec §3.3 lists pr-manager as producer.
3. Guard pr_meta and agent_state inserts with empty-collection checks so
re-delivered firstWake events don't crash on duplicate-key inserts.
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## main #4296 +/- ##
==========================================
+ Coverage 57.23% 59.21% +1.98%
==========================================
Files 227 266 +39
Lines 23013 24892 +1879
Branches 6006 6493 +487
==========================================
+ Hits 13171 14741 +1570
- Misses 9837 10144 +307
- Partials 5 7 +2
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
✅ Deploy Preview for electric-next ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Draft design for PR Shepherds — a multi-agent system that shepherds GitHub PRs through a fixed set of gates (template, CI, conflicts, review threads, docs) until ready to merge. First non-trivial multi-agent system on the Electric Agents reactive-blackboard pattern.
The primary goal is to exercise the framework end-to-end on a real workload, find platform bugs, and surface improvements before tackling harder agentic systems.
Three worker agents (
pr-reviewer,pr-build-doctor,pr-doc-editor) plus a thinpr-managerand discoverypr-watcher. Each is a hybrid: TS entity shell wires subscriptions/tools/prelude; the agent's reasoning lives in a markdown skill atpackages/agents/skills/pr/<role>.md.Spec at
docs/superpowers/specs/2026-05-08-pr-shepherds-design.md. Sections cover entities, shared blackboard schema, signal vocabulary, subscription mechanism, per-role decision trees, iteration caps +/continue//stopslash-commands, safety gates (agentslabel entry, worktree lock, no force-push), failure modes, phase-1/phase-2 boundary, testing strategy, component layout, and §15 Templates (PR description, review thread comment, status comment, commit message, slash-command grammar).Deliberately limited (per §2): no coding agent, one repo per watcher, no webhooks (phase 1), no automerge, not a general-purpose framework.
Test plan
ctx.observe(...).where(...)) matches what §3.4 assumes.🤖 Generated with Claude Code