Paperclip Atlassian Source Intake

Reliable Jira and Confluence source-comment intake for Paperclip.

This plugin is intended to make Atlassian comments first-class Paperclip source events. It exists because agent prompts and hourly heuristics are not reliable enough for comments added to Jira issues, Confluence design specs, child pages, inline comments, or nested comment replies after work is already in progress.

Current Status

This repository is an initial scaffold. It defines:

• a Paperclip plugin manifest
• Jira and Confluence webhook endpoints
• a plugin-owned database namespace
• a canonical artifact/comment event schema
• managed Paperclip project, agent, routine, and skill declarations
• minimal dashboard/settings UI
• tests for source-comment event normalization, including nested replies

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

Why This Exists

Paperclip agents should not each invent their own Jira/Confluence comment cursor. The plugin owns the reliable graph and event contract, while agents own external Atlassian reads:

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

Covered Source Surfaces

The model explicitly includes:

• jira_comments
• confluence_footer_comments
• confluence_inline_comments
• confluence_footer_comment_replies
• confluence_inline_comment_replies

Nested replies 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 /comment-surfaces
• set-lifecycle / POST /artifact-lifecycle
• active-surfaces / GET /active-surfaces
• coverage-audit / GET /coverage-audit
• record-comment-event / POST /comment-events

Example flow:

Tech spec created
  -> register Jira Epic artifact
  -> register Confluence page artifact
  -> register edge: Jira Epic -> Confluence tech spec
  -> register footer, inline, footer-reply, and inline-reply comment surfaces

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.atlassian-source-intake

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-atlassian
paperclipai plugin inspect paperclip.atlassian-source-intake

Planned MVP

1. Add agent-owned Jira/JPD/Confluence sync routines for active artifacts and recently completed artifacts.
2. Implement Confluence footer comments, inline comments, child-page, and nested reply traversal in the agent sync contract.
3. Convert Jira/Confluence webhook payloads into source-comment events.
4. Add daily graph coverage audit for missing child pages/comment surfaces.
5. Route new human comments into Paperclip issues with durable origin ids.
6. Add settings UI for project keys, Confluence spaces, and ignored authors.

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 Atlassian credentials in plugin settings; keep credentials on the agents or host services that perform source synchronization.