Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Design & UI

create-issue-interaction-ui

Add a new Paperclip issue-thread interaction kind end-to-end. Use when repo work introduces or extends interaction cards like request_confirmation, checkbox confirmations, ask_user_questions, or suggest_tasks.

paperclipai · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add paperclipai/paperclip --skill create-issue-interaction-ui

About this skill


name: create-issue-interaction-ui description: > Add a new Paperclip issue-thread interaction kind end-to-end. Use when repo work introduces or extends interaction cards like request_confirmation, checkbox confirmations, ask_user_questions, or suggest_tasks.

Create a new issue-thread interaction UI (Developer/maintainer skill)

Developer/maintainer skill. Do NOT install this on production Paperclip agents.

This skill walks a Paperclip contributor through introducing a new issue-thread interaction kind from shared contract to issue-detail wiring, helpers, and docs. It is intentionally a developer/maintainer skill: the audience is a human or coding agent making code changes inside paperclipai/paperclip, not the operational agents that run inside a deployed Paperclip company.

Do NOT install this on production Paperclip agents. This guide is for repository contributors changing Paperclip itself.

When to use

  • A new interaction kind is being introduced (compact picker, structured rating, in-thread approval card, etc.).
  • An existing interaction needs a parallel variant with a distinct payload shape, validation, or resolution outcome (and ask_user_questions is the wrong fit because option count, target binding, or result shape differs).
  • A reviewer asks for "the same audit, staleness, supersede, and continuation semantics as the other interactions" on a new card.

When NOT to use

  • Adding fields to an existing interaction kind that does not need a new payload schema. Patch the existing validators/UI in place instead.
  • Changing how Paperclip agents call interactions. Update skills/paperclip or references/api-reference.md; that is agent guidance, not card work.
  • Building a non-thread UI (issue detail sidebar, project board widget, etc.). Those have their own component conventions.

Mental model

Every issue-thread interaction has four moving parts:

LayerOwns
SharedKind constant, payload/result interfaces, Zod validators, exported types, shared-test coverage.
ServerService create/accept/reject/respond, staleness, supersede, idempotency, activity log, wake send.
UICard pending/resolved/stale states, fixtures, Storybook, issue-thread/IssueDetail wiring.
Helpers/DocsCLI command, MCP tool, plugin SDK type+host+testing path, skills/paperclip guidance.

The four existing kinds are the canonical prior art. Pick the closest one and copy its plumbing rather than inventing parallel mechanics:

  • request_confirmation — single yes/no bound to a target with stale/supersede.
  • request_checkbox_confirmation — bounded multi-select against an immutable option set.
  • ask_user_questions — small typed form, no target binding.
  • suggest_tasks — proposes tasks the board can accept individually.

If your new card needs target binding and a yes/no-style resolution, model it after the two request_* kinds. If it is a structured form, model it after ask_user_questions. If it produces creatable child entities, model it after suggest_tasks.

The canonical worked example

The current best end-to-end reference is the checkbox confirmation rollout (merged in 4d5322c82, GitHub PR #7649). Read that diff before starting:

git show --stat 4d5322c82

The plan it implemented is preserved as an issue document on PAP-10415. Use it as the template for your own plan document if you are running this work through Paperclip itself.

Order of operations

Do the shared contract first. It is the smallest correct change you can land even before UI is final, and every later layer reads its types and validators.

1. Shared contract (smallest, lands first)

Touch:

  • packages/shared/src/constants.ts — add the kind string to ISSUE_THREAD_INTERACTION_KINDS and any size constant (mirror REQUEST_CHECKBOX_CONFIRMATION_OPTION_LIMIT = 200).
  • packages/shared/src/types/issue.ts — add Option, Payload, Result, and Interaction interfaces. Extend the IssueThreadInteraction and payload/result union types at the bottom of the file.
  • packages/shared/src/types/index.ts — re-export the new types.
  • packages/shared/src/validators/issue.ts — add Zod schemas for payload, result, and the create-input variant. Reuse the existing requestConfirmationTargetSchema when target binding applies.
  • packages/shared/src/validators/index.ts — re-export the new schemas.
  • packages/shared/src/index.ts — re-export at the package root.
  • packages/shared/src/issue-thread-interactions.test.ts — extend the table tests for the new payload variant.

Validation invariants that have already been litigated and must hold:

  • Option lists are bounded (the checkbox kind uses 200; pick a number the UX can render compactly).
  • Option ids are unique within a payload and any default selection must reference known ids.
  • Labels and descriptions are length-capped to match existing question options. Do not invent looser caps.
  • Target binding uses the shared RequestConfirmationTarget schema so stale expiration runs through one code path.

2. Server service and routes

Touch:

  • server/src/services/issue-thread-interactions.ts — add the kind to:
    • the supported-kinds list (SUPPORTED_KINDS near the top),
    • mapInteractionRow (the switch (row.kind) over payload/result parsers),
    • create-input validation (switch (data.kind)),
    • the accept/reject/respond/stale-expiration branches,
    • the activity-log payload and the continuation wake payload.
  • server/src/routes/issues.ts — extend any kind-specific branches (notably the response-shape branch around line 6096 in the checkbox PR).
  • `server/src/__test
Read the complete source ↗