create-issue-interaction-ui skill

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

rating, in-thread approval card, etc.).

• A new interaction kind is being introduced (compact picker, structured

shape, validation, or resolution outcome (and askuserquestions is the wrong fit because option count, target binding, or result shape differs).

• An existing interaction needs a parallel variant with a distinct payload

semantics as the other interactions" on a new card.

• A reviewer asks for "the same audit, staleness, supersede, and continuation

When NOT to use

payload schema. Patch the existing validators/UI in place instead.

• Adding fields to an existing interaction kind that does not need a new

or references/api-reference.md; that is agent guidance, not card work.

• Changing how Paperclip agents call interactions. Update skills/paperclip

Those have their own component conventions.

• Building a non-thread UI (issue detail sidebar, project board widget, etc.).

Mental model

Every issue-thread interaction has five moving parts:

Use the current ISSUETHREADINTERACTION_KINDS as the inventory. Pick the closest existing kind and reuse its plumbing rather than inventing parallel mechanics:

• request_confirmation — single yes/no bound to a target with stale/supersede.
• requestcheckboxconfirmation — bounded multi-select against an immutable option set.
• askuserquestions — small typed form, no target binding.
• requestitemverdicts — requests individual decisions on a set of items.
• suggest_tasks — proposes tasks a permitted resolver can accept individually.
• connection_intent — requests authorized connection setup or access.

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 askuserquestions. If it produces creatable child entities, model it after suggesttasks.

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:

ISSUETHREADINTERACTIONKINDS and any size constant (mirror REQUESTCHECKBOXCONFIRMATIONOPTION_LIMIT = 200).

• packages/shared/src/constants.ts — add the kind string to

and Interaction interfaces. Extend the IssueThreadInteraction and payload/result union types at the bottom of the file.

• packages/shared/src/types/issue.ts — add Option, Payload, Result,

result, and the create-input variant. Reuse the existing requestConfirmationTargetSchema when target binding applies.

• packages/shared/src/types/index.ts — re-export the new types.
• packages/shared/src/validators/issue.ts — add Zod schemas for payload,

tests for the new payload variant.

• 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

Validation invariants that have already been litigated and must hold:

can render compactly).

• Option lists are bounded (the checkbox kind uses 200; pick a number the UX

reference known ids.

• Option ids are unique within a payload and any default selection must

options. Do not invent looser caps.

• Labels and descriptions are length-capped to match existing question

expiration runs through one code path.

• Target binding uses the shared RequestConfirmationTarget schema so stale

2. Server service and routes

Touch:

the response-shape branch around line 6096 in the checkbox PR).

• 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

create, accept-with-result, reject-with-reason, stale-target expiration, supersede-on-user-comment, idempotency conflict, and wake payload shape.

• server/src/tests/issue-thread-interactions-service.test.ts — cover

create + respond/accept/reject HTTP behavior, company scoping, and authorization.

• server/src/tests/issue-thread-interaction-routes.test.ts — cover

Server invariants:

addressee checks in the shared service. Governed actions retain their required human approval; neither a new kind nor a channel callback widens authority.

• Resolver authority. Use the current resolver policy, company cap, and named

by companyId. Never trust an issueId alone.