Paperclip GitHub PR Feedback

Reliable GitHub pull request feedback, review, workflow, and check-run intake for Paperclip.

This plugin is intended to make GitHub pull request operational signals first-class Paperclip source events. It exists because agents should not rely on ad hoc polling or prompt memory to notice pull request review feedback, inline review threads, failing checks, workflow state, merge conflicts, or issue comments.

Current Status

This repository is an initial scaffold. It defines:

• a Paperclip plugin manifest
• a GitHub webhook endpoint
• a plugin-owned database namespace
• a canonical artifact/source-event schema
• managed Paperclip project, agent, routine, and skill declarations
• minimal dashboard/settings UI
• tests for source-event normalization, including review threads

The plugin intentionally does not store or resolve GitHub credentials. GitHub API reads are owned by Paperclip agents, which write normalized artifacts, surfaces, lifecycle, and events into this plugin.

Usability Gate

The current plugin is installable and useful as the shared graph contract for GitHub PR feedback, but it is not a credentialed unattended connector by itself.

Before it can keep PR feedback moving without manual intervention, it needs:

• agent instructions/routines that call GitHub with agent-owned credentials and write this plugin graph on every heartbeat
• GitHub webhook payload conversion into normalized source events
• source-event routing into Paperclip issues or wakeups
• durable handling for failing checks, stale review threads, merge conflicts, and late comments after merge
• ignored-author and bot policy enforcement
• repository settings validation in the plugin settings UI

Why This Exists

Paperclip agents should not each invent their own PR feedback cursor. The plugin owns the reliable graph and event contract, while agents own external GitHub reads:

Agent GitHub scan
  -> artifact graph
  -> source surface cursor
  -> source event
  -> Paperclip issue or wakeup
  -> owning agent

Covered Source Surfaces

The model explicitly includes:

• issue_comments
• pull_request_comments
• pull_request_reviews
• pull_request_review_threads
• check_runs
• check_suites
• workflow_runs

Review threads and check/workflow state are treated as required surfaces, not edge cases.

Agent-Facing Registry Contract

Agents and orchestration routines should register what they create or discover instead of relying on later prompt heuristics.

Supported plugin actions and matching API routes:

• register-artifact / POST /artifacts
• register-edge / POST /artifact-edges
• register-surface / POST /surfaces
• set-lifecycle / POST /artifact-lifecycle
• active-surfaces / GET /active-surfaces
• coverage-audit / GET /coverage-audit
• record-source-event / POST /source-events

Example flow:

Pull request opened
  -> register repository artifact
  -> register pull request artifact
  -> register edge: repository -> pull request
  -> register PR comments, reviews, review threads, check runs, and workflow runs

Lifecycle states:

• registered
• active
• grace
• closed
• archived
• reopened

Agent heartbeat scans should read registered, active, grace, and reopened surfaces. closed and archived surfaces should not receive routine polling, but newly observed source activity can reopen them.

Development

pnpm install
pnpm typecheck
pnpm test
pnpm build

For local Paperclip development:

pnpm dev
paperclipai plugin install <absolute-path-to-plugin>
paperclipai plugin inspect paperclip.github-pr-feedback

If paperclipai is not on PATH, use npx paperclipai.

For a published package install, use the package name instead of a local path:

paperclipai plugin install paperclip-plugin-github-pr
paperclipai plugin inspect paperclip.github-pr-feedback

Planned MVP

1. Implement GitHub webhook payload conversion for PR comments, reviews, review threads, issues, checks, and workflow runs.
2. Add agent-owned GitHub sync routines for active PRs, recently merged PRs, and open issues.
3. Add merge-conflict and failing-check classification.
4. Add daily graph coverage audit for missing PR review/check surfaces.
5. Route new human or review-bot feedback into Paperclip issues with durable origin ids.
6. Add settings UI for repositories, ignored authors, and routing policies.

Trust Model

Paperclip alpha plugins are trusted local or npm-installed code. Do not install this plugin from an untrusted source. This plugin does not require GitHub credentials in plugin settings; keep credentials on the agents or host services that perform source synchronization.