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:
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/__tests__/issue-thread-interactions-service.test.ts — cover
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-interaction-routes.test.ts — cover
create + respond/accept/reject HTTP behavior, company scoping, and
authorization.
Server invariants:
Board-only resolution. Agent-authored accept/reject must be rejected with
the existing 403 path; do not add a per-kind bypass.
Company scoping. Reads, writes, expiration, and supersede must all filter
by companyId. Never trust an issueId alone.
Stale target. If target was specified at create time and a newer revision
lands, the interaction expires with outcome: "stale_target". Do not write
bespoke staleness — call the same helper the other request_* kinds use.
Supersede on user comment. Default supersedeOnUserComment: true unless
the payload schema documents otherwise.
Idempotency. The deterministic idempotencyKey shape from the existing
kinds (<kind>:<issueId>:<decisionKey>:<revisionId>) must be honored;
duplicate POSTs must return the existing card, not stack.
Continuation policy. Support none, wake_assignee, and
wake_assignee_on_accept. Pick a default that matches whether the
asker is blocked waiting for the answer (wake_assignee) or only cares
about acceptance (wake_assignee_on_accept).
3. UI card and issue-thread wiring
Touch:
ui/src/components/IssueThreadInteractionCard.tsx — add a card component
(e.g. RequestCheckboxConfirmationCard) and a resolution component
(e.g. RequestCheckboxConfirmationResolution). Branch the existing
switch by interaction.kind. Reuse the card shell — do not introduce a
parallel card frame.
ui/src/lib/issue-thread-interactions.ts — add typed helpers like
getCheckboxConfirmationSelectedLabels so the card stays declarative.
ui/src/lib/issue-thread-interactions.test.ts — test the helpers.
ui/src/components/IssueThreadInteractionCard.test.tsx — pending,
resolved, stale, disabled/submitting, and validation-error states.
ui/src/fixtures/issueThreadInteractionFixtures.ts — seed at least one
pending and one resolved fixture for the new kind.
ui/src/stories/issue-thread-interactions.stories.tsx — Storybook entries
for the key states.
ui/src/pages/IssueDetail.tsx — extend the per-kind branches the card is
rendered from (callback wiring, response submission).
ui/src/components/IssueChatThread.tsx — if the kind affects thread-level
rendering (badge, summary, count), update the per-kind switches here.
ui/src/api/issues.ts — extend the typed accept/reject/respond bodies.
UI invariants:
Compact rendering. The card must render comfortably with ~100 options
(bounded scroll area, count-first resolved-state summaries — do not chip
every selected option inline).
Select all and clear selection live inside the card, not in a global menu.
The accept payload uses kind-specific field names (e.g. selectedOptionIds,
not the suggest-tasks selectedClientKeys). Do not reuse another kind's
field name.
Stale, superseded, and accepted states render distinct copy; reuse the
existing resolution-component shell.
4. CLI, MCP, plugin SDK helpers
External callers must be able to create the new interaction without
hand-writing JSON. Touch:
cli/src/commands/client/issue.ts — add a CLI sub-command or extend the
generic interaction create path.
cli/src/__tests__/issue-subresources.test.ts — cover the new flag set.
packages/mcp-server/src/tools.ts — add an MCP tool that accepts the new
payload shape; reuse the existing createIssueThreadInteraction codepath.
packages/mcp-server/src/tools.test.ts — cover the tool's payload shape.
packages/plugins/sdk/src/types.ts — add the typed
CreateIssueThreadInteraction variant so plugin authors get autocomplete.
packages/plugins/sdk/src/worker-rpc-host.ts — extend the kind switch in
the create call.
packages/plugins/sdk/src/testing.ts — extend the test harness so plugins
can simulate the new kind end-to-end.
packages/plugins/sdk/tests/testing-actions.test.ts — round-trip test for
the new kind through the test harness.
5. Agent guidance
Touch:
skills/paperclip/SKILL.md — add a row to the interaction-kinds table:
when to use, when not to use, plus a copyable payload example.
skills/paperclip/references/api-reference.md — full payload and result
schemas, validation limits, create/respond bodies, error codes.
The skills text is read by the runtime agents. Keep it concise — differentiate
clearly from sibling kinds in one or two sentences each.
Tests to run before requesting review
The checkbox PR ran exactly this focused set under NODE_ENV=test. Use the
same shape for any new kind, swapping in your new test files:
If UI vitest fails with act is not a function, the shell is running with
NODE_ENV=production (it picks up React's prod build). Re-run with
NODE_ENV=test explicitly.
Pre-merge checklist
New kind appears in ISSUE_THREAD_INTERACTION_KINDS and is exported.
Payload and result interfaces are versioned (start at version: 1).
Zod validators enforce option/label/description limits and id uniqueness.
Target binding (if any) uses the shared RequestConfirmationTarget path.
Service handles create, accept, reject/respond, stale-target,
supersede-on-user-comment, idempotency, activity log, and continuation
wake.
Routes honor board-only resolution and company scoping.
UI renders pending, resolved, stale, disabled/submitting, and
validation-error states; resolved-state large selections summarize by
count first.
Fixtures and Storybook entries exist for the new kind.
CLI, MCP, and plugin SDK helpers all accept the new payload shape and
have test coverage.
skills/paperclip/SKILL.md and references/api-reference.md updated.
Focused test set above is green; CI gates pass.
Anti-patterns observed in review
These came out of the checkbox PR review thread and are worth avoiding next
time:
Reusing another kind's accept-payload field name (e.g. piggybacking on
selectedClientKeys instead of introducing selectedOptionIds). Each kind
owns its own field names.
Writing parallel staleness or supersede logic instead of routing through
the existing request_confirmation helpers. This silently drifts behavior.
Rendering hundreds of selected-option chips in the resolved state. Resolved
large selections must summarize by count first.
Skipping plugin SDK / MCP / CLI coverage on the theory that "the API is
generic enough." External callers do not pick up new kinds without typed
helpers, and the absence shows up later as broken agent flows.
Adding the kind to skills guidance before the server route accepts it.
Agents will try the new kind and 400 in production.
1---
2name: create-issue-interaction-ui
3description: >
4 Add a new Paperclip issue-thread interaction kind end-to-end. Use when repo
5 work introduces or extends interaction cards like request_confirmation,
6 checkbox confirmations, ask_user_questions, or suggest_tasks.
7metadata:
8 source: https://skillmd.com/skills/paperclipai/create-issue-interaction-ui
9---
1011# Create a new issue-thread interaction UI (Developer/maintainer skill)
1213Developer/maintainer skill. Do NOT install this on production Paperclip agents.
1415This skill walks a Paperclip contributor through introducing a new issue-thread
16interaction kind from shared contract to issue-detail wiring, helpers, and
17docs. It is intentionally a developer/maintainer skill: the audience is a
18human or coding agent making code changes inside `paperclipai/paperclip`, not
19the operational agents that run inside a deployed Paperclip company.
2021Do NOT install this on production Paperclip agents. This guide is for repository contributors changing Paperclip itself.
2223## When to use
2425- A new interaction kind is being introduced (compact picker, structured
26 rating, in-thread approval card, etc.).
27- An existing interaction needs a parallel variant with a distinct payload
28 shape, validation, or resolution outcome (and `ask_user_questions` is the
29 wrong fit because option count, target binding, or result shape differs).
30- A reviewer asks for "the same audit, staleness, supersede, and continuation
31 semantics as the other interactions" on a new card.
3233## When NOT to use
3435- Adding fields to an existing interaction kind that does not need a new
36 payload schema. Patch the existing validators/UI in place instead.
37- Changing how Paperclip agents *call* interactions. Update `skills/paperclip`
38 or `references/api-reference.md`; that is agent guidance, not card work.
39- Building a non-thread UI (issue detail sidebar, project board widget, etc.).
40 Those have their own component conventions.
4142## Mental model
4344Every issue-thread interaction has four moving parts:
4546| Layer | Owns |
47|--------------|---------------------------------------------------------------------------------------------------|
48| Shared | Kind constant, payload/result interfaces, Zod validators, exported types, shared-test coverage. |
49| Server | Service create/accept/reject/respond, staleness, supersede, idempotency, activity log, wake send. |
50| UI | Card pending/resolved/stale states, fixtures, Storybook, issue-thread/IssueDetail wiring. |
51| Helpers/Docs | CLI command, MCP tool, plugin SDK type+host+testing path, `skills/paperclip` guidance. |
5253The four existing kinds are the canonical prior art. Pick the closest one and
54copy its plumbing rather than inventing parallel mechanics:
5556- `request_confirmation` — single yes/no bound to a `target` with stale/supersede.
57- `request_checkbox_confirmation` — bounded multi-select against an immutable option set.
58- `ask_user_questions` — small typed form, no target binding.
59- `suggest_tasks` — proposes tasks the board can accept individually.
6061If your new card needs target binding and a yes/no-style resolution, model it
62after the two `request_*` kinds. If it is a structured form, model it after
63`ask_user_questions`. If it produces creatable child entities, model it after
64`suggest_tasks`.
6566## The canonical worked example
6768The current best end-to-end reference is the checkbox confirmation rollout
69(merged in `4d5322c82`, GitHub PR `#7649`). Read that diff before starting:
7071```sh
72git show --stat 4d5322c82
73```
7475The plan it implemented is preserved as an issue document on
76[PAP-10415](/PAP/issues/PAP-10415#document-plan). Use it as the template for
77your own plan document if you are running this work through Paperclip itself.
7879## Order of operations
8081Do the shared contract first. It is the smallest correct change you can land
82even before UI is final, and every later layer reads its types and validators.
8384### 1. Shared contract (smallest, lands first)
8586Touch:
8788- `packages/shared/src/constants.ts` — add the kind string to
89 `ISSUE_THREAD_INTERACTION_KINDS` and any size constant (mirror
90 `REQUEST_CHECKBOX_CONFIRMATION_OPTION_LIMIT = 200`).
91- `packages/shared/src/types/issue.ts` — add `Option`, `Payload`, `Result`,
92 and `Interaction` interfaces. Extend the `IssueThreadInteraction` and
93 payload/result union types at the bottom of the file.
94- `packages/shared/src/types/index.ts` — re-export the new types.
95- `packages/shared/src/validators/issue.ts` — add Zod schemas for payload,
96 result, and the create-input variant. Reuse the existing
97 `requestConfirmationTargetSchema` when target binding applies.
98- `packages/shared/src/validators/index.ts` — re-export the new schemas.
99- `packages/shared/src/index.ts` — re-export at the package root.
100- `packages/shared/src/issue-thread-interactions.test.ts` — extend the table
101 tests for the new payload variant.
102103Validation invariants that have already been litigated and must hold:
104105- Option lists are bounded (the checkbox kind uses 200; pick a number the UX
106 can render compactly).
107- Option ids are unique within a payload and any default selection must
108 reference known ids.
109- Labels and descriptions are length-capped to match existing question
110 options. Do not invent looser caps.
111- Target binding uses the shared `RequestConfirmationTarget` schema so stale
112 expiration runs through one code path.
113114### 2. Server service and routes
115116Touch:
117118- `server/src/services/issue-thread-interactions.ts` — add the kind to:
119 - the supported-kinds list (`SUPPORTED_KINDS` near the top),
120 - `mapInteractionRow` (the `switch (row.kind)` over payload/result parsers),
121 - create-input validation (`switch (data.kind)`),
122 - the accept/reject/respond/stale-expiration branches,
123 - the activity-log payload and the continuation wake payload.
124- `server/src/routes/issues.ts` — extend any kind-specific branches (notably
125 the response-shape branch around line 6096 in the checkbox PR).
126- `server/src/__tests__/issue-thread-interactions-service.test.ts` — cover
127 create, accept-with-result, reject-with-reason, stale-target expiration,
128 supersede-on-user-comment, idempotency conflict, and wake payload shape.
129- `server/src/__tests__/issue-thread-interaction-routes.test.ts` — cover
130 create + respond/accept/reject HTTP behavior, company scoping, and
131 authorization.
132133Server invariants:
134135- Board-only resolution. Agent-authored accept/reject must be rejected with
136 the existing 403 path; do not add a per-kind bypass.
137- Company scoping. Reads, writes, expiration, and supersede must all filter
138 by `companyId`. Never trust an `issueId` alone.
139- Stale target. If `target` was specified at create time and a newer revision
140 lands, the interaction expires with `outcome: "stale_target"`. Do not write
141 bespoke staleness — call the same helper the other `request_*` kinds use.
142- Supersede on user comment. Default `supersedeOnUserComment: true` unless
143 the payload schema documents otherwise.
144- Idempotency. The deterministic `idempotencyKey` shape from the existing
145 kinds (`<kind>:<issueId>:<decisionKey>:<revisionId>`) must be honored;
146 duplicate POSTs must return the existing card, not stack.
147- Continuation policy. Support `none`, `wake_assignee`, and
148 `wake_assignee_on_accept`. Pick a default that matches whether the
149 asker is *blocked* waiting for the answer (`wake_assignee`) or only cares
150 about acceptance (`wake_assignee_on_accept`).
151152### 3. UI card and issue-thread wiring
153154Touch:
155156- `ui/src/components/IssueThreadInteractionCard.tsx` — add a card component
157 (e.g. `RequestCheckboxConfirmationCard`) and a resolution component
158 (e.g. `RequestCheckboxConfirmationResolution`). Branch the existing
159 switch by `interaction.kind`. Reuse the card shell — do not introduce a
160 parallel card frame.
161- `ui/src/lib/issue-thread-interactions.ts` — add typed helpers like
162 `getCheckboxConfirmationSelectedLabels` so the card stays declarative.
163- `ui/src/lib/issue-thread-interactions.test.ts` — test the helpers.
164- `ui/src/components/IssueThreadInteractionCard.test.tsx` — pending,
165 resolved, stale, disabled/submitting, and validation-error states.
166- `ui/src/fixtures/issueThreadInteractionFixtures.ts` — seed at least one
167 pending and one resolved fixture for the new kind.
168- `ui/src/stories/issue-thread-interactions.stories.tsx` — Storybook entries
169 for the key states.
170- `ui/src/pages/IssueDetail.tsx` — extend the per-kind branches the card is
171 rendered from (callback wiring, response submission).
172- `ui/src/components/IssueChatThread.tsx` — if the kind affects thread-level
173 rendering (badge, summary, count), update the per-kind switches here.
174- `ui/src/api/issues.ts` — extend the typed accept/reject/respond bodies.
175176UI invariants:
177178- Compact rendering. The card must render comfortably with ~100 options
179 (bounded scroll area, count-first resolved-state summaries — do not chip
180 every selected option inline).
181- Select all and clear selection live inside the card, not in a global menu.
182- The accept payload uses kind-specific field names (e.g. `selectedOptionIds`,
183 not the suggest-tasks `selectedClientKeys`). Do not reuse another kind's
184 field name.
185- Stale, superseded, and accepted states render distinct copy; reuse the
186 existing resolution-component shell.
187188### 4. CLI, MCP, plugin SDK helpers
189190External callers must be able to create the new interaction without
191hand-writing JSON. Touch:
192193- `cli/src/commands/client/issue.ts` — add a CLI sub-command or extend the
194 generic interaction create path.
195- `cli/src/__tests__/issue-subresources.test.ts` — cover the new flag set.
196- `packages/mcp-server/src/tools.ts` — add an MCP tool that accepts the new
197 payload shape; reuse the existing `createIssueThreadInteraction` codepath.
198- `packages/mcp-server/src/tools.test.ts` — cover the tool's payload shape.
199- `packages/plugins/sdk/src/types.ts` — add the typed
200 `CreateIssueThreadInteraction` variant so plugin authors get autocomplete.
201- `packages/plugins/sdk/src/worker-rpc-host.ts` — extend the kind switch in
202 the create call.
203- `packages/plugins/sdk/src/testing.ts` — extend the test harness so plugins
204 can simulate the new kind end-to-end.
205- `packages/plugins/sdk/tests/testing-actions.test.ts` — round-trip test for
206 the new kind through the test harness.
207208### 5. Agent guidance
209210Touch:
211212- `skills/paperclip/SKILL.md` — add a row to the interaction-kinds table:
213 *when to use*, *when not to use*, plus a copyable payload example.
214- `skills/paperclip/references/api-reference.md` — full payload and result
215 schemas, validation limits, create/respond bodies, error codes.
216217The skills text is read by the runtime agents. Keep it concise — differentiate
218clearly from sibling kinds in one or two sentences each.
219220## Tests to run before requesting review
221222The checkbox PR ran exactly this focused set under `NODE_ENV=test`. Use the
223same shape for any new kind, swapping in your new test files:
224225```sh
226NODE_ENV=test pnpm run preflight:workspace-links
227NODE_ENV=test pnpm exec vitest run \
228 packages/shared/src/issue-thread-interactions.test.ts \
229 server/src/__tests__/issue-thread-interaction-routes.test.ts \
230 server/src/__tests__/issue-thread-interactions-service.test.ts \
231 ui/src/components/IssueThreadInteractionCard.test.tsx \
232 ui/src/lib/issue-thread-interactions.test.ts \
233 cli/src/__tests__/issue-subresources.test.ts \
234 packages/mcp-server/src/tools.test.ts \
235 packages/plugins/sdk/tests/testing-actions.test.ts
236```
237238If UI vitest fails with `act is not a function`, the shell is running with
239`NODE_ENV=production` (it picks up React's prod build). Re-run with
240`NODE_ENV=test` explicitly.
241242## Pre-merge checklist
243244- [ ] New kind appears in `ISSUE_THREAD_INTERACTION_KINDS` and is exported.
245- [ ] Payload and result interfaces are versioned (start at `version: 1`).
246- [ ] Zod validators enforce option/label/description limits and id uniqueness.
247- [ ] Target binding (if any) uses the shared `RequestConfirmationTarget` path.
248- [ ] Service handles create, accept, reject/respond, stale-target,
249 supersede-on-user-comment, idempotency, activity log, and continuation
250 wake.
251- [ ] Routes honor board-only resolution and company scoping.
252- [ ] UI renders pending, resolved, stale, disabled/submitting, and
253 validation-error states; resolved-state large selections summarize by
254 count first.
255- [ ] Fixtures and Storybook entries exist for the new kind.
256- [ ] CLI, MCP, and plugin SDK helpers all accept the new payload shape and
257 have test coverage.
258- [ ] `skills/paperclip/SKILL.md` and `references/api-reference.md` updated.
259- [ ] Focused test set above is green; CI gates pass.
260261## Anti-patterns observed in review
262263These came out of the checkbox PR review thread and are worth avoiding next
264time:
265266- Reusing another kind's accept-payload field name (e.g. piggybacking on
267 `selectedClientKeys` instead of introducing `selectedOptionIds`). Each kind
268 owns its own field names.
269- Writing parallel staleness or supersede logic instead of routing through
270 the existing `request_confirmation` helpers. This silently drifts behavior.
271- Rendering hundreds of selected-option chips in the resolved state. Resolved
272 large selections must summarize by count first.
273- Skipping plugin SDK / MCP / CLI coverage on the theory that "the API is
274 generic enough." External callers do not pick up new kinds without typed
275 helpers, and the absence shows up later as broken agent flows.
276- Adding the kind to skills guidance before the server route accepts it.
277 Agents will try the new kind and 400 in production.
Run npx get-skill add paperclipai/create-issue-interaction-ui in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
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. It is listed under Coding & Dev Tools on SkillMD.
This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: docs only. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
paperclipai (@paperclipai) published this skill. Their other Agent Skills are listed on their SkillMD profile.