100 Commits

Author	SHA1	Message	Date
Devin Foley	33353ce62b	feat(skills): remove bundled paperclip-dev skill and retire required skill attribute (#7029) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Local adapters (Claude, Codex, Cursor, Gemini, Grok, OpenCode, Pi, ACPX) ship bundled "skills" — opinionated Markdown prompt bundles materialized into the agent's runtime > - One of those bundled skills, `paperclip-dev`, existed to let agents develop Paperclip itself; it has now moved to its own external repo and no longer belongs in the core tree > - The adapter skill model also carried a `required` / `requiredReason` attribute plus a `paperclip_required` `AdapterSkillOrigin` variant, all of which only existed to mark bundled skills as non-optional in the UI and adapter sync logic > - With `paperclip-dev` gone, no bundled skill is "required" anymore, and the type / runtime surface for `required` is dead weight — but it is computed at request time and never persisted, so a clean removal is safe (no compatibility shim needed) > - This pull request deletes `skills/paperclip-dev/` and removes every trace of the `required` / `requiredReason` field and the `paperclip_required` origin across shared types, validators, adapter-utils, all eight local adapters, server routes, the company-skills service, the UI, the storybook fixtures, and the test suite > - The benefit is a smaller, simpler adapter-skill surface: one origin (`company_managed`) for managed bundled skills, `resolvePaperclipDesiredSkillNames` collapses to "just the configured desired set", and the AgentDetail skills tab no longer renders a "Required by Paperclip" section that no longer applies ## Linked Issues or Issue Description <!-- No existing public GitHub issue; describing the underlying work inline (feature_request template fields). --> **Summary** Remove the bundled `paperclip-dev` skill (now maintained in its own external repo) and retire the `required` / `requiredReason` skill attribute and the `paperclip_required` skill origin, which only existed to support it. **Problem or motivation** `paperclip-dev` is the only bundled skill that was ever marked "required". Now that it lives in a separate repository, shipping it inside the core tree is wrong, and the entire `required` surface (a type field, a validator field, a synthesized `paperclip_required` origin, UI "Required by Paperclip" section, and required-skill merging in the desired-skills calculation) becomes dead weight. The `required` value is computed at request time and never persisted, so it can be removed cleanly without a migration or compatibility shim. **Proposed solution** Delete `skills/paperclip-dev/`, drop the `required` / `requiredReason` fields and `paperclip_required` origin everywhere they are produced or consumed, collapse managed-skill origin to a single `company_managed` value, and simplify `resolvePaperclipDesiredSkillNames` to return only the configured desired set. **Alternatives considered** Keeping the `required` attribute as a no-op for forward compatibility — rejected because it is request-time only (nothing persists it), so leaving it in place is pure dead surface area with no callers. **Roadmap alignment** Internal cleanup / dead-code removal that simplifies the adapter-skill surface; it does not introduce or duplicate any planned core feature in ROADMAP.md. ## What Changed - Deleted bundled `skills/paperclip-dev/` (moved to a separate repo). - Dropped `required`, `requiredReason`, and the `paperclip_required` origin from `packages/shared/src/types/adapter-skills.ts`, `packages/shared/src/validators/adapter-skills.ts`, and `packages/adapter-utils/src/types.ts`. - In `packages/adapter-utils/src/server-utils.ts`: removed `readSkillRequired()`; dropped `required`/`requiredReason` from `listPaperclipSkillEntries()`, `normalizeConfiguredPaperclipRuntimeSkills()`, `buildPersistentSkillSnapshot()`, and `PaperclipSkillEntry`; collapsed `buildManagedSkillOrigin()` to always return `company_managed`; simplified `resolvePaperclipDesiredSkillNames()` to return only the configured desired set (signature preserved so adapter call sites are untouched). - Walked all eight local adapters (`acpx-local`, `claude-local`, `codex-local`, `cursor-local`, `gemini-local`, `grok-local`, `opencode-local`, `pi-local`) and removed every remaining `requiredReason` / `paperclip_required` reference. - `server/src/services/company-skills.ts`: dropped the `required = sourceKind === "paperclip_bundled"` synthesis when listing runtime skill entries. - `server/src/routes/agents.ts`: removed required-skill merging from the desired-skills calculation in the persist-config path and the unsupported-snapshot path (keeping the current version-aware `desiredSkillEntries` structure). - `ui/src/pages/AgentDetail.tsx`: dropped required-based filters, the required tooltip, and the entire "Required by Paperclip" section from the agent skills tab; storybook fixtures in `ui/storybook/stories/acpx-local.stories.tsx` cleaned up to match. - Tests: deleted the `required: false` case in `paperclip-skill-utils.test.ts` and the "keeps required bundled skills installed" case in every `*-local-skill-sync.test.ts`; `acpx-local-execute.test.ts`, `cursor-local-execute.test.ts`, `cursor-local-skill-sync.test.ts`, `agent-skills-routes.test.ts`, and `packages/adapter-utils/src/server-utils.test.ts` were updated to drop removed fields and map `origin: "paperclip_required"` → `"company_managed"`. - `server/src/adapters/registry.ts`: two `as unknown as ServerAdapterModule["..."]` casts on `hermesListSkills` / `hermesSyncSkills` (matching the existing `executeHermesLocal` pattern). `hermes-paperclip-adapter@0.2.0` still depends on the published `@paperclipai/adapter-utils` which keeps the retired `paperclip_required` variant; the cast bridges the workspace-vs-published type mismatch at the registry seam and can drop once hermes upgrades. ## Verification Run from the workspace root: ```sh grep -rn "skills/paperclip-dev" . grep -rn "paperclip_required" --include="*.ts" --include="*.tsx" . grep -rn "requiredReason" --include="*.ts" --include="*.tsx" . pnpm -w typecheck pnpm --filter @paperclipai/server exec vitest run paperclip-skill-utils pnpm --filter @paperclipai/server exec vitest run skill-sync ``` The first three greps return only the explanatory comment in `server/src/adapters/registry.ts` (no live `paperclip_required` / `requiredReason` usage) and zero `skills/paperclip-dev` source hits. Locally: - `pnpm -w typecheck` → all packages this PR touches pass (adapter-utils, shared, server, ui, cli, and the cursor/gemini/opencode/pi adapters). - Affected vitest suites pass: `paperclip-skill-utils`, `server-utils`, all eight `*-local-skill-sync`, `agent-skills-routes`, and the `acpx`/`cursor`/`pi` execute suites. ## Risks - Behavioral shift in the agent skills UI: the "Required by Paperclip" section disappears. No bundled skill is required anymore, so this only affects environments that previously surfaced `paperclip-dev` as a forced-on row; those installs will see the skill move into the regular "company-managed" list (and be uninstalled on next sync unless explicitly listed as desired). - Existing agents may still have the string `"paperclip-dev"` in their persisted `desiredSkills`. That entry is inert (no source for it to install from); a one-time DB cleanup is out of scope. Low risk. - Hermes adapter type bridge: two casts in `registry.ts` paper over a type-only divergence between the workspace `@paperclipai/adapter-utils` and the published version still pinned by `hermes-paperclip-adapter@0.2.0`. Runtime behavior is unaffected because the retired `paperclip_required` value is no longer produced by anything in this tree. The casts can be removed once hermes upgrades its dependency. ## Model Used - Provider: Anthropic - Model: Claude Opus 4.7 (`claude-opus-4-7`) - Capability: agent tool use via Paperclip's `claude_local` adapter ## 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 not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [ ] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [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>	2026-06-20 21:58:44 -07:00
Nicky Leach	364f0f5a8d	fix(server): enforce issue read for issue thread lists (#8331) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Agents coordinate through issue threads, so issue comments and interactions are part of the task authorization surface. > - Low-trust and boundary-limited agents can receive narrow mention-scoped access, but that must not turn into broad same-company issue-thread reads. > - The comment creation path was narrowed to allow explicit mention replies without granting mutation access. > - The surrounding list/read routes still needed to enforce the same `issue:read` boundary before returning thread data. > - This pull request applies the issue read check to issue comment and interaction listing routes, and locks that behavior with server regressions. > - The benefit is that narrow cross-agent collaboration remains possible without exposing unrelated issue-thread history. ## Linked Issues or Issue Description Bug fix: - What happened: same-company agents outside an issue read boundary could still hit issue-thread listing routes and receive thread data. - Expected behavior: issue comments and issue-thread interactions should only be listed after the actor is allowed to read the issue. - Steps to reproduce: configure a peer agent denied by the issue read boundary, then request `GET /api/issues/:id/comments` or the issue interaction listing route. - Paperclip version/commit: current `master` before this branch. - Deployment mode: applies to server authorization in all modes. Related public context: #7389, #7863, #8024. ## What Changed - Added issue read enforcement before listing issue comments. - Added issue read enforcement before listing issue-thread interactions. - Added server regressions for denied peer-agent issue-thread access while preserving mention-scoped collaboration behavior. - Removed an avoidable per-mentioned-comment issue reload in mention-grant authorization by passing the already-loaded issue assignee through the helper. - Documented cross-agent issue read/comment authorization behavior in the Paperclip API reference. - Added a resilient fallback for pinned external skills when GitHub tree fetches are temporarily unavailable during catalog builds. ## Verification - `pnpm vitest run server/src/__tests__/issue-agent-mutation-ownership-routes.test.ts server/src/__tests__/authorization-service.test.ts` - 2 test files passed - 84 tests passed - Existing mocked recovery revalidation warnings were emitted by the route suite and the command exited 0 - Greptile: 5/5 on commit `b73fc323f192dc44f88374c16865008d4348923b`; no unresolved review threads. - `pnpm vitest run packages/skills-catalog/src/catalog-builder.test.ts` - 1 test file passed - 6 tests passed - CI: all visible PR checks are terminal green on commit `b73fc323f192dc44f88374c16865008d4348923b`. ## Risks Low risk. This tightens read authorization on issue-thread listing routes; any caller that depended on same-company access without `issue:read` will now receive 403 and must use an explicit grant or valid issue read path. ## Model Used OpenAI GPT-5 Codex, Codex coding agent environment, tool use and local command execution enabled, reasoning mode active. Context window 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 not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [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 - [x] All Paperclip CI gates are green - [x] 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>	2026-06-19 15:16:17 -07:00
scotttong	6f9801a46b	feat(ui): NUX rework behind enableConferenceRoomChat experimental flag — capsule onboarding, conference-room chat, unified composer (#8000) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The first-run experience (onboarding wizard) and the chat surfaces (conference-room/board chat, task threads, composers) are the product's front door — they decide whether a new operator understands "hire agents, give them work, review results" in the first five minutes > - Today those surfaces feel ticket-y and form-like: the wizard is a static multi-step form that ends in an anticlimactic "Launch" screen, the task composer and board chat behave differently from each other, and agent-feed issue quicklooks misbehave (multiple flyouts open at once, cards jump on hover) > - We wanted to iterate toward a conversational, team-centric NUX — but without risking the workflows of everyone already running Paperclip > - This PR reworks the NUX behind a new default-OFF `enableConferenceRoomChat` experimental flag: a capsule-motif onboarding wizard that builds your team as you answer, a conference-room chat surface, one shared ChatComposer across surfaces, brand-accurate status chips, and feed-quicklook fixes — with the pre-existing UI fork-and-frozen as `*Classic` components that flag-OFF users keep > - The benefit is a complete, testable modern NUX that anyone can opt into from Settings → Experimental, with zero default behavior change and a clean path to either graduate or drop the experiment ## Linked Issues or Issue Description No pre-existing GitHub issue — feature description per `feature_request.yml`: - **Problem / motivation:** Paperclip's onboarding wizard and chat surfaces grew up as separate ticket-centric forms. New users get a form-filling experience rather than the feeling of standing up a team; the board chat and task threads use different composers with different affordances; the agent feed's issue quicklook can stack multiple popovers and shifts cards on hover. - **Proposed solution:** A coherent NUX experiment behind one experimental flag (`enableConferenceRoomChat`, Settings → Experimental, default OFF): capsule onboarding wizard with an evolving team capsule, conference-room chat, unified `ChatComposer`, team-centric copy, brand status chips, quicklook single-flight fix. Flag-OFF users get the exact pre-experiment UI via frozen `*Classic` forks, verified by an on/off parity test matrix. - **Alternatives considered:** (a) incremental unflagged restyling — rejected: the changes interlock across surfaces and would drip risk into every release; (b) a separate app shell / route for the new NUX — rejected: too much divergence, the flag + classic-fork pattern keeps the diff reviewable and reversible. - **Roadmap alignment:** `ROADMAP.md` lists **CEO Chat** ("a lighter-weight way to talk to leadership agents... should still resolve to real work objects"). This experiment is groundwork in that direction (conference-room chat resolves to issues/tasks via the same composer used in task threads) and does not change the core task-and-comments model. Related PRs found in the dedup search (same area, none duplicate this work — they target the classic wizard, which this PR intentionally leaves intact and mergeable): - #5385 — Coach-driven onboarding: conversational entry + agent-companies package import - #5378 — Onboarding wizard: reusable adapter picker + probe card - #6636 — ui(onboarding): friendly error surface + retry for the wizard - #7005 — fix(onboarding): explicitly await first-task wake - #2616 — fix: restore workspace directory config in onboarding wizard ## What Changed - **Experimental flag plumbing** — `enableConferenceRoomChat` in shared types/validators, server instance-settings service + API, Settings → Experimental card with explicit enable/disable copy - **Onboarding wizard** — classic wizard forked and frozen (`OnboardingWizardClassic`); flag-ON variant is a 5-step capsule wizard with a persistent evolving `AgentCapsule` (gradient/glow motif), team-centric reframed copy, and a typing-dots intro (hardened with fake-timer tests) - **Conference-room chat** — flag-ON board-chat surface with agent bubble name/icon headers and copy/vote/timestamp action rows (`AgentBubbleActionRow`) - **Unified composer** — shared `ChatComposer` adopted across surfaces; translucent surface + scroll-mask removal; "Agent mode"/"Plan mode" relabels; no-assignee confirmation `AlertDialog` (new `ui/alert-dialog.tsx` primitive); `@task` reference picker + linkification in mentions - **Agent feed** — single-flight issue-quicklook store (one popover at a time), flyouts open to the left, removed hover translate-y jitter - **Status chips** — brand-accurate task status chips behind the flag (light/dark, 1px borders per paperclip.ing/brand) - **Tests** — flag on/off parity matrix across IssueDetail, NewIssueDialog, Sidebar, wizard, gate components; component tests for all new pieces - **Merge with `master`** — one conflict in `ui/src/components/IssueChatThread.tsx`, resolved by keeping master's new `AssigneeChip`/`HandoffWakeRow`/`RunStatusBadge` components inside the flag-gated metadata-row chrome (details in commit `21a5642a`); post-merge fixes: vitest 4 mock typing in `MarkdownEditor.test.tsx`, flag hook made safe for provider-less mounts (master's new isolated component tests) - **Branch hygiene** — internal design wireframes/mockups stripped before the PR (they live in the Paperclip issue threads) - No user-facing documentation changes required: the flag is intentionally experimental and self-described in the Settings card; no existing docs reference the affected surfaces ## Verification - `pnpm run typecheck` — green across the workspace (ui, server, shared, plugins) - Full UI suite (`vitest run` in `ui/`, clean worktree at this HEAD): **1593/1595 passing, 223/224 files** — the 2 remaining failures are in `src/components/artifacts/ArtifactCard.test.tsx` and **fail identically on pristine `origin/master`** (pre-existing upstream, unrelated to this branch) - Full server suite (`vitest run` in `server/`, same clean worktree): results in PR checks; flag plumbing covered by instance-settings tests - Targeted post-merge resolution check: `IssueChatThread`, `IssueChatThreadSystemNotice`, `IssueDetail`, `Sidebar`, `ConferenceRoomChatGate`, `OnboardingWizardVariant`, `NewIssueDialog`, `InstanceExperimentalSettings`, `MarkdownEditor` — 172/172 passing - Manual walkthrough: flag OFF (default) → onboarding wizard, task thread, board chat, composer all render the classic UI; flag ON via Settings → Experimental → capsule wizard, conference-room chat, unified composer, status chips active - Screenshots: see below **Flag on/off screenshots** (committed on this branch under `screenshots/PR-8000-*`): | Surface | Flag OFF (classic, default) | Flag ON (experimental) | | --- | --- | --- | | Settings → Experimental |  |  | | Task thread |  |  | | Home / nav |  |  | | Conference Room (flag-ON only surface) | — |  | Capsule onboarding wizard walkthrough screenshots (flag ON) are attached to the Paperclip design/implementation threads; the wizard requires a fresh instance so it is captured via the e2e harness (`tests/e2e/nux-phase4-screenshots.spec.ts`). ## Risks - **Large surface, but gated:** all new behavior sits behind `enableConferenceRoomChat`, default OFF; flag-OFF rendering is locked by frozen `*Classic` forks plus an on/off parity test suite - **Classic forks are frozen at the fork point (`e3aada1d`):** master features added to the live thread component after that point (assignee handoff chips, run status badge, composer mention coach) render in the flag-ON path; the flag-OFF task thread keeps the fork-point behavior until the experiment graduates (forks deleted) or is dropped (forks restored as canonical). Called out for reviewer attention. - **Merge-conflict resolution in `IssueChatThread.tsx`** (commit `21a5642a`) deserves reviewer eyes: master's new handoff/run-status components were kept; the base toast-style no-assignee flow remains replaced by the AlertDialog flow introduced on this branch - Schema/server changes are additive (one optional boolean instance setting); no migrations of existing data ## Model Used - Claude (Anthropic) via Claude Code running in the Paperclip agent harness (agent: ClaudeCoder) - Branch implemented across multiple agent sessions on Claude Opus-class models with extended thinking + tool use (file edits, shell, Playwright screenshots); merge/PR session model ID as reported by the harness: `claude-fable-5` (Claude Code CLI) - All code was agent-authored and board-reviewed through Paperclip issue threads (plans, wireframes, confirmations) before merging ## 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 (none required — experimental flag, self-documenting Settings card; noted above) - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green (run 3 on `8af3041a`: all 16 gates SUCCESS, incl. e2e and all 4 serialized-suite shards) - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups (re-review verdict: Confidence 5/5, “Safe to merge”; all 4 round-1 findings fixed + confirmed resolved; both summary notes addressed in `8af3041a`) - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>	2026-06-11 16:32:55 -05:00
Dotta	468edd8b22	Add workspace file viewer and artifact links (#7681) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Agent work is issue-centered, and reviewers often need to inspect files, artifacts, and path references produced during that work. > - Before this branch, workspace-relative paths and artifact file references were not first-class inspectable objects in the board UI. > - Safe file viewing needs shared resource contracts, server-side workspace boundary checks, and UI that opens files without exposing arbitrary host paths. > - The workspace file viewer branch needed to stay as one active PR and be rebased onto current `paperclipai/paperclip:master` for review. > - This pull request adds the workspace file resource API, issue-page file viewer and browser, markdown file-reference links, and artifact file chips. > - The benefit is that board users can inspect relevant files from issue context while preserving workspace boundaries and auditability. ## Linked Issues or Issue Description No public GitHub issue exists for this branch. Internal Paperclip issues: `PAP-1953`, `PAP-10539`, `PAP-10733`. Problem / motivation: - Board users need to open workspace-relative files mentioned by agents or attached as work-product metadata without switching to a terminal. - The UI needs to support both direct file-path opening and workspace browsing/searching from an issue page. - The server must enforce company access, workspace boundaries, size limits, rate limits, and safe audit logging. Related PR: - Prior closed attempt: #4442 - Single active PR for this branch: #7681 ## What Changed - Added shared workspace file resource types, validators, and workspace-file `resourceRef` metadata validation for work products. - Added server routes/services for resolving, listing, and previewing workspace-relative files with access checks, scan caps, list-specific limits, and audit logging. - Added the issue file viewer provider, sheet, workspace browser, command-palette action, markdown workspace-file autolinks, and artifact file chips. - Updated issue workspace UI and stories/tests for file browsing and workspace file opening. - Rebased the branch onto current `paperclipai/paperclip:master` and updated the existing single PR branch. - Addressed current-head Greptile follow-ups by applying `offset` consistently across search/recent/changed file listings, restoring stopped-service port ownership checks before auto-port reuse, and stabilizing the workspace browser pagination test. ## Verification Current local verification after rebase to `public/master`: - `pnpm exec vitest run packages/shared/src/work-product.test.ts server/src/__tests__/file-resources.test.ts server/src/__tests__/instance-settings-routes.test.ts server/src/__tests__/instance-settings-service.test.ts server/src/__tests__/workspace-runtime.test.ts ui/src/components/FileViewerSheet.test.tsx ui/src/components/FileViewerSheet.copy.test.tsx ui/src/components/WorkspaceFileBrowser.test.tsx ui/src/components/WorkspaceFileMarkdownBody.test.tsx ui/src/context/FileViewerContext.test.ts ui/src/lib/remark-workspace-file-refs.test.ts ui/src/lib/workspace-file-parser.test.ts ui/src/components/IssueWorkspaceCard.test.tsx` - 13 files passed, 197 tests passed. - `pnpm -r --filter @paperclipai/shared --filter @paperclipai/server --filter @paperclipai/ui typecheck` - passed. - `pnpm exec vitest run ui/src/components/WorkspaceFileBrowser.test.tsx` - 1 file passed, 25 tests passed. - `pnpm exec vitest run server/src/__tests__/file-resources.test.ts server/src/__tests__/workspace-runtime.test.ts` - 2 files passed, 90 tests passed. - `pnpm -r --filter @paperclipai/server typecheck` - passed. - Confirmed branch is `0` behind and `46` ahead of current `public/master` after rebase and follow-up commits. - Confirmed the PR diff does not include `pnpm-lock.yaml`. - Confirmed the PR diff does not include `.github/workflows` changes. - Searched GitHub for duplicate or related workspace file viewer PRs/issues; #4442 is the prior closed attempt and this PR is the single active PR for the branch. - No screenshots were committed; the task explicitly asked not to add design screenshots or images unless they were part of the work. Current remote verification on head `a698a7bc10137baf7d25bd5722e1d6e0343387c1`: - Greptile Review - success, 64 files reviewed, 0 comments added, no unresolved Greptile review threads. - PR workflow `verify` - success. - Typecheck + Release Registry, General tests, workspace test shards, serialized server suites, Build, Canary Dry Run, e2e, Socket, and Snyk - success. - `security-review` - neutral, with output saying a draft advisory was filed for maintainer review and is not a merge block. - `commitperclip PR Review / review` - cancelled after the security gate detected flags and timed out while creating/reviewing the advisory. I reran it once and it cancelled the same way; no actionable code/test failure was exposed in the job logs. ## Risks - This is a broad UI/server feature PR, so review needs to pay attention to route authorization, workspace boundary handling, and markdown autolink false positives. - Workspace browsing intentionally caps list results and scan depth; very large workspaces may require users to refine search terms. - Remote workspace preview remains unavailable until remote file-access support is implemented. - The neutral commitperclip security-review advisory needs maintainer review, but the check output says it is not a merge block. > 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, GPT-5 coding agent in a Paperclip/Codex local tool-use environment, medium reasoning, with shell/GitHub CLI tool use for branch inspection, verification, rebase, PR update, Greptile review, and CI inspection. ## 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 - [ ] 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 - [x] 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> Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>	2026-06-09 17:17:43 -05:00
Dotta	e50666e4c8	[codex] Move maintainer task skills under .agents (#7658) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The skills layout separates runtime Paperclip skills in `skills/` from maintainer/agent workflow skills in `.agents/skills/`. > - Three maintainer workflow skills still lived under root `skills/`, making them look like runtime skills shipped through the Paperclip skill path. > - Root `skills/` is documented as reserved for Paperclip runtime skills, so these task-oriented maintainer skills belong with the other `.agents/skills` entries. > - This pull request moves the three requested skill packages, updates the direct smoke path, and adds regression coverage for the maintainer-only skill boundary. > - The benefit is a cleaner skills boundary without changing skill contents or runtime behavior. ## Linked Issues or Issue Description Internal Paperclip issue: PAP-10471. No public GitHub issue exists for this repository-maintenance change. Inline feature/enhancement issue description follows the feature request template fields: ### Problem or motivation Root `skills/` is documented as reserved for Paperclip runtime skills, but `terminal-bench-loop`, `paperclip-create-plugin`, and `diagnose-why-work-stopped` lived there even though they are maintainer/agent workflow skills. ### Proposed solution Move those three skill packages to `.agents/skills/`, update the terminal-bench loop smoke script to read the new local path, and cover the moved skill names in the existing runtime-skill discovery test fixture. ### Alternatives considered Leaving the skills in root `skills/` would preserve direct old paths, but it keeps blurring the runtime-skill boundary. Moving them into the app-shipped skills catalog would be the wrong fit because these are maintainer workflow skills, not bundled company skills. ### Roadmap alignment This is a small maintenance cleanup around the existing Skills Manager/workflow-skill organization and does not introduce a roadmap-level core feature. ## What Changed - Moved `terminal-bench-loop`, `paperclip-create-plugin`, and `diagnose-why-work-stopped` into `.agents/skills/`. - Updated the terminal-bench loop smoke script and skill self-check text to use `.agents/skills/terminal-bench-loop/SKILL.md`. - Added regression coverage in `server/src/__tests__/paperclip-skill-utils.test.ts` that places these three skills under `.agents/skills` while asserting runtime discovery still lists only root runtime skills. ## Verification - `pnpm smoke:terminal-bench-loop-skill --source-issue-id "$PAPERCLIP_TASK_ID" --run-key PAP-10471-move-skill-path` - `pnpm exec vitest run server/src/__tests__/paperclip-skill-utils.test.ts` - `rg -n "skills/(terminal-bench-loop|paperclip-create-plugin|diagnose-why-work-stopped)" . --glob '!node_modules' --glob '!dist' --glob '!ui/dist'` returned no matches. ## Risks - Low risk: this is a file-location change plus direct path/test updates. - Maintainer agents that referenced the old root paths directly will need to use `.agents/skills/...` instead. > 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, GPT-5 coding agent with shell/tool use. ## 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	2026-06-06 10:47:59 -05:00
Dotta	2e74d32871	PAP-10430: split Issue-to-Task copy migration (#7651) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The board UI is the operator surface where users create, assign, monitor, and review work items. > - The product language is moving toward "tasks" for user-facing work items while the internal API and database still use "issues". > - PR #7543 bundled this copy migration with broader information-architecture work, which made the branch too large for Greptile review. > - This pull request peels the Issue-to-Task copy migration into a smaller, independently reviewable change. > - The benefit is clearer user-facing terminology, less agent confusion via the Paperclip skill note, and a smaller PR that Greptile can review. ## Linked Issues or Issue Description Refs #7645 Refs #7543 Refs PAP-10430 This PR was split out of #7543 so the Issue-to-Task copy migration can be reviewed separately and the remaining IA PR can fall under Greptile's file limit. ## What Changed - Preserves Scott Tong's original `PAP-57` copy-only commit, with author and co-author credit intact, to rename user-facing "Issues" copy to "Tasks" across the UI while keeping routes/API/internal symbols as `issue`. - Updates onboarding and release-smoke browser selectors from `Create & Open Issue` to `Create & Open Task`. - Adds a terminology note to `skills/paperclip/SKILL.md` clarifying that task and issue refer to the same Paperclip work item. - Resolves the only cherry-pick conflict by keeping current search artifacts support and changing visible search copy to "tasks". ## Verification - `pnpm --filter @paperclipai/ui build` passed. - `NODE_ENV=test pnpm exec vitest run ui/src/components/IssuesList.test.tsx ui/src/components/Sidebar.test.tsx ui/src/components/NewIssueDialog.test.tsx ui/src/pages/IssueDetail.test.tsx` passed: 4 files, 66 tests. - `git diff --check origin/master...HEAD` passed. - Diff is 80 files, below Greptile's 100-file limit. - Before/after UI copy examples: "Issues" -> "Tasks", "New Issue" -> "New Task", "Create & Open Issue" -> "Create & Open Task". ## Risks - Medium copy-risk: this intentionally changes user-facing terminology broadly while keeping internal issue identifiers and routes unchanged. - Some docs and APIs still say `issue`; the skill note clarifies this so agents do not treat task and issue as separate entities. - Browser-level visual validation is expected from CI because this local container is missing usable browser dependencies. > 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 Scott Tong authored the original `PAP-57` copy migration, assisted by Claude Opus 4.8 and Paperclip agents per the preserved commit metadata. Codex / GPT-5-class coding agent with shell, GitHub CLI, and repository access performed the PR split, conflict resolution, skill note, and verification. ## 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 - [x] All Paperclip CI gates are green - [x] 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: scotttong <scott.tong@gmail.com> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com> Co-authored-by: Paperclip <noreply@paperclip.ing>	2026-06-06 10:10:01 -05:00
Dotta	4d5322c821	[codex] Add checkbox confirmation issue interactions (#7649) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Agent work is coordinated through issues, comments, interactions, and approval-style handoffs. > - Existing issue-thread interactions could ask questions, suggest tasks, and request confirmation, but they did not support a structured checkbox confirmation payload for choosing one or more options. > - That gap made board/user confirmations harder to validate consistently across API callers, plugin helpers, CLI tooling, and the UI. > - This pull request adds the shared checkbox confirmation contract, server handling, client helpers, and issue-thread UI needed to render and submit structured selections. > - The benefit is that agents can request bounded multi-select confirmations in the same audited issue-thread flow as other Paperclip interactions. ## Linked Issues or Issue Description - No public GitHub issue found for this exact branch. Internal Paperclip issue: PAP-10415 / PAP-10441 requested creating this PR for the checkbox confirmation issue-thread UI component work. - GitHub duplicate search performed for checkbox confirmation / issue-thread interaction PRs; no matching open PR was found. - Related issue search result `#7497` was unrelated company file cleanup work, so it is not linked as a related issue. ## What Changed - Added shared types, validators, constants, and tests for `request_checkbox_confirmation` interactions. - Extended server issue-thread interaction service and routes for checkbox confirmation creation, validation, expiration, and response handling. - Added CLI, MCP, and plugin SDK helper coverage so external callers can create the new interaction shape consistently. - Updated the issue-thread interaction UI to render checkbox confirmations with min/max bounds, selection summaries, stale-target states, and accept/decline flows. - Documented the checkbox confirmation interaction contract in the Paperclip skill/API reference. ## Verification - Rebased cleanly on `paperclipai/paperclip` `master` fetched into `public-gh/master` at `a4fa0eaf5`. - Confirmed the PR diff does not include `pnpm-lock.yaml` or `.github/workflows` changes. - Ran focused tests with `NODE_ENV=test`: ```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 cli/src/__tests__/project-goal.test.ts packages/mcp-server/src/tools.test.ts packages/plugins/sdk/tests/testing-actions.test.ts ``` Result: 8 test files passed, 78 tests passed. - CI on latest head `63b9e55` is green. - Greptile Review passed on latest head; GraphQL review-thread check shows all Greptile threads resolved. ## Risks - Medium surface area because the interaction contract touches shared validators, server routes/services, UI rendering, CLI, MCP, plugin SDK helpers, and docs. - No database migrations are included. - `pnpm-lock.yaml` is intentionally excluded per repository lockfile policy. - UI screenshots are not attached because the task explicitly requested not to add design screenshots or images unless they were part of the work; component tests cover the new rendering and interaction states. > 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 repository file access, shell command execution, git/GitHub CLI tooling, and Paperclip control-plane API access. Exact hosted model ID/context-window metadata is not exposed inside this 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 - [ ] 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 - [x] All Paperclip CI gates are green - [x] 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>	2026-06-06 08:48:43 -05:00
Dotta	e080e4686a	Move artifact upload details to skill reference ... Co-Authored-By: Paperclip <noreply@paperclip.ing>	2026-05-31 18:18:48 +00:00
Dotta	c4bb68c14b	Bundle artifact upload helper with Paperclip skill ... Co-Authored-By: Paperclip <noreply@paperclip.ing>	2026-05-31 18:17:01 +00:00
Dotta	e7cdd0f8c5	Move artifact upload guidance into Paperclip skill ... Co-Authored-By: Paperclip <noreply@paperclip.ing>	2026-05-31 17:41:14 +00:00
Dotta	9eac727cf1	[codex] Add skills CLI and catalog management (#6782) ... ## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies through company-scoped control-plane workflows. > - Agents need reusable, inspectable skills that can be installed, reset, audited, exported, and assigned without bespoke local setup. > - The existing skill truth model needed cleanup so bundled skills, optional catalog skills, runtime skills, and adapter-provided skills have clear provenance. > - Operators also need a practical CLI and board UI for discovering and managing company skills. > - This pull request adds the skills CLI, packaged skills catalog, company skills APIs, and catalog-aware board UI. > - The benefit is a more reusable Paperclip company setup where skills are portable, auditable, and easier for operators and agents to manage. ## What Changed - Added `paperclipai skills` CLI commands and coverage for catalog listing, installing, resetting, and inspecting company skills. - Added a packaged `@paperclipai/skills-catalog` workspace with bundled and optional skill content plus validation/build tests. - Added shared company-skill types and validators used across CLI, server, and UI contracts. - Added server catalog APIs/services for company skill catalog operations, reset semantics, audit behavior, and portability provenance. - Updated adapter skill handling so runtime/catalog provenance remains explicit across local adapters. - Added board UI support for browsing and managing catalog-backed company skills. - Updated docs for the skills CLI/catalog flow and the company skills Paperclip skill reference. - Rebased the branch onto current `paperclipai/paperclip:master`; no `pnpm-lock.yaml`, `.github/workflows`, or migration files are included in the final PR diff. ## Verification - Passed: `pnpm run preflight:workspace-links && pnpm exec vitest run cli/src/__tests__/skills.test.ts packages/skills-catalog/src/catalog-builder.test.ts packages/skills-catalog/src/shipped-catalog.test.ts packages/shared/src/validators/company-skill.test.ts packages/adapter-utils/src/server-utils.test.ts packages/plugins/create-paperclip-plugin/src/entrypoints.test.ts server/src/__tests__/company-skills-catalog-service.test.ts server/src/__tests__/company-skills-routes.test.ts server/src/__tests__/company-portability.test.ts`. - Passed: `pnpm exec vitest run server/src/__tests__/workspace-runtime.test.ts -t "default branch|origin/master|symbolic-ref"`. - Attempted: full `server/src/__tests__/workspace-runtime.test.ts`. Four provisioning tests failed while seeding an isolated worktree database from the local Paperclip instance because the local plugin schema dump contains a duplicate-column foreign key (`plugin_content_machine_18a7bc327b.content_case_signals`). The default-branch tests touched by the rebase conflict passed in the focused run above. - Checked final diff: no `pnpm-lock.yaml`, no `.github/workflows`, and no migration-file changes relative to `master`. ## Risks - Medium: this is a broad skills/catalog change touching CLI, server APIs, shared contracts, adapter skill sync, and UI. - Catalog validation and reset semantics need careful reviewer attention because they affect reusable company setup and portability. - No database migrations are included in this PR, so there is no migration ordering/idempotency risk in the final diff. - No lockfile is included by design; dependency resolution will be handled by the repository lockfile workflow. ## Model Used - OpenAI Codex coding agent based on GPT-5, running in Paperclip via the `codex_local` adapter with shell, git, GitHub CLI, and code-editing tool access. Exact hosted model build/context-window metadata is not exposed in this 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 run targeted tests locally and documented the local workspace-runtime seed failure above - [x] I have added or updated tests where applicable - [x] If this change affects the UI, screenshots were intentionally omitted per PAP-10124 instructions; UI behavior is covered by tests and reviewer inspection - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>	2026-05-28 07:33:51 -10:00
Dotta	b947a7d76c	[codex] Improve local plugin development workflow (#5821) ... ## Thinking Path > - Paperclip is the control plane for autonomous AI-agent companies. > - Plugins are the extension point for adding capabilities without expanding the core product surface. > - Local plugin development needed a tighter CLI-first loop so plugin authors can scaffold, run, install, inspect, and reload plugins without reaching into internal package paths. > - The server plugin install path also needed local-path handling that keeps plugin identity, dashboard routes, and development watchers coherent. > - This pull request adds the CLI scaffold/install workflow, fixes the server and SDK edge cases that blocked that loop, and updates the agent-facing plugin creation skill and docs. > - The benefit is that contributors can develop plugins from local folders with a documented, repeatable happy path. ## What Changed - Added `paperclipai plugin init` coverage and CLI wiring for local plugin scaffolding. - Improved local plugin install handling, plugin key route resolution, dashboard capability behavior, and dev watcher startup/reload behavior. - Fixed plugin SDK worker entrypoint validation for symlinked package layouts. - Added targeted tests for plugin init, server plugin authz/watcher behavior, SDK worker host validation, and the authoring smoke example. - Added a short local plugin development guide and refreshed the plugin authoring guide plus `paperclip-create-plugin` skill instructions. ## Verification - `pnpm run preflight:workspace-links && pnpm --filter @paperclipai/plugin-sdk build && pnpm --filter @paperclipai/create-paperclip-plugin typecheck && pnpm --filter paperclipai typecheck && pnpm --filter @paperclipai/plugin-sdk typecheck && pnpm --filter @paperclipai/server typecheck` - `pnpm exec vitest run --project paperclipai cli/src/__tests__/plugin-init.test.ts` - `pnpm exec vitest run --project @paperclipai/plugin-sdk packages/plugins/sdk/tests/worker-rpc-host.test.ts` - `pnpm exec vitest run --project @paperclipai/server server/src/__tests__/plugin-dev-watcher.test.ts --pool=forks --poolOptions.forks.isolate=true` - `pnpm exec vitest run --project @paperclipai/server server/src/__tests__/plugin-routes-authz.test.ts --pool=forks --poolOptions.forks.isolate=true` - `pnpm --dir packages/plugins/examples/plugin-authoring-smoke-example test` - Confirmed `pnpm-lock.yaml` is not included in the PR diff. ## Risks - Medium risk: this touches plugin install routing, CLI command behavior, and the local development watcher. - Local path plugin installs execute trusted local code by design; the new docs call out that trust boundary. - No database migrations are included. > 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, GPT-5 coding agent, tool-enabled local shell and git workflow, medium reasoning effort. Context window details were not exposed in this 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 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 - [x] I will address all Greptile and reviewer comments before requesting merge UI screenshots: not applicable; this PR changes CLI/server/plugin docs and tests, not board UI rendering. --------- Co-authored-by: Paperclip <noreply@paperclip.ing>	2026-05-12 17:38:24 -05:00
Dotta	68f69975a4	Harden control-plane safety and issue identifiers (#5292) ... ## Thinking Path > - Paperclip relies on issue identifiers, execution policies, and agent heartbeat rules to keep autonomous work auditable. > - Safety checks need to reject ambiguous agent handoffs, and identifier parsing needs to support Cloud tenant prefixes. > - Agent instructions also need to make final-disposition rules explicit so work does not stall in vague states. > - This pull request isolates backend correctness and governance hardening from the UI and recovery-system-notice branches. > - The benefit is safer in-review transitions, better identifier compatibility, and clearer agent operating contracts. ## What Changed - Fixed run-aware confirmation ordering and interrupted-run state cleanup. - Added Cloud tenant identity bootstrap and alphanumeric issue identifier support across shared parsing and server routes. - Guarded agent-authored `in_review` updates unless a real review path exists. - Tightened heartbeat disposition instructions in adapter utilities/default AGENTS/Paperclip skill. ## Verification - `pnpm install --frozen-lockfile` - `pnpm exec vitest run packages/shared/src/issue-references.test.ts server/src/__tests__/issue-identifier-routes.test.ts server/src/__tests__/issue-execution-policy-routes.test.ts packages/adapter-utils/src/server-utils.test.ts` initially had the first execution-policy test hit Vitest's 5s timeout under the parallel bundle while the rest passed. - `pnpm exec vitest run server/src/__tests__/issue-execution-policy-routes.test.ts --testTimeout=20000` passed with 10/10 tests. - Follow-up: `pnpm run typecheck:build-gaps` passed. - Follow-up: `pnpm --filter @paperclipai/ui typecheck` passed. - Follow-up: `pnpm vitest run server/src/__tests__/issue-comment-reopen-routes.test.ts server/src/__tests__/company-portability.test.ts server/src/__tests__/costs-service.test.ts` passed. - Follow-up: `pnpm vitest run ui/src/context/LiveUpdatesProvider.test.ts ui/src/lib/issue-chat-messages.test.ts ui/src/lib/issue-reference.test.ts ui/src/lib/issue-timeline-events.test.ts` passed. ## Risks - Medium control-plane risk: in-review update validation changes agent behavior. The error message is explicit and tests cover allowed review paths. ## Model Used - OpenAI GPT-5 Codex via Paperclip `codex_local` adapter, with shell/git/GitHub CLI tool use. ## 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 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 - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>	2026-05-06 07:49:47 -05:00
Dotta	685ee84e4a	[codex] Document terminal bench dispatch config (#4961) ... ## Thinking Path > - Paperclip agents rely on skills for repeatable operating procedures > - The Terminal-Bench loop skill needs to preserve enough dispatch configuration to reproduce real heartbeat behavior > - A bare benchmark command can create unassigned work with no heartbeat-enabled agent, which is a harness setup failure rather than product evidence > - The Paperclip heartbeat skill also needs to keep escalation biased toward agent-owned follow-through > - This pull request documents dispatch runner config requirements and strengthens the agent follow-through rule > - The benefit is fewer misleading benchmark loops and clearer agent operating guidance ## What Changed - Documented `PAPERCLIP_HARBOR_RUNNER_CONFIG` / runner dispatch config as required Terminal-Bench loop input. - Updated the Terminal-Bench loop smoke check to require the dispatch config mention. - Added stronger Paperclip skill guidance to avoid asking humans for work an agent can perform. ## Verification - `pnpm smoke:terminal-bench-loop-skill` ## Risks - Low risk: documentation and smoke expectation changes only. The stricter smoke assertion is intentional so future edits do not drop the dispatch config requirement. > 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, GPT-5 coding agent, tool use and local command execution. Exact context window was not exposed in 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 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 - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>	2026-05-01 12:00:47 -05:00
Dotta	1fe1067361	Polish board settings and skills workflow (#4863) ... ## Thinking Path > - Paperclip's board UI and bundled skills are the operator layer for configuring agents, routines, issue workflows, and local troubleshooting loops. > - The prior rollup mixed this operator polish with database backups, backend reliability, thread scale, and cost/workflow primitives. > - This pull request isolates the remaining board QoL, settings, issue-detail integration, adapter config cleanup, and skills smoke tooling. > - It includes some integration-level overlap with the thread and workflow slices so this branch can run from `origin/master` while still preserving the full original work. > - Preferred merge order is the narrower primitives first, then this integration PR last. > - The benefit is that reviewers can inspect the user-facing board/settings/skills layer separately from backend infrastructure changes. ## What Changed - Added board/settings polish for agents, routines, company settings, project workspace detail, and issue detail controls. - Added agent/routine UI regression tests and New Issue dialog coverage. - Integrated issue-detail activity/cost/interaction surfaces and leaf work pause/resume controls. - Cleaned bundled adapter UI config defaults and onboarding copy. - Added terminal-bench loop and work-stoppage diagnosis skills plus a smoke test script. - Updated attachment type handling and Paperclip skill/API guidance. ## Verification - `pnpm install --frozen-lockfile` - `pnpm exec vitest run ui/src/pages/Agents.test.tsx ui/src/pages/Routines.test.tsx ui/src/components/NewIssueDialog.test.tsx ui/src/pages/IssueDetail.test.tsx server/src/__tests__/costs-service.test.ts server/src/__tests__/issue-thread-interaction-routes.test.ts server/src/__tests__/issue-thread-interactions-service.test.ts` - Result: 7 test files passed, 54 tests passed. - `pnpm run smoke:terminal-bench-loop-skill` - Result: JSON output included `"ok": true` and `"cleanup": true`. - UI screenshots not included because verification is focused component/page coverage for the changed board surfaces. ## Risks - This is the integration-heavy PR in the split and intentionally overlaps some component/API primitives with the issue-thread and workflow PRs so it can run from `origin/master`. - Preferred merge order: #4859, #4860, #4861, #4862, then this PR last. If earlier branches merge first, this PR may need a straightforward conflict refresh in shared UI files. - The terminal-bench smoke script creates temporary mock issues and relies on cleanup; the verified run returned `cleanup: true`. > 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, GPT-5.5, code execution and GitHub CLI tool use, medium reasoning effort. ## 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 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 - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>	2026-04-30 15:28:11 -05:00
Dotta	d9f540c331	[codex] Refresh docs and agent skills (#4693) ... ## Thinking Path > - Paperclip orchestrates AI agents through a company-scoped control plane > - Contributors and agents need docs and skills that match the current V1 behavior > - The source branch included documentation updates alongside implementation work > - Keeping docs and skill guidance separate makes the implementation PR easier to review > - This pull request refreshes the V1 docs and agent-operating guidance without changing runtime behavior > - The benefit is current contributor guidance that can merge independently from code changes ## What Changed - Refreshed V1 product, goal, implementation, database, and development documentation. - Updated the Paperclip heartbeat skill guidance and create-agent skill references. - Added the Paperclip plan-to-task conversion skill. - Updated release changelog skill guidance. ## Verification - `git diff --check public-gh/master..HEAD` passed in the PR worktree after the Greptile fix. - Greptile Review passed on head `673317ed` with zero unresolved review threads. - GitHub PR checks passed on head `673317ed`: `policy`, `verify`, `e2e`, and `security/snyk (cryppadotta)`. ## Risks - Low runtime risk because this branch only changes docs and skill guidance. - Documentation may need follow-up wording adjustments if reviewers want a different framing for V1 behavior. > 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, GPT-5 coding agent, tool-enabled terminal/GitHub workflow. Exact runtime context window was not exposed by the harness. ## 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 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 - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>	2026-04-28 16:12:03 -05:00
Devin Foley	d2cbe2cb23	Prefer pushing feature branches to a user fork in paperclip-dev skill (#4572) ... ## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies > - The `paperclip-dev` skill is the canonical reference agents read before doing development work on the Paperclip repo itself > - Today the skill assumes feature branches get pushed to `origin` (= `paperclipai/paperclip`), which clutters the upstream branch list when contributors actually have personal forks > - This is the standard open-source contribution pattern (push to fork, PR upstream) and the skill should reflect it > - This pull request adds a "Forks — Prefer Pushing to a User Fork" section that teaches agents to detect a fork remote, push there, and only fall back to `origin` when no fork is configured > - The benefit is cleaner upstream branch hygiene and behavior that matches typical contributor workflows without any code/runtime change ## What Changed - Added a new **Forks — Prefer Pushing to a User Fork** section to `skills/paperclip-dev/SKILL.md` covering: - How to detect a user fork via `git remote -v` (treat any non-`paperclipai` GitHub remote as the fork) - How to push to the fork (`git push -u <fork-remote> HEAD`) - How to create the PR from the fork (`gh pr create --repo paperclipai/paperclip --head <fork-owner>:<branch>`) - The no-fork fallback (push to `origin`, do not auto-create a fork — ask first) - Keeping the fork's `master` in sync - Added a reinforcing entry to the **Common Mistakes** table linking back to the new section ## Verification - Docs-only change to a single markdown skill file. Reviewer can confirm by reading the diff in `skills/paperclip-dev/SKILL.md`: - New `## Forks — Prefer Pushing to a User Fork` section sits between `## Worktrees` and `## Pull Requests` - New row appended to the `## Common Mistakes` table - No tests, no build, no runtime behavior affected. ## Risks - Low risk. Documentation-only edit. The instructions are advisory — they only change agent behavior on future runs that read the skill. ## Model Used - Provider: Anthropic (Claude) - Model ID: `claude-opus-4-7` (Claude Opus 4) - Capabilities: tool use (file read/edit, shell, git, gh CLI), extended reasoning - Context: invoked via Claude Code / Paperclip heartbeat for issue PAPA-139 ## 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 run tests locally and they pass (N/A — docs-only change; no test surface) - [x] I have added or updated tests where applicable (N/A) - [x] If this change affects the UI, I have included before/after screenshots (N/A — no UI change) - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge	2026-04-26 22:19:07 -07:00
Devin Foley	d1484551ee	Add open-source hygiene note to paperclip-dev skill (#4541) ... ## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies. > - The `paperclip-dev` skill is part of the contributor and agent workflow layer that tells developers how to work in this repository safely. > - That skill already references the public upstream `origin`, but it did not explicitly say that pushes there must be treated as publishable open-source output. > - Without that reminder, contributors are more likely to leak secrets, PII, private logs, machine-local config, or noisy throwaway git history into the public repo. > - This pull request adds a prominent `OPEN SOURCE HYGIENE` callout near the top of the skill, before the git workflow guidance. > - The benefit is clearer safety guidance for contributors and less accidental disclosure or branch/commit noise on the upstream project. ## What Changed - Added an `OPEN SOURCE HYGIENE` callout near the top of `skills/paperclip-dev/SKILL.md`. - Explicitly warned that anything pushed to `origin` must be publishable. - Called out avoiding secrets, API keys, PII, private logs, machine-local config, and noisy throwaway branches or checkpoint commits. ## Verification - N/a ## Risks - Low risk. This is a docs-only change in a skill file; the main risk is wording tone or placement, not runtime behavior. ## Model Used - OpenAI Codex via the `codex_local` Paperclip adapter, GPT-5-based coding agent runtime. Exact backend serving model ID is not exposed in this heartbeat environment. Tool use, shell execution, and patch application were enabled. ## 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 - [ ] 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 - [x] I will address all Greptile and reviewer comments before requesting merge	2026-04-26 12:14:49 -07:00
Devin Foley	91333ec86f	feat: add paperclip-dev skill with optional bundled skill support (#3854) ... ## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies > - Agents working on the Paperclip codebase itself need guidance on dev workflows: server lifecycle, worktrees, builds, database ops, diagnostics > - There was no bundled skill covering these workflows — agents had to figure it out from scratch each time > - Additionally, not every skill should be force-installed on every agent — a dev-focused skill should be opt-in > - This PR adds a `paperclip-dev` skill with `required: false` frontmatter so it ships with Paperclip but isn't auto-installed > - The skill's PR section references canonical files (`.github/PULL_REQUEST_TEMPLATE.md`, `CONTRIBUTING.md`) instead of duplicating their content, with gated instructions that force agents to read those files before creating any PR > - The benefit is that developers (human or agent) can opt in to structured dev guidance without polluting the default agent skill set or creating drift between duplicated docs ## What Changed - Added `skills/paperclip-dev/SKILL.md` covering server management, worktree lifecycle, builds, database ops, diagnostics, agent operations, and common mistakes - The Pull Requests section uses gated, reference-based instructions — agents MUST read `.github/PULL_REQUEST_TEMPLATE.md` and `CONTRIBUTING.md` before running `gh pr create`, with a brief checklist of required section names (no content duplication) - Updated `packages/adapter-utils/src/server-utils.ts` to respect `required: false` frontmatter — optional skills are bundled but not auto-installed on agents - Added test in `server/src/__tests__/paperclip-skill-utils.test.ts` verifying that optional skills are excluded from the default install set ## Verification ```bash # Run tests pnpm test # Manual verification: create a fresh worktree without seeding npx paperclipai worktree:make test-optional-skill --no-seed cd ~/paperclip-test-optional-skill eval "$(npx paperclipai worktree env)" npx paperclipai run # Verify paperclip-dev appears in company skill library but is NOT auto-assigned # Call listPaperclipSkillEntries() — paperclip-dev should show required: false # Call resolvePaperclipDesiredSkillNames() — paperclip-dev should NOT be in the default set # Cleanup npx paperclipai worktree:cleanup test-optional-skill ``` ## Risks - Low risk. The `required` field defaults to `true` when absent, so all existing skills behave identically. Only the new `paperclip-dev` skill sets `required: false`. ## Model Used Claude Opus 4.6 (`claude-opus-4-6`) via Claude Code, with tool use and extended context. ## 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 run tests locally and they pass - [x] I have added or updated tests where applicable - [ ] 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 - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>	2026-04-26 11:06:13 -07:00
Dotta	641eb44949	[codex] Harden create-agent skill governance (#4422) ... ## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies > - Hiring agents is a governance-sensitive workflow because it grants roles, adapter config, skills, and execution capability > - The create-agent skill needs explicit templates and review guidance so hires are auditable and not over-permissioned > - Skill sync also needs to recognize bundled Paperclip skills consistently for Codex local agents > - This pull request expands create-agent role templates, adds a security-engineer template, and documents capability/secret-handling review requirements > - The benefit is safer, more repeatable agent creation with clearer approval payloads and less permission sprawl ## What Changed - Expanded `paperclip-create-agent` guidance for template selection, adjacent-template drafting, and role-specific review bars. - Added a Security Engineer agent template and collaboration/safety sections for Coder, QA, and UX Designer templates. - Hardened draft-review guidance around desired skills, external-system access, secrets, and confidential advisory handling. - Updated LLM agent-configuration guidance to point hiring workflows at the create-agent skill. - Added tests for bundled skill sync, create-agent skill injection, hire approval payloads, and LLM route guidance. ## Verification - `pnpm exec vitest run server/src/__tests__/agent-skills-routes.test.ts server/src/__tests__/codex-local-skill-injection.test.ts server/src/__tests__/codex-local-skill-sync.test.ts server/src/__tests__/llms-routes.test.ts server/src/__tests__/paperclip-skill-utils.test.ts --config server/vitest.config.ts` passed: 5 files, 23 tests. - `git diff --check public-gh/master..pap-2228-create-agent-governance -- . ':(exclude)ui/storybook-static'` passed. - Confirmed this PR does not include `pnpm-lock.yaml`. ## Risks - Low-to-medium risk: this primarily changes skills/docs and tests, but it affects future hiring guidance and approval expectations. - Reviewers should check whether the new Security Engineer template is too broad for default company installs. - No database migrations. > 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, git, Paperclip API, and GitHub CLI tool use in the local Paperclip workspace. ## 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 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 - [x] I will address all Greptile and reviewer comments before requesting merge Note: screenshot checklist item is not applicable; this PR changes skills, docs, and server tests. --------- Co-authored-by: Paperclip <noreply@paperclip.ing>	2026-04-24 14:15:28 -05:00
Dotta	a957394420	[codex] Add structured issue-thread interactions (#4244) ... ## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies. > - Operators supervise that work through issues, comments, approvals, and the board UI. > - Some agent proposals need structured board/user decisions, not hidden markdown conventions or heavyweight governed approvals. > - Issue-thread interactions already provide a natural thread-native surface for proposed tasks and questions. > - This pull request extends that surface with request confirmations, richer interaction cards, and agent/plugin/MCP helpers. > - The benefit is that plan approvals and yes/no decisions become explicit, auditable, and resumable without losing the single-issue workflow. ## What Changed - Added persisted issue-thread interactions for suggested tasks, structured questions, and request confirmations. - Added board UI cards for interaction review, selection, question answers, and accept/reject confirmation flows. - Added MCP and plugin SDK helpers for creating interaction cards from agents/plugins. - Updated agent wake instructions, onboarding assets, Paperclip skill docs, and public docs to prefer structured confirmations for issue-scoped decisions. - Rebased the branch onto `public-gh/master` and renumbered branch migrations to `0063` and `0064`; the idempotency migration uses `ADD COLUMN IF NOT EXISTS` for old branch users. ## Verification - `git diff --check public-gh/master..HEAD` - `pnpm exec vitest run packages/adapter-utils/src/server-utils.test.ts packages/mcp-server/src/tools.test.ts packages/shared/src/issue-thread-interactions.test.ts ui/src/lib/issue-thread-interactions.test.ts ui/src/lib/issue-chat-messages.test.ts ui/src/components/IssueThreadInteractionCard.test.tsx ui/src/components/IssueChatThread.test.tsx server/src/__tests__/issue-thread-interaction-routes.test.ts server/src/__tests__/issue-thread-interactions-service.test.ts server/src/services/issue-thread-interactions.test.ts` -> 9 files / 79 tests passed - `pnpm -r typecheck` -> passed, including `packages/db` migration numbering check ## Risks - Medium: this adds a new issue-thread interaction model across db/shared/server/ui/plugin surfaces. - Migration risk is reduced by placing this branch after current master migrations (`0063`, `0064`) and making the idempotency column add idempotent for users who applied the old branch numbering. - UI interaction behavior is covered by component tests, but this PR does not include browser screenshots. > 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, GPT-5-class coding agent runtime. Exact model ID and context window are not exposed in this Paperclip run; tool use and local shell/code execution were enabled. ## 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 run tests locally and they pass - [x] I have added or updated tests where applicable - [ ] 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 - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>	2026-04-21 20:15:11 -05:00
Dotta	09d0678840	[codex] Harden heartbeat scheduling and runtime controls (#4223) ... ## Thinking Path > - Paperclip orchestrates AI agents through issue checkout, heartbeat runs, routines, and auditable control-plane state > - The runtime path has to recover from lost local processes, transient adapter failures, blocked dependencies, and routine coalescing without stranding work > - The existing branch carried several reliability fixes across heartbeat scheduling, issue runtime controls, routine dispatch, and operator-facing run state > - These changes belong together because they share backend contracts, migrations, and runtime status semantics > - This pull request groups the control-plane/runtime slice so it can merge independently from board UI polish and adapter sandbox work > - The benefit is safer heartbeat recovery, clearer runtime controls, and more predictable recurring execution behavior ## What Changed - Adds bounded heartbeat retry scheduling, scheduled retry state, and Codex transient failure recovery handling. - Tightens heartbeat process recovery, blocker wake behavior, issue comment wake handling, routine dispatch coalescing, and activity/dashboard bounds. - Adds runtime-control MCP tools and Paperclip skill docs for issue workspace runtime management. - Adds migrations `0061_lively_thor_girl.sql` and `0062_routine_run_dispatch_fingerprint.sql`. - Surfaces retry state in run ledger/agent UI and keeps related shared types synchronized. ## Verification - `pnpm exec vitest run server/src/__tests__/heartbeat-retry-scheduling.test.ts server/src/__tests__/heartbeat-process-recovery.test.ts server/src/__tests__/routines-service.test.ts` - `pnpm exec vitest run src/tools.test.ts` from `packages/mcp-server` ## Risks - Medium risk: this touches heartbeat recovery and routine dispatch, which are central execution paths. - Migration order matters if split branches land out of order: merge this PR before branches that assume the new runtime/routine fields. - Runtime retry behavior should be watched in CI and in local operator smoke tests because it changes how transient failures are resumed. > 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, GPT-5-based coding agent runtime, shell/git tool use enabled. Exact hosted model build and context window are not exposed in this Paperclip heartbeat environment. ## 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 run tests locally and they pass - [x] I have added or updated tests where applicable - [ ] 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 - [x] I will address all Greptile and reviewer comments before requesting merge	2026-04-21 12:24:11 -05:00
Dotta	0f4e4b4c10	[codex] Split reusable agent hiring templates (#4124) ... ## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies > - Hiring new agents depends on clear, reusable operating instructions > - The create-agent skill had one large template reference that mixed multiple roles together > - That made it harder to reuse, review, and adapt role-specific instructions during governed hires > - This pull request splits the reusable agent instruction templates into focused role files and polishes the agent instructions pane layout > - The benefit is faster, clearer agent hiring without bloating the main skill document ## What Changed - Split coder, QA, and UX designer reusable instructions into dedicated reference files. - Kept the index reference concise and pointed it at the role-specific files. - Updated the create-agent skill to describe the separated template structure. - Polished the agent detail instructions/package file tree layout so the longer template references remain readable. ## Verification - `pnpm install --frozen-lockfile --ignore-scripts` - `pnpm --filter @paperclipai/ui typecheck` - UI screenshot rationale: no screenshots attached because the visible change is limited to the Agent detail instructions file-tree layout (`wrapLabels` plus the side-by-side breakpoint). There is no new user flow or state transition to demonstrate; reviewers can verify visually by opening an agent's Instructions tab and resizing across the single-column and side-by-side breakpoints to confirm long file names wrap instead of truncating or overflowing. ## Risks - Low risk: this is documentation and UI layout only. - Main risk is stale links in the skill references; the new files are committed in the referenced paths. > 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, tool-enabled local shell and GitHub workflow, exact runtime context window not exposed in this session. ## 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 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, or documented why targeted component/type verification is sufficient here - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>	2026-04-20 10:33:19 -05:00
Aron Prins	73eb23734f	docs: use structured agent mentions in paperclip skill (#4103) ... ## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies > - Agents coordinate work through tasks and comments, and @-mentions are part of the wakeup path for cross-agent handoffs and review requests > - The current repo skill still instructs machine-authored comments to use raw `@AgentName` text as the default mention format > - But the current backend mention parsing is still unreliable for multi-word display names, so agents following that guidance can silently fail to wake the intended target > - This pull request updates the Paperclip skill and API reference to prefer structured `agent://` markdown mentions for machine-authored comments > - The benefit is a low-risk documentation workaround that steers agents onto the mention format the server already resolves reliably while broader runtime fixes are reviewed upstream ## What Changed - Updated `skills/paperclip/SKILL.md` to stop recommending raw `@AgentName` mentions for machine-authored comments - Updated `skills/paperclip/references/api-reference.md` with a concrete workflow: resolve the target via `GET /api/companies/{companyId}/agents`, then emit `[@Display Name](agent://<agent-id>)` - Added explicit guidance that raw `@AgentName` text is fallback-only and unreliable for names containing spaces - Cross-referenced the current upstream mention-bug context so reviewers can connect this docs workaround to the open parser/runtime fixes Related issue/PR refs: #448, #459, #558, #669, #722, #1412, #2249 ## Verification - `pnpm -r typecheck` - `pnpm build` - `pnpm test:run` currently fails on upstream `master` in existing tests unrelated to this docs-only change: - `src/__tests__/worktree.test.ts` — `seeds authenticated users into minimally cloned worktree instances` timed out after 20000ms - `src/__tests__/onboard.test.ts` — `keeps tailnet quickstart on loopback until tailscale is available` expected `127.0.0.1` but got `100.125.202.3` - Confirmed the git diff is limited to: - `skills/paperclip/SKILL.md` - `skills/paperclip/references/api-reference.md` ## Risks - Low risk. This is a docs/skill-only change and does not alter runtime behavior. - It is a mitigation, not a full fix: it helps agent-authored comments that follow the Paperclip skill, but it does not fix manually typed raw mentions or other code paths that still emit plain `@Name` text. - If upstream chooses a different long-term mention format, this guidance may need to be revised once the runtime-side fix lands. ## Model Used - OpenAI Codex desktop agent on a GPT-5-class model. Exact deployed model ID and context window are not exposed by the local harness. Tool use enabled, including shell execution, git, and GitHub CLI. ## 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 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 - [x] I will address all Greptile and reviewer comments before requesting merge	2026-04-20 07:38:04 -07:00
Dotta	16b2b84d84	[codex] Improve agent runtime recovery and governance (#4086) ... ## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies. > - The heartbeat runtime, agent import path, and agent configuration defaults determine whether work is dispatched safely and predictably. > - Several accumulated fixes all touched agent execution recovery, wake routing, import behavior, and runtime concurrency defaults. > - Those changes need to land together so the heartbeat service and agent creation defaults stay internally consistent. > - This pull request groups the runtime/governance changes from the split branch into one standalone branch. > - The benefit is safer recovery for stranded runs, bounded high-volume reads, imported-agent approval correctness, skill-template support, and a clearer default concurrency policy. ## What Changed - Fixed stranded continuation recovery so successful automatic retries are requeued instead of incorrectly blocking the issue. - Bounded high-volume issue/log reads across issue, heartbeat, agent, project, and workspace paths. - Fixed imported-agent approval and instruction-path permission handling. - Quarantined seeded worktree execution state during worktree provisioning. - Queued approval follow-up wakes and hardened SQL_ASCII heartbeat output handling. - Added reusable agent instruction templates for hiring flows. - Set the default max concurrent agent runs to five and updated related UI/tests/docs. ## Verification - `pnpm install --frozen-lockfile` - `pnpm exec vitest run server/src/__tests__/company-portability.test.ts server/src/__tests__/heartbeat-process-recovery.test.ts server/src/__tests__/heartbeat-comment-wake-batching.test.ts server/src/__tests__/heartbeat-list.test.ts server/src/__tests__/issues-service.test.ts server/src/__tests__/agent-permissions-routes.test.ts packages/adapter-utils/src/server-utils.test.ts ui/src/lib/new-agent-runtime-config.test.ts` - Split integration check: merged this branch first, followed by the other [PAP-1614](/PAP/issues/PAP-1614) branches, with no merge conflicts. - Confirmed this branch does not include `pnpm-lock.yaml`. ## Risks - Medium risk: touches heartbeat recovery, queueing, and issue list bounds in central runtime paths. - Imported-agent and concurrency default behavior changes may affect existing automation that assumes one-at-a-time default runs. - No database migrations are included. > 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, GPT-5.4 tool-enabled coding model, agentic code-editing/runtime with local shell and GitHub CLI access; exact context window and reasoning mode are not exposed by the Paperclip harness. ## 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 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 - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>	2026-04-20 06:19:48 -05:00
Dotta	236d11d36f	[codex] Add run liveness continuations (#4083) ... ## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies. > - Heartbeat runs are the control-plane record of each agent execution window. > - Long-running local agents can exhaust context or stop while still holding useful next-step state. > - Operators need that stop reason, next action, and continuation path to be durable and visible. > - This pull request adds run liveness metadata, continuation summaries, and UI surfaces for issue run ledgers. > - The benefit is that interrupted or long-running work can resume with clearer context instead of losing the agent's last useful handoff. ## What Changed - Added heartbeat-run liveness fields, continuation attempt tracking, and an idempotent `0058` migration. - Added server services and tests for run liveness, continuation summaries, stop metadata, and activity backfill. - Wired local and HTTP adapters to surface continuation/liveness context through shared adapter utilities. - Added shared constants, validators, and heartbeat types for liveness continuation state. - Added issue-detail UI surfaces for continuation handoffs and the run ledger, with component tests. - Updated agent runtime docs, heartbeat protocol docs, prompt guidance, onboarding assets, and skills instructions to explain continuation behavior. - Addressed Greptile feedback by scoping document evidence by run, excluding system continuation-summary documents from liveness evidence, importing shared liveness types, surfacing hidden ledger run counts, documenting bounded retry behavior, and moving run-ledger liveness backfill off the request path. ## Verification - `pnpm exec vitest run packages/adapter-utils/src/server-utils.test.ts server/src/__tests__/run-continuations.test.ts server/src/__tests__/run-liveness.test.ts server/src/__tests__/activity-service.test.ts server/src/__tests__/documents-service.test.ts server/src/__tests__/issue-continuation-summary.test.ts server/src/services/heartbeat-stop-metadata.test.ts ui/src/components/IssueRunLedger.test.tsx ui/src/components/IssueContinuationHandoff.test.tsx ui/src/components/IssueDocumentsSection.test.tsx` - `pnpm --filter @paperclipai/db build` - `pnpm exec vitest run server/src/__tests__/activity-service.test.ts ui/src/components/IssueRunLedger.test.tsx` - `pnpm --filter @paperclipai/ui typecheck` - `pnpm --filter @paperclipai/server typecheck` - `pnpm exec vitest run server/src/__tests__/activity-service.test.ts server/src/__tests__/run-continuations.test.ts ui/src/components/IssueRunLedger.test.tsx` - `pnpm exec vitest run server/src/__tests__/heartbeat-process-recovery.test.ts -t "treats a plan document update"` - `pnpm exec vitest run server/src/__tests__/activity-service.test.ts server/src/__tests__/heartbeat-process-recovery.test.ts -t "activity service|treats a plan document update"` - Remote PR checks on head `e53b1a1d`: `verify`, `e2e`, `policy`, and Snyk all passed. - Confirmed `public-gh/master` is an ancestor of this branch after fetching `public-gh master`. - Confirmed `pnpm-lock.yaml` is not included in the branch diff. - Confirmed migration `0058_wealthy_starbolt.sql` is ordered after `0057` and uses `IF NOT EXISTS` guards for repeat application. - Greptile inline review threads are resolved. ## Risks - Medium risk: this touches heartbeat execution, liveness recovery, activity rendering, issue routes, shared contracts, docs, and UI. - Migration risk is mitigated by additive columns/indexes and idempotent guards. - Run-ledger liveness backfill is now asynchronous, so the first ledger response can briefly show historical missing liveness until the background backfill completes. - UI screenshot coverage is not included in this packaging pass; validation is currently through focused component tests. > 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, GPT-5.4, local tool-use coding agent with terminal, git, GitHub connector, GitHub CLI, and Paperclip API access. ## 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 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 - [x] I will address all Greptile and reviewer comments before requesting merge Screenshot note: no before/after screenshots were captured in this PR packaging pass; the UI changes are covered by focused component tests listed above. --------- Co-authored-by: Paperclip <noreply@paperclip.ing>	2026-04-20 06:01:49 -05:00
Dotta	7f893ac4ec	[codex] Harden execution reliability and heartbeat tooling (#3679) ... ## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies > - Reliable execution depends on heartbeat routing, issue lifecycle semantics, telemetry, and a fast enough local verification loop to keep regressions visible > - The remaining commits on this branch were mostly server/runtime correctness fixes plus test and documentation follow-ups in that area > - Those changes are logically separate from the UI-focused issue-detail and workspace/navigation branches even when they touch overlapping issue APIs > - This pull request groups the execution reliability, heartbeat, telemetry, and tooling changes into one standalone branch > - The benefit is a focused review of the control-plane correctness work, including the follow-up fix that restored the implicit comment-reopen helpers after branch splitting ## What Changed - Hardened issue/heartbeat execution behavior, including self-review stage skipping, deferred mention wakes during active execution, stranded execution recovery, active-run scoping, assignee resolution, and blocked-to-todo wake resumption - Reduced noisy polling/logging overhead by trimming issue run payloads, compacting persisted run logs, silencing high-volume request logs, and capping heartbeat-run queries in dashboard/inbox surfaces - Expanded telemetry and status semantics with adapter/model fields on task completion plus clearer status guidance in docs/onboarding material - Updated test infrastructure and verification defaults with faster route-test module isolation, cheaper default `pnpm test`, e2e isolation from local state, and repo verification follow-ups - Included docs/release housekeeping from the branch and added a small follow-up commit restoring the implicit comment-reopen helpers that were dropped during branch reconstruction ## Verification - `pnpm vitest run server/src/__tests__/issue-comment-reopen-routes.test.ts server/src/__tests__/issue-telemetry-routes.test.ts` - `pnpm vitest run server/src/__tests__/http-log-policy.test.ts server/src/__tests__/heartbeat-run-log.test.ts server/src/__tests__/health.test.ts` - `server/src/__tests__/activity-service.test.ts`, `server/src/__tests__/heartbeat-comment-wake-batching.test.ts`, and `server/src/__tests__/heartbeat-process-recovery.test.ts` were attempted on this host but the embedded Postgres harness reported init-script/data-dir problems and skipped or failed to start, so they are noted as environment-limited ## Risks - Medium: this branch changes core issue/heartbeat routing and reopen/wakeup behavior, so regressions would affect agent execution flow rather than isolated UI polish - Because it also updates verification infrastructure, reviewers should pay attention to whether the new tests are asserting the right failure modes and not just reshaping harness behavior ## Model Used - OpenAI Codex coding agent (GPT-5-class runtime in Codex CLI; exact deployed model ID is not exposed in this environment), reasoning enabled, tool use and local code execution enabled ## 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) - [ ] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [ ] 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 - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>	2026-04-14 13:34:52 -05:00
Dotta	8bdf4081ee	chore: improve worktree tooling and security docs	2026-04-10 22:26:30 -05:00
dotta	4e20279305	fix(skill): add scoped-wake fast path to skip full heartbeat on comment wakes ... When an agent is woken by a comment (Resume Delta or Wake Payload), the skill now explicitly instructs it to skip Steps 1-4 (identity, approvals, inbox, pick work) and go directly to checkout. This prevents agents from wastefully fetching their full assignment list and announcing "checking my paperclip tasks" when they already know exactly which issue to work on. Co-Authored-By: Paperclip <noreply@paperclip.ing>	2026-04-09 06:14:12 -05:00
dotta	0a5ac9affd	Clarify execution-policy reviewer guidance ... Add explicit Paperclip skill guidance for reviewer/approver heartbeats and document that execution-policy decisions use PATCH /api/issues/:issueId rather than a separate endpoint. Co-Authored-By: Paperclip <noreply@paperclip.ing>	2026-04-07 17:43:10 -05:00
dotta	365b6d9bd8	Add generic issue-linked board approvals ... Co-Authored-By: Paperclip <noreply@paperclip.ing>	2026-04-06 21:24:38 -05:00
Dotta	08fea10ce1	Merge pull request #2772 from paperclipai/PAPA-46-why-did-this-issue-succeed-without-following-my-instructions ... fix: enable agent re-checkout of in_review tasks on comment feedback	2026-04-06 18:57:33 -05:00
dotta	4c01a45d2a	fix: address greptile feedback for blocker dependencies ... Co-Authored-By: Paperclip <noreply@paperclip.ing>	2026-04-06 09:03:13 -05:00
dotta	9499d0df97	Add blocker/dependency documentation to Paperclip skill ... Document blockedByIssueIds field, issue_blockers_resolved and issue_children_completed wake reasons, and blockedBy/blocks response arrays in both SKILL.md and api-reference.md so agents know how to set and use first-class issue dependencies. Co-Authored-By: Paperclip <noreply@paperclip.ing>	2026-04-06 09:03:13 -05:00
dotta	b825a121cb	Prioritize comment wake prompts	2026-04-04 18:14:19 -05:00
dotta	91e040a696	Batch inline comment wake payloads ... Co-Authored-By: Paperclip <noreply@paperclip.ing>	2026-04-04 18:14:19 -05:00
Devin Foley	d12650e5ac	fix: update stale single-status checkout examples in worked docs ... Greptile flagged that worked examples in task-workflow.md and api-reference.md still used ["todo"] instead of the full expectedStatuses array. Aligned them with the rest of the PR. Co-Authored-By: Paperclip <noreply@paperclip.ing>	2026-04-04 11:43:29 -07:00
Devin Foley	cd2be692e9	Fix in-review task recheckout guidance ... Co-Authored-By: Paperclip <noreply@paperclip.ing>	2026-04-04 11:20:29 -07:00
Devin Foley	258c7ccd21	fix: ensure agents respond to comments on in_review tasks ... Root cause: when someone commented on an in_review task, the heartbeat wakeup was triggered but the agent couldn't re-checkout the task because expectedStatuses only included todo/backlog/blocked. The in_review status was never handled in the checkout flow or the heartbeat procedure. Changes: - Add wakeCommentId to issue_commented and issue_reopened_via_comment context snapshots (consistent with issue_comment_mentioned) - Add in_review to checkout expectedStatuses in heartbeat skill - Update Step 3 fallback query to include in_review status - Update Step 4 to prioritize in_review tasks when woken by comment - Add explicit issue_commented wake reason handling in Step 4 Co-Authored-By: Paperclip <noreply@paperclip.ing>	2026-04-03 09:19:48 -07:00
dotta	bd6d07d0b4	fix(ui): polish issue detail timelines and attachments ... Co-Authored-By: Paperclip <noreply@paperclip.ing>	2026-04-02 11:51:40 -05:00
dotta	6524dbe08f	fix(skills): move routines docs into paperclip references ... Co-Authored-By: Paperclip <noreply@paperclip.ing>	2026-04-02 06:28:04 -05:00
Aron Prins	4abd53c089	fix(skills): tighten api-reference table descriptions to match existing style ... Co-Authored-By: Paperclip <noreply@paperclip.ing> Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-04-02 11:00:53 +02:00
Aron Prins	3c99ab8d01	chore: improve api documentation and implementing routines properly.	2026-04-02 10:52:52 +02:00
Aron Prins	e5b2e8b29b	fix(skills): address greptile review on paperclip-routines skill ... - Add missing `description` field to the Creating a Routine field table - Document optional `label` field available on all trigger kinds	2026-04-01 13:56:10 +02:00
Aron Prins	62d8b39474	feat(skills): add paperclip-routines skill ... Adds a new skill that documents how to create and manage Paperclip routines — recurring tasks that fire on a schedule, webhook, or API call and dispatch an execution issue to the assigned agent.	2026-04-01 13:49:11 +02:00
dotta	ec1210caaa	Preserve workspaces for follow-up issues ... Co-Authored-By: Paperclip <noreply@paperclip.ing>	2026-03-30 14:10:36 -05:00
dotta	ce4536d1fa	Add agent Mine inbox API surface ... Co-Authored-By: Paperclip <noreply@paperclip.ing>	2026-03-29 10:57:34 -05:00
dotta	19154d0fec	Clarify Codex instruction sources ... Co-Authored-By: Paperclip <noreply@paperclip.ing>	2026-03-23 16:57:33 -05:00
dotta	2a33acce3a	Remove api trigger kind and mark webhook as coming soon ... Drop "api" from the trigger kind dropdown and disable the "webhook" option with a "COMING SOON" label until it's ready. Co-Authored-By: Paperclip <noreply@paperclip.ing>	2026-03-20 06:54:03 -05:00
dotta	ee85028534	docs: expand paperclip company skills guidance	2026-03-20 06:05:15 -05:00