The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
[codex] Add create-issue-interaction-ui maintainer skill (#7659)
Dottaf09d4231e354
diff --git a/.agents/skills/create-issue-interaction-ui/SKILL.md b/.agents/skills/create-issue-interaction-ui/SKILL.mdnew file mode 100644index 0000000000..9a3bdde25c--- /dev/null+++ b/.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.diff --git a/.github/CODEOWNERS b/.github/CODEOWNERSindex 0b8981e151..09e65d3cfc 100644--- a/.github/CODEOWNERS+++ b/.github/CODEOWNERS@@ -8,6 +8,7 @@ scripts/rollback-latest.sh @cryppadotta @devinfoleydoc/RELEASING.md @cryppadotta @devinfoleydoc/PUBLISHING.md @cryppadotta @devinfoleydoc/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)diff --git a/server/src/__tests__/paperclip-skill-utils.test.ts b/server/src/__tests__/paperclip-skill-utils.test.tsindex d5d56848d1..aae6c70abe 100644--- a/server/src/__tests__/paperclip-skill-utils.test.ts+++ b/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);