- name
- create-external-bot-integration
- description
- - Build and qualify external bots such as Dot in Paperclip. Use for two-way work, invitation, identity, wakeup, Runner lifecycle, native tools, recovery, and Cloud delivery. CLI adapters and app-only connectors use their existing skills.
Create an External Bot Integration
Make an existing external agent a useful Paperclip participant: Paperclip can assign work to it, and it can initiate governed work from its own conversation. It uses its relevant native capabilities, returns inspectable results to Paperclip, and participates in normal admission, authority, and finalization.
This workflow incorporates the September 30–October 9, 2026 Dot integration. Provider facts and code paths in the references are dated evidence, not a claim that every future bot supports the same APIs. Verify the current implementation and official provider documentation before choosing a transport or changing code.
1. Establish the release contract before narrowing the implementation
Read release-contract.md. Infer already-stated requirements and authorization from the conversation. Ask only about consequential unknowns; do not ask the user to repeat “two way,” Cloud, or use of Runner.
Record the target environment, acting identity, capabilities, allowed human setup steps, delivery/stop expectations, and checkable finish line. Keep one compact matrix in the existing plan or task. Follow repository conventions if creating a plan file. “Works” must name its level: prototype, real provider, real Runner, managed sandbox, deployed tenant, or unattended first-time onboarding.
Reuse the current implementation and qualification evidence. Inspect the relevant checkout, instructions, app/Cloud PRs, and Runner artifact. Do not recreate work already merged or apply an old plan to a different deployed revision.
2. Prove the uncertain provider boundary first
Identify supported ways to authenticate, wake the agent, load tools, correlate work, return results, and stop or revoke authority. Check events/subscriptions as well as direct APIs and chat channels. Do not assume that a bot mention wakes another bot, that MCP notifications wake an offline agent, or that a plugin listed in settings is callable in the agent's current conversation.
Use a synthetic company and stable public HTTPS endpoint. Start with a scripted client for deterministic protocol tests, then the actual provider account:
- Fresh connection → callable read tool → verified event round trip.
- Paperclip assignment → autonomous acceptance → persisted result → finalization.
- Idle bot request → one governed intake → useful action → finalization.
If idle autonomy is in scope, the third journey is a first milestone, not an optional expansion. Do not make the user create a placeholder task for the bot. Label every nudge, operator repair, simulated dependency, and manual tool call. A successful assisted run does not prove prompt-only first-time setup.