## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Teams often keep their work in external ticket systems
> - Paperclip must keep execution and governance control when those
systems supply work
> - Connector authors need one provider-neutral contract for links,
routing, sync, and recovery
> - This pull request adds that contract as a draft specification
> - The benefit is a shared design for external task connectors without
provider logic in Paperclip core
## Linked Issues or Issue Description
- Refs: #3587
- Related prior connector work: #6271
- Supersedes the non-reopenable #7904.
- Duplicate #10569 was opened during concurrent recovery; this PR
contains the later review fixes
and is the 5/5, green canonical replacement. Recommend closing #10569
without merging it.
## What Changed
- Added a normative External Task Protocol for provider-neutral task
data, link state, routing, synchronization, conflicts, and health.
- Defined a Symphony-compatible execution profile that uses Paperclip
checkout, heartbeat, workspace, budget, approval, and blocker controls.
- Added provider profiles for Linear, Jira, Asana, Notion, Trello, and
GitHub Issues.
- Fixed the link-state transitions, reopen invariant, and section
cross-reference found in review.
- Updated the connector boundary to name the current capability-gated
plugin host clients.
- Aligned backlog wake semantics and issue-scoped run-stop conformance
with the current host API.
- Made terminal-to-active follow-up handoff retry-safe using a
single-record `TaskLink` retarget and
auditable handoff history, without assuming unavailable multi-record
plugin transactions.
- Preserved and refreshed Dotta's original specification work.
## Verification
- Ran `git diff --check`.
- Checked every numbered section reference against the document
headings.
- Compared the protocol integration points with the current plugin SDK
and host issue contracts.
- Ran the current PR template, linked-issue, duplicate-search, and
test-coverage quality gates against this description and title.
## Risks
- Low runtime risk. This pull request changes documentation only.
- The specification can constrain future connector designs. It remains a
draft and keeps provider-specific behavior in plugins.
- The replacement keeps the legacy `PAP-10377-task-protocol` head ref
because renaming it closed
#7904 and GitHub would not reopen that PR after the ref was restored.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
- The original draft used Claude Code. This review repair used OpenAI
Codex with GPT-5. The exact API snapshot and context window are not
exposed. The run used reasoning, repository inspection, shell tools, and
code editing.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] Branch naming exception is documented above; the legacy public
issue branch was retained to preserve the repaired head ref
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
Co-authored-by: Dev Agent <dev@paperclip.ing>
Product spec for ClipHub — a marketplace for Paperclip team
configurations, agent blueprints, skills, and governance templates.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Restored docs/ directory that was accidentally deleted by `git add -A`
in the v0.2.3 release script
- Replaced generic "P" favicon with actual paperclip icon using brand
primary color (#2563EB)
- Added light/dark logo SVGs for Mintlify navbar (paperclip icon + wordmark)
- Updated docs.json with logo configuration for dark/light mode
- Fixed release.sh to stage only release-related files instead of `git add -A`
to prevent sweeping unrelated changes into release commits
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Introduce testEnvironment() on ServerAdapterModule with structured
pass/warn/fail diagnostics for all four adapter types (claude_local,
codex_local, process, http). Adds POST test-environment endpoint,
shared types/validators, adapter test implementations, and UI API
client. Includes asset type foundations used by related features.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Move doc/specs/ui.md to doc/spec/ui.md. Move plans/module-system.md to
doc/plans/. Add doc/spec/agents-runtime.md and docs/ reference specs.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Dotta
Dotta
Forgotten