[codex] Add create-issue-interaction-ui maintainer skill (#7659)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Issue-thread interactions are one of the core ways agents pause for
structured board or user decisions.
> - Adding a new interaction kind currently requires coordinated changes
across shared contracts, server behavior, UI cards, fixtures,
CLI/MCP/plugin SDK helpers, and agent guidance.
> - The checkbox-confirmation rollout established a good end-to-end
pattern, but contributors needed a durable maintainer checklist for
repeating that work.
> - This pull request adds a developer/maintainer skill that captures
that workflow inside the repo under `.agents/skills`.
> - The benefit is a reusable implementation guide for future
interaction-card work without installing that guidance on runtime
Paperclip agents.

## Linked Issues or Issue Description

Paperclip issue: [PAP-10457](/PAP/issues/PAP-10457)

This PR documents the process for adding a new issue-thread interaction
family end-to-end. There is no GitHub issue for this Paperclip-internal
skill addition.

## What Changed

- Added `.agents/skills/create-issue-interaction-ui/SKILL.md` as a
developer/maintainer skill.
- Covered shared contract, server route/service behavior, UI card
wiring, fixtures/Storybook, CLI/MCP/plugin SDK helpers, agent guidance,
invariants, and focused verification.
- Referenced the checkbox-confirmation rollout (`4d5322c82`, PR `#7649`)
as the canonical worked example.

## Verification

- `git diff --check origin/master..HEAD`
- `NODE_ENV=test pnpm exec vitest run
server/src/__tests__/paperclip-skill-utils.test.ts`
- Reviewed the added skill markdown for scope, location, and workflow
completeness.

## Risks

Low risk. This is a documentation/skill-only change under
`.agents/skills`; it does not change runtime code, database schema, API
behavior, or installed production-agent guidance.

> 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

OpenAI Codex coding agent based on GPT-5, with shell and GitHub CLI tool
access. Exact hosted model variant and context-window size were not
exposed by the runtime.

## 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 run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] 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>

.agents/skills/create-issue-interaction-ui/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: create-issue-interaction-ui
+description: >
+  Developer/maintainer skill for adding a new issue-thread interaction kind to
+  the Paperclip codebase end-to-end: shared contract, server service/routes,
+  UI card, fixtures/Storybook, CLI/MCP/plugin SDK helpers, agent guidance, and
+  tests. Use when a Paperclip contributor is asked to introduce a new
+  interaction family (something analogous to `request_confirmation`,
+  `request_checkbox_confirmation`, `ask_user_questions`, or `suggest_tasks`)
+  or to extend the issue-thread interaction system with a new card type. Do
+  NOT install this on production Paperclip agents — it is for repo work, not
+  agent runtime behavior.
+---
+
+# Create a new issue-thread interaction UI (developer skill)
+
+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.
+
+## 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:
+
+| Layer        | Owns                                                                                              |
+|--------------|---------------------------------------------------------------------------------------------------|
+| Shared       | Kind constant, payload/result interfaces, Zod validators, exported types, shared-test coverage.    |
+| Server       | Service create/accept/reject/respond, staleness, supersede, idempotency, activity log, wake send. |
+| UI           | Card pending/resolved/stale states, fixtures, Storybook, issue-thread/IssueDetail wiring.         |
+| Helpers/Docs | CLI 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:
+
+```sh
+git show --stat 4d5322c82
+```
+
+The plan it implemented is preserved as an issue document on
+[PAP-10415](/PAP/issues/PAP-10415#document-plan). 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:
+
+```sh
+NODE_ENV=test pnpm run preflight:workspace-links
+NODE_ENV=test pnpm exec vitest run \
+  packages/shared/src/issue-thread-interactions.test.ts \
+  server/src/__tests__/issue-thread-interaction-routes.test.ts \
+  server/src/__tests__/issue-thread-interactions-service.test.ts \
+  ui/src/components/IssueThreadInteractionCard.test.tsx \
+  ui/src/lib/issue-thread-interactions.test.ts \
+  cli/src/__tests__/issue-subresources.test.ts \
+  packages/mcp-server/src/tools.test.ts \
+  packages/plugins/sdk/tests/testing-actions.test.ts
+```
+
+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.

.github/CODEOWNERS

@@ -8,6 +8,7 @@ scripts/rollback-latest.sh @cryppadotta @devinfoley
 doc/RELEASING.md @cryppadotta @devinfoley
 doc/PUBLISHING.md @cryppadotta @devinfoley
 doc/RELEASE-AUTOMATION-SETUP.md @cryppadotta @devinfoley
+skills/** @cryppadotta @devinfoley
 
 # Package files — dependency changes require review
 # package.json matches recursively at all depths (covers root + all workspaces)

server/src/__tests__/paperclip-skill-utils.test.ts

@@ -61,6 +61,21 @@ describe("paperclip skill utils", () => {
     await expect(fs.access(path.resolve("scripts/paperclip-upload-artifact.sh"))).rejects.toThrow();
   });
 
+  it("keeps the create-issue-interaction-ui guide as a maintainer-only skill", async () => {
+    const skillPath = path.resolve(".agents/skills/create-issue-interaction-ui/SKILL.md");
+    const skillBody = await fs.readFile(skillPath, "utf8");
+    const normalizedSkillBody = skillBody.replace(/\s+/g, " ");
+
+    expect(skillBody).toContain("name: create-issue-interaction-ui");
+    expect(skillBody).toContain("Developer/maintainer skill");
+    expect(normalizedSkillBody).toContain("Do NOT install this on production Paperclip agents");
+    expect(skillBody).toContain("packages/shared/src/constants.ts");
+    expect(skillBody).toContain("server/src/services/issue-thread-interactions.ts");
+    expect(skillBody).toContain("ui/src/components/IssueThreadInteractionCard.tsx");
+    expect(skillBody).toContain("packages/plugins/sdk/src/testing.ts");
+    await expect(fs.access(path.resolve("skills/create-issue-interaction-ui/SKILL.md"))).rejects.toThrow();
+  });
+
   it("marks skills with required: false in SKILL.md frontmatter as optional", async () => {
     const root = await makeTempDir("paperclip-skill-optional-");
     cleanupDirs.add(root);