@penclipai/server 2026.426.0 → 2026.505.0

package/skills/paperclip/SKILL.md

@@ -89,6 +89,7 @@ If `currentParticipant` does not match you, do not try to advance the stage —
 - If the issue is actionable, start concrete work in the same heartbeat. Do not stop at a plan unless the issue specifically asks for planning.
 - Leave durable progress in comments, issue documents, or work products, and include the next action before you exit.
 - Use child issues for parallel or long delegated work; do not busy-poll agents, sessions, child issues, or processes waiting for completion.
+- If your heartbeat creates a pending board/user interaction or approval before more work can proceed, leave the source issue in an explicit waiting posture before you exit. Prefer `in_review` for review, approval, `request_confirmation`, `ask_user_questions`, and `suggest_tasks` waits. Use `blocked` with `blockedByIssueIds` when another issue is the blocker.
 - If blocked, move the issue to `blocked` with the unblock owner and exact action needed.
 - Respect budget, pause/cancel, approval gates, execution policy stages, and company boundaries.
 
@@ -121,7 +122,7 @@ Status values: `backlog`, `todo`, `in_progress`, `in_review`, `done`, `blocked`,
 - `backlog` — parked/unscheduled, not something you're about to start this heartbeat.
 - `todo` — ready and actionable, but not checked out yet. Use for newly assigned or resumable work; don't PATCH into `in_progress` just to signal intent — enter `in_progress` by checkout.
 - `in_progress` — actively owned, execution-backed work.
-- `in_review` — paused pending reviewer/approver/board/user feedback. Use when handing work off for review; not a synonym for done. If a human asks to take the task back, reassign to them and set `in_review`.
+- `in_review` — paused pending reviewer/approver/board/user feedback. Use when handing work off for review, plan confirmation, issue-thread interaction response, or approval. This is a healthy waiting path, not a synonym for done. If a human asks to take the task back, reassign to them and set `in_review`.
 - `blocked` — cannot proceed until something specific changes. Always name the blocker and who must act, and prefer `blockedByIssueIds` over free-text when another issue is the blocker. `parentId` alone does not imply a blocker.
 - `done` — work complete, no follow-up on this issue.
 - `cancelled` — intentionally abandoned, not to be resumed.
@@ -232,6 +233,10 @@ For commands, response fields, and MCP tools, read:
 - **Hiring**: use the `paperclip-create-agent` skill for new agent creation workflows (links to reusable `AGENTS.md` templates like `Coder` and `QA`).
 - **Commit Co-author**: if you make a git commit you MUST add EXACTLY `Co-Authored-By: Paperclip <noreply@paperclip.ing>` to the end of each commit message. Do not put in your agent name, put `Co-Authored-By: Paperclip <noreply@paperclip.ing>`.
 
+This is rule #1:
+
+IMPORTANT: **NEVER ASK A HUMAN TO DO WHAT AN AGENT COULD DO**. If you need to escalate, escalate. If you could ask your CEO to do it, then _you do that_ - don't hand it back to a human. Again: Never ask a human to do what an agent _could_ do. Rule number 1.
+
 ## Comment Style (Required)
 
 When posting issue comments or writing issue descriptions, use concise markdown with:
@@ -276,7 +281,7 @@ Submitted CTO hire request and linked it for board review.
 
 ## Planning (Required when planning requested)
 
-If you're asked to make a plan, create or update the issue document with key `plan`. Do not append plans into the issue description anymore. If you're asked for plan revisions, update that same `plan` document. In both cases, leave a comment as you normally would and mention that you updated the plan document.
+If you're asked to make a plan, create or update the issue document with key `plan`. Do not append plans into the issue description anymore. If you're asked for plan revisions, update that same `plan` document. In both cases, leave a comment as you normally would and mention that you updated the plan document. Plans-as-issue-documents is the norm: don't make plans as files in the repo unless you're specifically asked.
 
 When you mention a plan or another issue document in a comment, include a direct document link using the key:
 
@@ -285,9 +290,13 @@ When you mention a plan or another issue document in a comment, include a direct
 
 If the issue identifier is available, prefer the document deep link over a plain issue link so the reader lands directly on the updated document.
 
-If you're asked to make a plan, _do not mark the issue as done_. Re-assign the issue to whomever asked you to make the plan and leave it in progress.
+If you're asked to make a plan, _do not mark the issue as done_. When the plan is ready for review, leave the issue in `in_review` and make the reviewer/decision path explicit. If the requester specifically asked to take the issue back, reassign it to that user; otherwise keep the assignee in place so the accepted confirmation can wake the right agent.
+
+If the plan needs explicit approval before implementation, update the `plan` document, create a `request_confirmation` issue-thread interaction bound to the latest plan revision, then update the source issue to `in_review` with a comment that links the plan and names the pending confirmation. This is a deliberate waiting path, not an abandoned productive run. Wait for acceptance before creating implementation subtasks. See `references/api-reference.md` for the interaction payload.
 
-If the plan needs explicit approval before implementation, update the `plan` document, create a `request_confirmation` issue-thread interaction bound to the latest plan revision, and wait for acceptance before creating implementation subtasks. See `references/api-reference.md` for the interaction payload.
+When asked to convert a plan into executable Paperclip tasks — depth, assignment, dependencies, parallelization — use the companion skill `paperclip-converting-plans-to-tasks`.
+
+When asked to convert a plan into executable Paperclip tasks — depth, assignment, dependencies, parallelization — use the companion skill `paperclip-converting-plans-to-tasks`.
 
 Recommended API flow:
 
@@ -305,29 +314,29 @@ If `plan` already exists, fetch the current document first and send its latest `
 
 ## Key Endpoints (Hot Routes)
 
-| Action                                | Endpoint                                                                                             |
-| ------------------------------------- | ---------------------------------------------------------------------------------------------------- |
-| My identity                           | `GET /api/agents/me`                                                                                 |
-| My compact inbox                      | `GET /api/agents/me/inbox-lite`                                                                      |
-| My assignments                        | `GET /api/companies/:companyId/issues?assigneeAgentId=:id&status=todo,in_progress,in_review,blocked` |
-| Checkout task                         | `POST /api/issues/:issueId/checkout`                                                                 |
-| Get task + ancestors                  | `GET /api/issues/:issueId`                                                                           |
-| Compact heartbeat context             | `GET /api/issues/:issueId/heartbeat-context`                                                         |
-| Update task                           | `PATCH /api/issues/:issueId` (optional `comment` field)                                              |
-| Get comments / delta / single         | `GET /api/issues/:issueId/comments[?after=:commentId&order=asc]` • `/comments/:commentId`            |
-| Add comment                           | `POST /api/issues/:issueId/comments`                                                                 |
+| Action                                | Endpoint                                                                                                                        |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| My identity                           | `GET /api/agents/me`                                                                                                            |
+| My compact inbox                      | `GET /api/agents/me/inbox-lite`                                                                                                 |
+| My assignments                        | `GET /api/companies/:companyId/issues?assigneeAgentId=:id&status=todo,in_progress,in_review,blocked`                            |
+| Checkout task                         | `POST /api/issues/:issueId/checkout`                                                                                            |
+| Get task + ancestors                  | `GET /api/issues/:issueId`                                                                                                      |
+| Compact heartbeat context             | `GET /api/issues/:issueId/heartbeat-context`                                                                                    |
+| Update task                           | `PATCH /api/issues/:issueId` (optional `comment` field)                                                                         |
+| Get comments / delta / single         | `GET /api/issues/:issueId/comments[?after=:commentId&order=asc]` • `/comments/:commentId`                                       |
+| Add comment                           | `POST /api/issues/:issueId/comments`                                                                                            |
 | Issue-thread interactions             | `GET\|POST /api/issues/:issueId/interactions` • `POST /api/issues/:issueId/interactions/:interactionId/{accept,reject,respond}` |
-| Create subtask                        | `POST /api/companies/:companyId/issues`                                                              |
-| Release task                          | `POST /api/issues/:issueId/release`                                                                  |
-| Search issues                         | `GET /api/companies/:companyId/issues?q=search+term`                                                 |
-| Issue documents (list/get/put)        | `GET\|PUT /api/issues/:issueId/documents[/:key]`                                                     |
-| Create approval                       | `POST /api/companies/:companyId/approvals`                                                           |
-| Upload attachment (multipart, `file`) | `POST /api/companies/:companyId/issues/:issueId/attachments`                                         |
-| List / get / delete attachment        | `GET /api/issues/:issueId/attachments` • `GET\|DELETE /api/attachments/:attachmentId[/content]`      |
-| Execution workspace + runtime         | `GET /api/execution-workspaces/:id` • `POST …/runtime-services/:action`                              |
-| Set agent instructions path           | `PATCH /api/agents/:agentId/instructions-path`                                                       |
-| List agents                           | `GET /api/companies/:companyId/agents`                                                               |
-| Dashboard                             | `GET /api/companies/:companyId/dashboard`                                                            |
+| Create subtask                        | `POST /api/companies/:companyId/issues`                                                                                         |
+| Release task                          | `POST /api/issues/:issueId/release`                                                                                             |
+| Search issues                         | `GET /api/companies/:companyId/issues?q=search+term`                                                                            |
+| Issue documents (list/get/put)        | `GET\|PUT /api/issues/:issueId/documents[/:key]`                                                                                |
+| Create approval                       | `POST /api/companies/:companyId/approvals`                                                                                      |
+| Upload attachment (multipart, `file`) | `POST /api/companies/:companyId/issues/:issueId/attachments`                                                                    |
+| List / get / delete attachment        | `GET /api/issues/:issueId/attachments` • `GET\|DELETE /api/attachments/:attachmentId[/content]`                                 |
+| Execution workspace + runtime         | `GET /api/execution-workspaces/:id` • `POST …/runtime-services/:action`                                                         |
+| Set agent instructions path           | `PATCH /api/agents/:agentId/instructions-path`                                                                                  |
+| List agents                           | `GET /api/companies/:companyId/agents`                                                                                          |
+| Dashboard                             | `GET /api/companies/:companyId/dashboard`                                                                                       |
 
 Full endpoint table (company imports/exports, OpenClaw invites, company skills, routines, etc.) lives in `references/api-reference.md`.
 
@@ -344,3 +353,5 @@ Results are ranked by relevance: title matches first, then identifier, descripti
 ## Full Reference
 
 For detailed API tables, JSON response schemas, worked examples (IC and Manager heartbeats), governance/approvals, cross-team delegation rules, error codes, issue lifecycle diagram, and the common mistakes table, read: `skills/paperclip/references/api-reference.md`
+
+Again, rule #1 is: never ask a human to do what an agent could do. Try harder. Try again. Ask another agent to help. Keep working until the goal is fully accomplished.

package/skills/paperclip/references/api-reference.md

@@ -683,7 +683,8 @@ Rules:
 - Rejection does not wake the assignee by default. The board/user can add a normal comment when revisions are needed.
 - Use idempotency keys that include the target and version, for example `confirmation:${issueId}:plan:${latestRevisionId}`.
 - Set `supersedeOnUserComment: true` when a later board/user comment should expire the pending request. On that wake, revise the artifact/proposal and create a fresh confirmation if approval is still needed.
-- For plan approval, update the `plan` issue document first, create the confirmation against the latest plan revision, and wait for acceptance before creating implementation subtasks.
+- A pending interaction is an explicit waiting path. Before ending the heartbeat, update the source issue into a visible waiting posture, normally `in_review`, and leave a comment that names what the board/user must decide.
+- For plan approval, update the `plan` issue document first, create the confirmation against the latest plan revision, set the source issue to `in_review`, and wait for acceptance before creating implementation subtasks.
 
 ### Checking approval status
 
@@ -724,7 +725,7 @@ Terminal states: `done`, `cancelled`
 - `backlog` = not ready to execute yet.
 - `todo` = ready to execute, but not actively checked out yet.
 - `in_progress` = actively owned work. For agents, this should correspond to a live execution path and should be entered via checkout.
-- `in_review` = waiting on review or approval action, not active execution.
+- `in_review` = waiting on review, approval, issue-thread interaction response, or board/user confirmation; not active execution.
 - `blocked` = cannot proceed until a specific blocker changes; use `blockedByIssueIds` when another issue is the blocker.
 - `done` = completed.
 - `cancelled` = intentionally abandoned.
@@ -733,6 +734,9 @@ Terminal states: `done`, `cancelled`
 - `completed_at` is auto-set on `done`.
 - One assignee per task at a time.
 - `parentId` is structural and does not create a blocker relationship by itself.
+- Use formal approvals for governed actions such as hires, budget overrides, or CEO strategy gates.
+- Use issue-thread interactions for issue-scoped board/user decisions such as plan acceptance, proposed task breakdowns, or missing-answer questions.
+- Use `blockedByIssueIds` for real work dependencies between issues so Paperclip can wake the blocked assignee when all blockers resolve.
 
 ---
 

package/skills/paperclip-converting-plans-to-tasks/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: paperclip-converting-plans-to-tasks
+description: >
+  The Paperclip way of converting a plan into executable tasks. Use whenever
+  you are asked to plan, scope, or break down work inside a Paperclip company.
+  Industry-agnostic guidance on how to translate a plan into assigned issues
+  with the right specialty, dependencies, and parallelization so Paperclip's
+  executor can pick up the work — it does not prescribe a plan format. Pair
+  with the `paperclip` skill, which covers the mechanics of writing the plan
+  document and reassigning the issue.
+---
+
+# Paperclip — Converting Plans to Tasks
+
+A companion skill for turning a plan into executable Paperclip work. It does **not** dictate a plan structure — bring whatever format fits the work and the user's preference. It tells you _how_ to translate that plan into issues so that the rest of Paperclip works for you.
+
+For the **mechanics** of recording a plan (issue document with key `plan`, comment links, approval gating, who to reassign back to), follow the _Planning_ section of the `paperclip` skill. This skill covers planning method, not the API surface.
+
+## When you're asked to plan
+
+- **Plan deeply.** Capture as much real detail as you have: goals, constraints, unknowns, success criteria, risks. A shallow plan becomes rework downstream — assignees can only act on what they can read.
+- **Know your team.** Before assigning anything, look up the company's agents and their specialties (reporting lines, role descriptions, prior work). Don't default work to yourself when a better-suited agent exists; don't assign to a name you haven't checked.
+- **Assign for specialty.** Hand each piece of work to the agent most relevant to it. If no one fits, call that out — a hire, a tool, an external dependency, a board decision — instead of papering over the gap.
+- **Take responsibility.** Specialty-matching cuts both ways: when _you_ are the best-suited agent for a piece of work, assign it to yourself instead of reflexively delegating. Don't hand off to avoid load.
+- **Use the dependency tree.** Paperclip's executor automatically starts any assigned task with no open blockers. Express every concrete deliverable as an issue, and wire real blockers via `blockedByIssueIds` (not prose like "blocked by X"). When `done`, dependents auto-wake.
+- **Order, then parallelize.** Sequence work by real dependencies, not by personal preference. Independent branches of the graph should start in parallel. Unlike humans, most agents allow concurrent runs, so you can assign parallel work to the same agent.
+- **Enough is enough.** Plans exist to unblock execution, not replace it. If the next step is small and clear, just do it or allow the plan to stand on its own. Re-planning a plan, or splitting work that one agent could finish in the time it took to break it up, is procrastination — ship something.
+
+## Quick checklist before you publish a plan
+
+- [ ] Enough detail that assignees can act without re-asking.
+- [ ] Every concrete deliverable is an issue (or named as a known follow-up).
+- [ ] Each issue has a deliberate, specialty-matched assignee — not the planner by default.
+- [ ] Each issue's real blockers are declared via `blockedByIssueIds`.
+- [ ] Independent branches can start in parallel.
+- [ ] Gaps (missing skills, hires, decisions, external inputs) are surfaced, not hidden.
+
+## What this skill is not
+
+- Not a plan template. Use any format — prose, outline, table, RACI, Gantt, whatever fits.
+- Not software-development–specific. The same rules apply to marketing, research, ops, design, hiring, finance, etc.
+- Not a replacement for the `paperclip` skill's planning mechanics. Use both.

package/skills/paperclip-create-agent/SKILL.md

@@ -83,9 +83,9 @@ curl -sS "$PAPERCLIP_API_URL/llms/agent-icons.txt" \
 - leave timer heartbeats off by default; only set `runtimeConfig.heartbeat.enabled=true` with an `intervalSec` when the role genuinely needs scheduled recurring work or the user explicitly asked for it
 - if the role may handle private advisories or sensitive disclosures, confirm a confidential workflow exists first (dedicated skill or documented manual process)
 - capabilities
-- run prompt in adapter config (`promptTemplate` where applicable)
+- managed instructions bundle (`AGENTS.md`) for adapters that support it; avoid durable `promptTemplate` config
 - for coding or execution agents, include the Paperclip execution contract: start actionable work in the same heartbeat; do not stop at a plan unless planning was requested; leave durable progress with a clear next action; use child issues for long or parallel delegated work instead of polling; mark blocked work with owner/action; respect budget, pause/cancel, approval gates, and company boundaries
-- instruction text such as `AGENTS.md` built from step 4; for local managed-bundle adapters, put the adapted `AGENTS.md` content in `adapterConfig.promptTemplate` unless you are a board user intentionally managing bundle paths/files
+- instruction text such as `AGENTS.md` built from step 4; for local managed-bundle adapters, send this as top-level `instructionsBundle.files["AGENTS.md"]`. Do not set `adapterConfig.promptTemplate` or `bootstrapPromptTemplate` for new agents.
 - source issue linkage (`sourceIssueId` or `sourceIssueIds`) when this hire came from an issue
 
 ### 7. Review the draft against the quality checklist
@@ -109,6 +109,7 @@ curl -sS -X POST "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/agent-h
     "desiredSkills": ["vercel-labs/agent-browser/agent-browser"],
     "adapterType": "codex_local",
     "adapterConfig": {"cwd": "/abs/path/to/repo", "model": "o4-mini"},
+    "instructionsBundle": {"files": {"AGENTS.md": "You are the CTO..."}},
     "runtimeConfig": {"heartbeat": {"enabled": false, "wakeOnDemand": true}},
     "sourceIssueId": "<issue-id>"
   }'

package/skills/paperclip-create-agent/references/agent-instruction-templates.md

@@ -41,7 +41,7 @@ If you are hiring a role that is not in this index, do not force a fit. Use the
 ## How to apply an exact template
 
 1. Open the matching reference in `references/agents/`.
-2. Copy that template into the new agent's instruction bundle (usually `AGENTS.md`). For hire requests using local managed-bundle adapters, set the adapted template as `adapterConfig.promptTemplate`; Paperclip materializes it into `AGENTS.md`.
+2. Copy that template into the new agent's instruction bundle (usually `AGENTS.md`). For hire requests using local managed-bundle adapters, send the adapted template as top-level `instructionsBundle.files["AGENTS.md"]`. Do not put new-agent instructions in `adapterConfig.promptTemplate`.
 3. Replace placeholders like `{{companyName}}`, `{{managerTitle}}`, `{{issuePrefix}}`, and URLs.
 4. Remove tools or workflows the target adapter cannot use.
 5. Keep the Paperclip heartbeat requirement and the task-comment requirement.

package/skills/paperclip-create-agent/references/api-reference.md

@@ -42,8 +42,13 @@ Request body matches agent create shape:
   "adapterType": "claude_local",
   "adapterConfig": {
     "cwd": "/absolute/path",
-    "model": "claude-sonnet-4-5-20250929",
-    "promptTemplate": "You are CTO..."
+    "model": "claude-sonnet-4-5-20250929"
+  },
+  "instructionsBundle": {
+    "entryFile": "AGENTS.md",
+    "files": {
+      "AGENTS.md": "You are CTO..."
+    }
   },
   "runtimeConfig": {
     "heartbeat": {

package/skills/paperclip-create-agent/references/baseline-role-guide.md

@@ -118,7 +118,7 @@ How the agent verifies its own work before marking an issue done or handing it t
 - **Over-generic prompts.** "Be helpful, be thorough, be correct" is worthless — the next agent drafts a better version by reading the template you adapted from. Write role-specific guidance only.
 - **Lens dumping.** Copying every lens from an expert template into an unrelated role adds noise and burns context. Five well-chosen lenses beat fifteen irrelevant ones.
 - **Permission sprawl.** Do not grant write access, admin endpoints, or broad skill sets "just in case." Grant exactly what the role needs.
-- **Secrets in adapter config.** Do not embed long-lived tokens, API keys, or private URLs in `adapterConfig` or `promptTemplate` when environment injection or a scoped skill can carry the capability instead.
+- **Secrets in agent config.** Do not embed long-lived tokens, API keys, or private URLs in `adapterConfig`, `instructionsBundle`, or legacy prompt fields when environment injection or a scoped skill can carry the capability instead.
 - **Silent timer heartbeats.** A timer heartbeat burns budget every interval. If the role has no scheduled work, leave it off.
 - **Bypassing governance.** Never skip `sourceIssueId`, reporting line, icon, or approval flow to ship faster. Hires without these are hard to audit and hard to hand off.
 - **Copying another company's prompt verbatim.** Placeholders like `{{companyName}}`, `{{managerTitle}}`, and `{{issuePrefix}}` must be replaced with this company's values before submitting the hire.

package/skills/paperclip-create-agent/references/draft-review-checklist.md

@@ -57,13 +57,13 @@ Use it for every path: exact template, adjacent template, or generic fallback.
 - [ ] `sourceIssueId` (or `sourceIssueIds`) is set when the hire was triggered by an issue
 - [ ] `desiredSkills` lists only skills that already exist in the company library, or will be installed first via the company-skills workflow
 - [ ] Adapter config matches this Paperclip instance (cwd, model, credentials) per `/llms/agent-configuration/<adapter>.txt`
-- [ ] `adapterConfig.promptTemplate` holds the adapted `AGENTS.md` for local managed-bundle adapters (unless you are intentionally managing bundle paths)
+- [ ] Local managed-bundle adapters send custom instructions through top-level `instructionsBundle.files["AGENTS.md"]` and do not set `adapterConfig.promptTemplate` or `bootstrapPromptTemplate`
 - [ ] Placeholders like `{{companyName}}`, `{{managerTitle}}`, `{{issuePrefix}}`, and any URL stubs are replaced with real values
 
 ## H. Safety and permissions (least privilege)
 
 - [ ] The hire grants only the access the role needs — no "just in case" permissions
-- [ ] No secrets are embedded in plain text in `adapterConfig` or `promptTemplate` unless the adapter explicitly requires it; prefer environment-injected credentials or scoped skills
+- [ ] No secrets are embedded in plain text in `adapterConfig`, `instructionsBundle`, or any legacy prompt field; prefer environment-injected credentials or scoped skills
 - [ ] Any `desiredSkills` or adapter settings that expand external-system access, browser/network reach, filesystem scope, or secret-handling capability are individually justified in the hire comment
 - [ ] `runtimeConfig.heartbeat.enabled` is `false` unless the role genuinely needs scheduled recurring work AND `intervalSec` is justified in the hire comment
 - [ ] `AGENTS.md` explicitly names anything the role must never do (external posts, shared infra changes, destructive ops without approval)

package/skills/paperclip-dev/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: paperclip-dev
+required: false
+description: >
+  Develop and operate a local Paperclip instance — start and stop servers,
+  pull updates from master, run builds and tests, manage worktrees, back up
+  databases, and diagnose problems. Use whenever you need to work on the
+  Paperclip codebase itself or keep a running instance healthy.
+---
+
+# Paperclip Dev
+
+This skill covers the day-to-day workflows for developing and operating a local Paperclip instance. It assumes you are working inside the Paperclip repo checkout with `origin` pointing to `git@github.com:paperclipai/paperclip.git`.
+
+> **OPEN SOURCE HYGIENE:** This repository is public-facing. Treat anything you push to `origin` as publishable. Never commit or push secrets, API keys, tokens, private logs, PII, customer data, or machine-local configuration that should stay private. Keep git history tidy as well: avoid pushing throwaway branches, noisy checkpoint commits, or speculative work that does not need to be shared upstream.
+
+> **MANDATORY:** Before running any CLI command, building, testing, or managing worktrees, you MUST read `doc/DEVELOPING.md` in the Paperclip repo. It is the canonical reference for all `paperclipai` CLI commands, their options, build/test workflows, database operations, worktree management, and diagnostics. Do NOT guess at flags or options — read the doc first.
+
+## Quick Command Reference
+
+These are the most common commands. For full option tables and details, see `doc/DEVELOPING.md`.
+
+| Task | Command |
+|------|---------|
+| Start server (first time or normal) | `npx paperclipai run` |
+| Dev mode with hot reload | `pnpm dev` |
+| Stop dev server | `pnpm dev:stop` |
+| Build | `pnpm build` |
+| Type-check | `pnpm typecheck` |
+| Run tests | `pnpm test` |
+| Run migrations | `pnpm db:migrate` |
+| Regenerate Drizzle client | `pnpm db:generate` |
+| Back up database | `npx paperclipai db:backup` |
+| Health check | `npx paperclipai doctor --repair` |
+| Print env vars | `npx paperclipai env` |
+| Trigger agent heartbeat | `npx paperclipai heartbeat run --agent-id <id>` |
+| Install agent skills locally | `npx paperclipai agent local-cli <agent> --company-id <id>` |
+
+## Pulling from Master
+
+```bash
+git fetch origin && git pull origin master
+pnpm install && pnpm build
+```
+
+If schema changes landed, also run `pnpm db:generate && pnpm db:migrate`.
+
+## Worktrees
+
+Paperclip worktrees combine git worktrees with isolated Paperclip instances — each gets its own database, server port, and environment seeded from the primary instance.
+
+> **MANDATORY:** Before creating or managing worktrees, you MUST read the "Worktree-local Instances" and "Worktree CLI Reference" sections in `doc/DEVELOPING.md`. That is the canonical reference for all worktree commands, their options, seed modes, and environment variables.
+
+### When to Use Worktrees
+
+- Starting a feature branch that needs its own Paperclip environment
+- Running parallel agent work without cross-contaminating the primary instance
+- Testing Paperclip changes in isolation before merging
+
+### Command Overview
+
+The CLI has two tiers (see `doc/DEVELOPING.md` for full option tables):
+
+| Command | Purpose |
+|---------|---------|
+| `worktree:make <name>` | Create worktree + isolated instance in one step |
+| `worktree:list` | List worktrees and their Paperclip status |
+| `worktree:merge-history` | Preview/import issue history between worktrees |
+| `worktree:cleanup <name>` | Remove worktree, branch, and instance data |
+| `worktree init` | Bootstrap instance inside existing worktree |
+| `worktree env` | Print shell exports for worktree instance |
+| `worktree reseed` | Refresh worktree DB from another instance |
+| `worktree repair` | Fix broken/missing worktree instance metadata |
+
+### Typical Workflow
+
+```bash
+# 1. Create a worktree for a feature
+npx paperclipai worktree:make my-feature --start-point origin/main
+
+# 2. Move into the worktree (path printed by worktree:make) and source the environment
+cd <worktree-path>
+eval "$(npx paperclipai worktree env)"
+
+# 3. Start the isolated Paperclip server
+npx paperclipai run
+
+# 4. Do your work
+
+# 5. When done, merge history back if needed
+npx paperclipai worktree:merge-history --from paperclip-my-feature --to current --apply
+
+# 6. Clean up
+npx paperclipai worktree:cleanup my-feature
+```
+
+## Forks — Prefer Pushing to a User Fork
+
+If the user has a personal fork of `paperclipai/paperclip` configured as a git remote, push your feature branches to **that fork** instead of creating branches on the main repo. This keeps the upstream branch list clean and matches the standard open-source contribution flow.
+
+### Detect a fork remote
+
+Before pushing or creating a PR, list remotes and check for one that points at a non-`paperclipai` GitHub fork:
+
+```bash
+git remote -v
+```
+
+Treat any remote whose URL points to `github.com:<user>/paperclip` (or `github.com/<user>/paperclip.git`) as the user's fork. Common names are `fork`, `<username>`, or `myfork`. The remote named `origin` or `upstream` that points at `paperclipai/paperclip` is the canonical upstream — do not push feature branches there if a fork exists.
+
+### Pushing to the fork
+
+```bash
+# Push the current branch to the user's fork and set upstream
+git push -u <fork-remote> HEAD
+```
+
+Then create the PR from the fork branch:
+
+```bash
+gh pr create --repo paperclipai/paperclip --head <fork-owner>:<branch-name> ...
+```
+
+`gh pr create` usually figures out the head ref automatically when run from a branch tracking the fork; the explicit `--head <owner>:<branch>` form is the reliable fallback when it does not.
+
+### When no fork exists
+
+If `git remote -v` shows only `paperclipai/paperclip` remotes (no user fork), fall back to pushing branches to `origin` as before. Do NOT create a fork on the user's behalf — ask first.
+
+### Keeping the fork up to date
+
+The canonical remote that points at `paperclipai/paperclip` may be named `origin` **or** `upstream` depending on how the user set up the repo. Detect it the same way as in the "Detect a fork remote" step, then fetch and push from/with that remote so the sync works under either convention:
+
+```bash
+UPSTREAM_REMOTE=$(git remote -v | awk '/paperclipai\/paperclip.*\(fetch\)/{print $1; exit}')
+git fetch "$UPSTREAM_REMOTE"
+git push <fork-remote> "${UPSTREAM_REMOTE}/master:master"
+```
+
+## Pull Requests
+
+> **MANDATORY PRE-FLIGHT:** Before creating ANY pull request, you MUST read the canonical source files listed below. Do NOT run `gh pr create` until you have read these files and verified your PR body matches every required section.
+
+### Step 1 — Read the canonical files
+
+You MUST read all three of these files before creating a PR:
+
+1. **`.github/PULL_REQUEST_TEMPLATE.md`** — the required PR body structure
+2. **`CONTRIBUTING.md`** — contribution conventions, PR requirements, and thinking-path examples
+3. **`.github/workflows/pr.yml`** — CI checks that gate merge
+
+### Step 2 — Validate your PR body against this checklist
+
+After reading the template, verify your `--body` includes every one of these sections (names must match exactly):
+
+- [ ] `## Thinking Path` — blockquote style, 5-8 reasoning steps
+- [ ] `## What Changed` — bullet list of concrete changes
+- [ ] `## Verification` — how a reviewer confirms this works
+- [ ] `## Risks` — what could go wrong
+- [ ] `## Model Used` — provider, model ID, version, capabilities
+- [ ] `## Checklist` — copied from the template, items checked off
+
+If any section is missing or empty, do NOT submit the PR. Go back and fill it in.
+
+### Step 3 — Create the PR
+
+Only after completing Steps 1 and 2, run `gh pr create`. Use the template contents as the structure for `--body` — do not write a freeform summary.
+
+## Hard Rules — Do NOT Bypass
+
+These rules exist because agents have caused real damage by improvising around CLI failures. Follow them exactly.
+
+1. **CLI is the only interface to worktrees and databases.** All worktree and database operations MUST go through `npx paperclipai` / `pnpm paperclipai` commands. You MUST NOT:
+   - Run `pg_dump`, `pg_restore`, `psql`, `createdb`, `dropdb`, or any raw postgres commands
+   - Manually set `DATABASE_URL` to point a worktree server at another instance's database
+   - Run `rm -rf` on any `.paperclip/`, `.paperclip-worktrees/`, or `db/` directory
+   - Directly manipulate embedded postgres data directories
+   - Kill postgres processes by PID
+
+2. **If a CLI command fails, stop and report.** Do NOT attempt workarounds. If `worktree:make`, `worktree reseed`, `worktree init`, `worktree:cleanup`, or any other `paperclipai` command fails:
+   - Report the exact error message in your task comment
+   - Set the task to `blocked`
+   - Suggest running `npx paperclipai doctor --repair` or recreating the worktree from scratch
+   - Do NOT try to manually replicate what the CLI does
+
+3. **Never share databases between instances.** Each worktree instance gets its own isolated database. Never override `DATABASE_URL` to point one instance at another's database. This destroys isolation and can corrupt production data.
+
+4. **Starting a dev server in a worktree requires setup first.** The correct sequence is:
+   ```bash
+   # If the worktree already exists but has no running instance:
+   cd <worktree-path>
+   eval "$(npx paperclipai worktree env)"
+   pnpm install && pnpm build
+   npx paperclipai run          # or pnpm dev
+
+   # If the worktree needs a fresh database:
+   npx paperclipai worktree reseed --seed-mode full
+
+   # If the worktree is broken beyond repair:
+   npx paperclipai worktree:cleanup <name>
+   npx paperclipai worktree:make <name> --seed-mode full
+   ```
+   If any step fails, follow rule 2 — stop and report.
+
+5. **Seeding is a CLI operation.** When asked to seed a worktree database from the main instance, use `worktree reseed` or recreate with `worktree:make --seed-mode full`. Read `doc/DEVELOPING.md` for the full option tables. Never attempt manual database copying.
+
+## Persistent Dev Servers (for Manual Testing)
+
+When an agent needs to start a dev server that outlives the current heartbeat — for example, so a human or QA agent can manually test against it — the server process **must** be launched in a detached session. A process started directly from a heartbeat shell is killed when the heartbeat exits.
+
+### Use `tmux` for persistent servers
+
+```bash
+# 1. cd into the worktree (or main repo) and source the environment
+cd <worktree-path>
+eval "$(npx paperclipai worktree env)"   # skip if using the primary instance
+
+# 2. Start the dev server in a named, detached tmux session
+tmux new-session -d -s <session-name> 'pnpm dev'
+
+# Example with a descriptive name:
+tmux new-session -d -s auth-fix-3102 'pnpm dev'
+```
+
+### Managing the session
+
+| Task | Command |
+|------|---------|
+| Check if the session is alive | `tmux has-session -t <session-name> 2>/dev/null && echo running` |
+| View server output | `tmux capture-pane -t <session-name> -p` |
+| Kill the session | `tmux kill-session -t <session-name>` |
+| List all tmux sessions | `tmux list-sessions` |
+
+### Verifying the server is reachable
+
+After launching, confirm the port is listening before reporting success:
+
+```bash
+# Wait briefly for startup, then verify
+sleep 3
+curl -sf http://127.0.0.1:<port>/api/health && echo "Server is up"
+lsof -nP -iTCP:<port> -sTCP:LISTEN
+```
+
+### Key rules
+
+1. **Always use `tmux` (or equivalent)** when a dev server needs to stay running after the heartbeat ends. A server started directly from the agent shell will die when the heartbeat exits, even if it appeared healthy moments before.
+2. **Name the session descriptively** — include the worktree name and port (e.g., `auth-fix-3102`).
+3. **Verify the server is listening** before reporting the URL to anyone.
+4. **Do not use `nohup` or `&` alone** — these are unreliable for agent shells that may have their entire process group killed.
+5. **Clean up when done** — kill the tmux session when the testing is complete.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Server won't start | Run `npx paperclipai doctor --repair` to diagnose and auto-fix |
+| Forgetting to source worktree env | Run `eval "$(npx paperclipai worktree env)"` after cd-ing into the worktree |
+| Stale dependencies after pull | Run `pnpm install && pnpm build` after pulling |
+| Schema out of date after pull | Run `pnpm db:generate && pnpm db:migrate` |
+| Reseeding while target DB is running | Stop the target server first, or use `--allow-live-target` |
+| Cleaning up with unmerged commits | Merge or push first, or use `--force` if intentionally discarding |
+| Running agents against wrong instance | Verify `PAPERCLIP_API_URL` points to the correct port |
+| CLI command fails | Do NOT work around it — report the error and block (see Hard Rules above) |
+| Agent tries manual postgres operations | NEVER do this — all DB ops go through the CLI (see Hard Rules above) |
+| Dev server dies between heartbeats | Launch in a detached `tmux` session — see "Persistent Dev Servers" above |
+| Pushed feature branch to `paperclipai/paperclip` when a fork exists | Push to the user's fork remote instead — see "Forks" above |