Add planning mode for issue work (#5353)

## Thinking Path

> - Paperclip is a control plane for autonomous AI companies.
> - Issues are the core unit of work, and issue comments are how board
users and agents coordinate execution.
> - Some issue conversations need to produce plans and approvals instead
of immediate implementation work.
> - The existing issue contract did not distinguish standard execution
comments from planning-oriented issue work.
> - This pull request adds an issue work-mode contract and board UI
affordances for standard vs planning mode.
> - The benefit is that planning-mode issues can be created, displayed,
discussed, and carried through agent heartbeat context without losing
the normal issue workflow.

## What Changed

- Added `standard` / `planning` issue work-mode contracts across DB,
shared validators/types, server issue flows, plugin protocol, and
adapter heartbeat payloads.
- Added an idempotent `0081_optimal_dormammu` migration for
`issues.work_mode`, ordered after current `public-gh/master` migrations.
- Updated heartbeat/context summaries and issue-thread interaction
behavior so planning work mode is preserved when creating suggested
follow-up issues.
- Added UI support for planning-mode issue creation, issue rows, detail
composer styling, and composer work-mode toggles.
- Added focused server/shared/UI tests plus a Playwright visual
verification spec for planning-mode surfaces.
- Rebased the branch onto current `public-gh/master` and added durable
planning-mode screenshots under `doc/assets/pap-3368/`.

## Verification

- `pnpm --filter @paperclipai/db run check:migrations`
- `pnpm exec vitest run --project @paperclipai/shared
packages/shared/src/validators/issue.test.ts`
- `pnpm exec vitest run --project @paperclipai/server
server/src/__tests__/heartbeat-context-summary.test.ts
server/src/__tests__/issue-thread-interactions-service.test.ts
server/src/__tests__/issues-goal-context-routes.test.ts --pool=forks
--poolOptions.forks.isolate=true`
- `pnpm exec vitest run --project @paperclipai/ui
ui/src/components/IssueChatThread.test.tsx
ui/src/components/NewIssueDialog.test.tsx
ui/src/components/IssueRow.test.tsx ui/src/pages/IssueDetail.test.tsx`
- `pnpm exec vitest run --project @paperclipai/adapter-utils
packages/adapter-utils/src/server-utils.test.ts`
- `PAPERCLIP_E2E_SKIP_LLM=true npx playwright test --config
tests/e2e/playwright.config.ts
tests/e2e/planning-mode-visual-verification.spec.ts`

## Screenshots

Desktop planning detail:

![Desktop planning
detail](https://raw.githubusercontent.com/paperclipai/paperclip/PAP-3368-plan-a-planning-mode-for-issues/doc/assets/pap-3368/desktop-planning-detail.png)

Desktop planning row:

![Desktop planning
row](https://raw.githubusercontent.com/paperclipai/paperclip/PAP-3368-plan-a-planning-mode-for-issues/doc/assets/pap-3368/desktop-planning-row.png)

Desktop staged standard toggle:

![Desktop staged standard
toggle](https://raw.githubusercontent.com/paperclipai/paperclip/PAP-3368-plan-a-planning-mode-for-issues/doc/assets/pap-3368/desktop-standard-toggle.png)

Mobile planning detail:

![Mobile planning
detail](https://raw.githubusercontent.com/paperclipai/paperclip/PAP-3368-plan-a-planning-mode-for-issues/doc/assets/pap-3368/mobile-planning-detail.png)

Mobile planning row:

![Mobile planning
row](https://raw.githubusercontent.com/paperclipai/paperclip/PAP-3368-plan-a-planning-mode-for-issues/doc/assets/pap-3368/mobile-planning-row.png)

## Risks

- Medium migration risk: this adds a non-null issue column. The
migration uses `ADD COLUMN IF NOT EXISTS` so installations that applied
an older branch-local migration number can still apply the final
numbered migration safely.
- Medium contract risk: issue payloads, plugin payloads, and adapter
heartbeat payloads now include work mode; compatibility is handled by
defaulting missing values to `standard`.
- UI risk is moderate because composer controls changed; focused
component tests and visual e2e coverage exercise standard vs planning
display and toggle 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 in a local Paperclip worktree, with
shell/tool use. Exact context-window size 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 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>
This commit is contained in:
Dotta 2026-05-06 07:01:28 -05:00 committed by GitHub
parent 320fd5d23b
commit a1b30c9f35
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
65 changed files with 1539 additions and 214 deletions

View file

@ -0,0 +1 @@
ALTER TABLE "issues" ADD COLUMN IF NOT EXISTS "work_mode" text DEFAULT 'standard' NOT NULL;

View file

@ -1,6 +1,6 @@
{
"id": "063c8887-ed46-4125-a08f-51c16b636245",
"prevId": "fdc9cd8b-5423-4d64-b255-9bc1497fdd6a",
"id": "a7ba5d6c-9f74-487d-a9c1-56a4d5455b92",
"prevId": "50cf2dfe-df7b-4f02-a169-edbae599cf39",
"version": "7",
"dialect": "postgresql",
"tables": {
@ -8274,6 +8274,12 @@
"primaryKey": false,
"notNull": false
},
"author_type": {
"name": "author_type",
"type": "text",
"primaryKey": false,
"notNull": false
},
"created_by_run_id": {
"name": "created_by_run_id",
"type": "uuid",
@ -8286,6 +8292,18 @@
"primaryKey": false,
"notNull": true
},
"presentation": {
"name": "presentation",
"type": "jsonb",
"primaryKey": false,
"notNull": false
},
"metadata": {
"name": "metadata",
"type": "jsonb",
"primaryKey": false,
"notNull": false
},
"created_at": {
"name": "created_at",
"type": "timestamp with time zone",
@ -10990,6 +11008,13 @@
"notNull": true,
"default": "'backlog'"
},
"work_mode": {
"name": "work_mode",
"type": "text",
"primaryKey": false,
"notNull": true,
"default": "'standard'"
},
"priority": {
"name": "priority",
"type": "text",
@ -13103,6 +13128,195 @@
"checkConstraints": {},
"isRLSEnabled": false
},
"public.plugin_managed_resources": {
"name": "plugin_managed_resources",
"schema": "",
"columns": {
"id": {
"name": "id",
"type": "uuid",
"primaryKey": true,
"notNull": true,
"default": "gen_random_uuid()"
},
"company_id": {
"name": "company_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"plugin_id": {
"name": "plugin_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"plugin_key": {
"name": "plugin_key",
"type": "text",
"primaryKey": false,
"notNull": true
},
"resource_kind": {
"name": "resource_kind",
"type": "text",
"primaryKey": false,
"notNull": true
},
"resource_key": {
"name": "resource_key",
"type": "text",
"primaryKey": false,
"notNull": true
},
"resource_id": {
"name": "resource_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"defaults_json": {
"name": "defaults_json",
"type": "jsonb",
"primaryKey": false,
"notNull": true,
"default": "'{}'::jsonb"
},
"created_at": {
"name": "created_at",
"type": "timestamp with time zone",
"primaryKey": false,
"notNull": true,
"default": "now()"
},
"updated_at": {
"name": "updated_at",
"type": "timestamp with time zone",
"primaryKey": false,
"notNull": true,
"default": "now()"
}
},
"indexes": {
"plugin_managed_resources_company_idx": {
"name": "plugin_managed_resources_company_idx",
"columns": [
{
"expression": "company_id",
"isExpression": false,
"asc": true,
"nulls": "last"
}
],
"isUnique": false,
"concurrently": false,
"method": "btree",
"with": {}
},
"plugin_managed_resources_plugin_idx": {
"name": "plugin_managed_resources_plugin_idx",
"columns": [
{
"expression": "plugin_id",
"isExpression": false,
"asc": true,
"nulls": "last"
}
],
"isUnique": false,
"concurrently": false,
"method": "btree",
"with": {}
},
"plugin_managed_resources_resource_idx": {
"name": "plugin_managed_resources_resource_idx",
"columns": [
{
"expression": "resource_kind",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "resource_id",
"isExpression": false,
"asc": true,
"nulls": "last"
}
],
"isUnique": false,
"concurrently": false,
"method": "btree",
"with": {}
},
"plugin_managed_resources_company_plugin_resource_uq": {
"name": "plugin_managed_resources_company_plugin_resource_uq",
"columns": [
{
"expression": "company_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "plugin_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "resource_kind",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "resource_key",
"isExpression": false,
"asc": true,
"nulls": "last"
}
],
"isUnique": true,
"concurrently": false,
"method": "btree",
"with": {}
}
},
"foreignKeys": {
"plugin_managed_resources_company_id_companies_id_fk": {
"name": "plugin_managed_resources_company_id_companies_id_fk",
"tableFrom": "plugin_managed_resources",
"tableTo": "companies",
"columnsFrom": [
"company_id"
],
"columnsTo": [
"id"
],
"onDelete": "cascade",
"onUpdate": "no action"
},
"plugin_managed_resources_plugin_id_plugins_id_fk": {
"name": "plugin_managed_resources_plugin_id_plugins_id_fk",
"tableFrom": "plugin_managed_resources",
"tableTo": "plugins",
"columnsFrom": [
"plugin_id"
],
"columnsTo": [
"id"
],
"onDelete": "cascade",
"onUpdate": "no action"
}
},
"compositePrimaryKeys": {},
"uniqueConstraints": {},
"policies": {},
"checkConstraints": {},
"isRLSEnabled": false
},
"public.plugin_migrations": {
"name": "plugin_migrations",
"schema": "",
@ -14358,6 +14572,214 @@
"checkConstraints": {},
"isRLSEnabled": false
},
"public.routine_revisions": {
"name": "routine_revisions",
"schema": "",
"columns": {
"id": {
"name": "id",
"type": "uuid",
"primaryKey": true,
"notNull": true,
"default": "gen_random_uuid()"
},
"company_id": {
"name": "company_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"routine_id": {
"name": "routine_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"revision_number": {
"name": "revision_number",
"type": "integer",
"primaryKey": false,
"notNull": true
},
"title": {
"name": "title",
"type": "text",
"primaryKey": false,
"notNull": true
},
"description": {
"name": "description",
"type": "text",
"primaryKey": false,
"notNull": false
},
"snapshot": {
"name": "snapshot",
"type": "jsonb",
"primaryKey": false,
"notNull": true
},
"change_summary": {
"name": "change_summary",
"type": "text",
"primaryKey": false,
"notNull": false
},
"restored_from_revision_id": {
"name": "restored_from_revision_id",
"type": "uuid",
"primaryKey": false,
"notNull": false
},
"created_by_agent_id": {
"name": "created_by_agent_id",
"type": "uuid",
"primaryKey": false,
"notNull": false
},
"created_by_user_id": {
"name": "created_by_user_id",
"type": "text",
"primaryKey": false,
"notNull": false
},
"created_by_run_id": {
"name": "created_by_run_id",
"type": "uuid",
"primaryKey": false,
"notNull": false
},
"created_at": {
"name": "created_at",
"type": "timestamp with time zone",
"primaryKey": false,
"notNull": true,
"default": "now()"
}
},
"indexes": {
"routine_revisions_routine_revision_uq": {
"name": "routine_revisions_routine_revision_uq",
"columns": [
{
"expression": "routine_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "revision_number",
"isExpression": false,
"asc": true,
"nulls": "last"
}
],
"isUnique": true,
"concurrently": false,
"method": "btree",
"with": {}
},
"routine_revisions_company_routine_created_idx": {
"name": "routine_revisions_company_routine_created_idx",
"columns": [
{
"expression": "company_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "routine_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "created_at",
"isExpression": false,
"asc": true,
"nulls": "last"
}
],
"isUnique": false,
"concurrently": false,
"method": "btree",
"with": {}
}
},
"foreignKeys": {
"routine_revisions_company_id_companies_id_fk": {
"name": "routine_revisions_company_id_companies_id_fk",
"tableFrom": "routine_revisions",
"tableTo": "companies",
"columnsFrom": [
"company_id"
],
"columnsTo": [
"id"
],
"onDelete": "cascade",
"onUpdate": "no action"
},
"routine_revisions_routine_id_routines_id_fk": {
"name": "routine_revisions_routine_id_routines_id_fk",
"tableFrom": "routine_revisions",
"tableTo": "routines",
"columnsFrom": [
"routine_id"
],
"columnsTo": [
"id"
],
"onDelete": "cascade",
"onUpdate": "no action"
},
"routine_revisions_restored_from_revision_id_routine_revisions_id_fk": {
"name": "routine_revisions_restored_from_revision_id_routine_revisions_id_fk",
"tableFrom": "routine_revisions",
"tableTo": "routine_revisions",
"columnsFrom": [
"restored_from_revision_id"
],
"columnsTo": [
"id"
],
"onDelete": "set null",
"onUpdate": "no action"
},
"routine_revisions_created_by_agent_id_agents_id_fk": {
"name": "routine_revisions_created_by_agent_id_agents_id_fk",
"tableFrom": "routine_revisions",
"tableTo": "agents",
"columnsFrom": [
"created_by_agent_id"
],
"columnsTo": [
"id"
],
"onDelete": "set null",
"onUpdate": "no action"
},
"routine_revisions_created_by_run_id_heartbeat_runs_id_fk": {
"name": "routine_revisions_created_by_run_id_heartbeat_runs_id_fk",
"tableFrom": "routine_revisions",
"tableTo": "heartbeat_runs",
"columnsFrom": [
"created_by_run_id"
],
"columnsTo": [
"id"
],
"onDelete": "set null",
"onUpdate": "no action"
}
},
"compositePrimaryKeys": {},
"uniqueConstraints": {},
"policies": {},
"checkConstraints": {},
"isRLSEnabled": false
},
"public.routine_runs": {
"name": "routine_runs",
"schema": "",
@ -15022,6 +15444,19 @@
"notNull": true,
"default": "'[]'::jsonb"
},
"latest_revision_id": {
"name": "latest_revision_id",
"type": "uuid",
"primaryKey": false,
"notNull": false
},
"latest_revision_number": {
"name": "latest_revision_number",
"type": "integer",
"primaryKey": false,
"notNull": true,
"default": 1
},
"created_by_agent_id": {
"name": "created_by_agent_id",
"type": "uuid",
@ -15929,195 +16364,6 @@
"policies": {},
"checkConstraints": {},
"isRLSEnabled": false
},
"public.plugin_managed_resources": {
"name": "plugin_managed_resources",
"schema": "",
"columns": {
"id": {
"name": "id",
"type": "uuid",
"primaryKey": true,
"notNull": true,
"default": "gen_random_uuid()"
},
"company_id": {
"name": "company_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"plugin_id": {
"name": "plugin_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"plugin_key": {
"name": "plugin_key",
"type": "text",
"primaryKey": false,
"notNull": true
},
"resource_kind": {
"name": "resource_kind",
"type": "text",
"primaryKey": false,
"notNull": true
},
"resource_key": {
"name": "resource_key",
"type": "text",
"primaryKey": false,
"notNull": true
},
"resource_id": {
"name": "resource_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"defaults_json": {
"name": "defaults_json",
"type": "jsonb",
"primaryKey": false,
"notNull": true,
"default": "'{}'::jsonb"
},
"created_at": {
"name": "created_at",
"type": "timestamp with time zone",
"primaryKey": false,
"notNull": true,
"default": "now()"
},
"updated_at": {
"name": "updated_at",
"type": "timestamp with time zone",
"primaryKey": false,
"notNull": true,
"default": "now()"
}
},
"indexes": {
"plugin_managed_resources_company_idx": {
"name": "plugin_managed_resources_company_idx",
"columns": [
{
"expression": "company_id",
"isExpression": false,
"asc": true,
"nulls": "last"
}
],
"isUnique": false,
"concurrently": false,
"method": "btree",
"with": {}
},
"plugin_managed_resources_plugin_idx": {
"name": "plugin_managed_resources_plugin_idx",
"columns": [
{
"expression": "plugin_id",
"isExpression": false,
"asc": true,
"nulls": "last"
}
],
"isUnique": false,
"concurrently": false,
"method": "btree",
"with": {}
},
"plugin_managed_resources_resource_idx": {
"name": "plugin_managed_resources_resource_idx",
"columns": [
{
"expression": "resource_kind",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "resource_id",
"isExpression": false,
"asc": true,
"nulls": "last"
}
],
"isUnique": false,
"concurrently": false,
"method": "btree",
"with": {}
},
"plugin_managed_resources_company_plugin_resource_uq": {
"name": "plugin_managed_resources_company_plugin_resource_uq",
"columns": [
{
"expression": "company_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "plugin_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "resource_kind",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "resource_key",
"isExpression": false,
"asc": true,
"nulls": "last"
}
],
"isUnique": true,
"concurrently": false,
"method": "btree",
"with": {}
}
},
"foreignKeys": {
"plugin_managed_resources_company_id_companies_id_fk": {
"name": "plugin_managed_resources_company_id_companies_id_fk",
"tableFrom": "plugin_managed_resources",
"tableTo": "companies",
"columnsFrom": [
"company_id"
],
"columnsTo": [
"id"
],
"onDelete": "cascade",
"onUpdate": "no action"
},
"plugin_managed_resources_plugin_id_plugins_id_fk": {
"name": "plugin_managed_resources_plugin_id_plugins_id_fk",
"tableFrom": "plugin_managed_resources",
"tableTo": "plugins",
"columnsFrom": [
"plugin_id"
],
"columnsTo": [
"id"
],
"onDelete": "cascade",
"onUpdate": "no action"
}
},
"compositePrimaryKeys": {},
"uniqueConstraints": {},
"policies": {},
"checkConstraints": {},
"isRLSEnabled": false
}
},
"enums": {},

View file

@ -568,6 +568,13 @@
"when": 1777849000000,
"tag": "0080_company_search_fuzzystrmatch",
"breakpoints": true
},
{
"idx": 81,
"version": "7",
"when": 1778067785040,
"tag": "0081_optimal_dormammu",
"breakpoints": true
}
]
}

View file

@ -30,6 +30,7 @@ export const issues = pgTable(
title: text("title").notNull(),
description: text("description"),
status: text("status").notNull().default("backlog"),
workMode: text("work_mode").notNull().default("standard"),
priority: text("priority").notNull().default("medium"),
assigneeAgentId: uuid("assignee_agent_id").references(() => agents.id),
assigneeUserId: text("assignee_user_id"),