From 01b550d61a1e11921f534afd9cc72d97515648c7 Mon Sep 17 00:00:00 2001 From: dotta Date: Thu, 26 Mar 2026 01:06:27 -0500 Subject: [PATCH 1/4] docs: fix SPEC accuracy for adapters and backend - align adapter list with current built-in adapters - update backend framework references to Express - remove outdated V1 not-supported template export claim - clarify work artifact boundaries with issue documents Co-Authored-By: Paperclip --- doc/SPEC.md | 31 +++++++++++++++++-------------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/doc/SPEC.md b/doc/SPEC.md index 82315bce..671431bb 100644 --- a/doc/SPEC.md +++ b/doc/SPEC.md @@ -186,17 +186,21 @@ The heartbeat is a protocol, not a runtime. Paperclip defines how to initiate an ### Execution Adapters -Agent configuration includes an **adapter** that defines how Paperclip invokes the agent. Initial adapters: +Agent configuration includes an **adapter** that defines how Paperclip invokes the agent. Built-in adapters include: -| Adapter | Mechanism | Example | -| -------------------- | ----------------------- | --------------------------------------------- | -| `process` | Execute a child process | `python run_agent.py --agent-id {id}` | -| `http` | Send an HTTP request | `POST https://openclaw.example.com/hook/{id}` | -| `openclaw_gateway` | OpenClaw gateway API | Managed OpenClaw agent via gateway | -| `gemini_local` | Gemini CLI process | Local Gemini CLI with sandbox and approval | -| `hermes_local` | Hermes agent process | Local Hermes agent | +| Adapter | Mechanism | Example | +| ---------------- | -------------------------- | -------------------------------------------------- | +| `process` | Execute a child process | `python run_agent.py --agent-id {id}` | +| `http` | Send an HTTP request | `POST https://openclaw.example.com/hook/{id}` | +| `claude_local` | Local Claude Code process | Claude Code heartbeat worker | +| `codex_local` | Local Codex process | Codex CLI heartbeat worker | +| `opencode_local` | Local OpenCode process | OpenCode heartbeat worker | +| `pi_local` | Local Pi process | Pi CLI heartbeat worker | +| `cursor` | Cursor API/CLI bridge | Cursor-integrated heartbeat worker | +| `openclaw_gateway` | OpenClaw gateway API | Managed OpenClaw agent via gateway | +| `hermes_local` | Local Hermes process | Hermes agent heartbeat worker | -The `process` and `http` adapters ship as defaults. Additional adapters have been added for specific agent runtimes (see list above), and new adapter types can be registered via the plugin system (see Plugin / Extension Architecture). +The `process` and `http` adapters ship as generic defaults. Additional built-in adapters cover common local coding runtimes (see list above), and new adapter types can be registered via the plugin system (see Plugin / Extension Architecture). ### Adapter Interface @@ -376,7 +380,7 @@ Flow: | Layer | Technology | | -------- | ------------------------------------------------------------ | | Frontend | React + Vite | -| Backend | TypeScript + Hono (REST API, not tRPC — need non-TS clients) | +| Backend | TypeScript + Express (REST API, not tRPC — need non-TS clients) | | Database | PostgreSQL (see [doc/DATABASE.md](./doc/DATABASE.md) for details — PGlite embedded for dev, Docker or hosted Supabase for production) | | Auth | [Better Auth](https://www.better-auth.com/) | @@ -406,7 +410,7 @@ No separate "agent API" vs. "board API." Same endpoints, different authorization ### Work Artifacts -Paperclip does **not** manage work artifacts (code repos, file systems, deployments, documents). That's entirely the agent's domain. Paperclip tracks tasks and costs. Where and how work gets done is outside scope. +Paperclip does **not** manage full delivery infrastructure (code repos, deployments, production runtime). It tracks task-linked artifacts (for example issue documents and attachments), while implementation and deployment remain the agent's domain. ### Open Questions @@ -476,15 +480,14 @@ Each is a distinct page/route: - [ ] **Default agent** — basic Claude Code/Codex loop with Paperclip skill - [ ] **Default CEO** — strategic planning, delegation, board communication - [ ] **Paperclip skill (SKILL.md)** — teaches agents to interact with the API -- [ ] **REST API** — full API for agent interaction (Hono) +- [ ] **REST API** — full API for agent interaction (Express) - [ ] **Web UI** — React/Vite: org chart, task board, dashboard, cost views - [ ] **Agent auth** — connection string generation with URL + key + instructions - [ ] **One-command dev setup** — embedded PGlite, everything local -- [ ] **Multiple Adapter types** (HTTP Adapter, OpenClaw Adapter) +- [ ] **Multiple Adapter types** (HTTP, OpenClaw gateway, and local coding adapters) ### Not V1 -- Template export/import - Knowledge base - a future plugin - Advanced governance models (hiring budgets, multi-member boards) - Revenue/expense tracking beyond token costs - a future plugin From 692105e202b75f44cd729862f9a9a4b5135f04dd Mon Sep 17 00:00:00 2001 From: dotta Date: Thu, 26 Mar 2026 06:48:58 -0500 Subject: [PATCH 2/4] docs: update adapter list and repo map accuracy - Add missing adapters (opencode_local, hermes_local, cursor, pi_local, openclaw_gateway) to agents-runtime.md - Document bootstrapPromptTemplate in prompt templates section - Update AGENTS.md repo map with packages/adapters, adapter-utils, plugins - Fix troubleshooting section to reference all local CLI adapters Co-Authored-By: Paperclip --- AGENTS.md | 3 +++ docs/agents-runtime.md | 22 ++++++++++++++-------- 2 files changed, 17 insertions(+), 8 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index dad6684f..bdfa3e5d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,6 +26,9 @@ Before making changes, read in this order: - `ui/`: React + Vite board UI - `packages/db/`: Drizzle schema, migrations, DB clients - `packages/shared/`: shared types, constants, validators, API path constants +- `packages/adapters/`: agent adapter implementations (Claude, Codex, Cursor, etc.) +- `packages/adapter-utils/`: shared adapter utilities +- `packages/plugins/`: plugin system packages - `doc/`: operational and product docs ## 4. Dev Setup (Auto DB) diff --git a/docs/agents-runtime.md b/docs/agents-runtime.md index bda72729..ba9bb122 100644 --- a/docs/agents-runtime.md +++ b/docs/agents-runtime.md @@ -1,7 +1,7 @@ # Agent Runtime Guide -Status: User-facing guide -Last updated: 2026-02-17 +Status: User-facing guide +Last updated: 2026-03-26 Audience: Operators setting up and running agents in Paperclip ## 1. What this system does @@ -32,14 +32,19 @@ If an agent is already running, new wakeups are merged (coalesced) instead of la ## 3.1 Adapter choice -Common choices: +Built-in adapters: - `claude_local`: runs your local `claude` CLI - `codex_local`: runs your local `codex` CLI +- `opencode_local`: runs your local `opencode` CLI +- `hermes_local`: runs your local `hermes` CLI +- `cursor`: runs Cursor in background mode +- `pi_local`: runs an embedded Pi agent locally +- `openclaw_gateway`: connects to an OpenClaw gateway endpoint - `process`: generic shell command adapter - `http`: calls an external HTTP endpoint -For `claude_local` and `codex_local`, Paperclip assumes the CLI is already installed and authenticated on the host machine. +For local CLI adapters (`claude_local`, `codex_local`, `opencode_local`, `hermes_local`), Paperclip assumes the CLI is already installed and authenticated on the host machine. ## 3.2 Runtime behavior @@ -66,6 +71,7 @@ For local adapters, set: You can set: - `promptTemplate`: used for every run (first run and resumed sessions) +- `bootstrapPromptTemplate`: used only on the first run of a new session (before the agent has any prior context) Templates support variables like `{{agent.id}}`, `{{agent.name}}`, and run context values. @@ -133,7 +139,7 @@ If the connection drops, the UI reconnects automatically. If runs fail repeatedly: -1. Check adapter command availability (`claude`/`codex` installed and logged in). +1. Check adapter command availability (e.g. `claude`/`codex`/`opencode`/`hermes` installed and logged in). 2. Verify `cwd` exists and is accessible. 3. Inspect run error + stderr excerpt, then full log. 4. Confirm timeout is not too low. @@ -166,9 +172,9 @@ Start with least privilege where possible, and avoid exposing secrets in broad r ## 10. Minimal setup checklist -1. Choose adapter (`claude_local` or `codex_local`). -2. Set `cwd` to the target workspace. -3. Add bootstrap + normal prompt templates. +1. Choose adapter (e.g. `claude_local`, `codex_local`, `opencode_local`, `hermes_local`, `cursor`, or `openclaw_gateway`). +2. Set `cwd` to the target workspace (for local adapters). +3. Optionally add prompt templates (`promptTemplate` and/or `bootstrapPromptTemplate`). 4. Configure heartbeat policy (timer and/or assignment wakeups). 5. Trigger a manual wakeup. 6. Confirm run succeeds and session/token usage is recorded. From ed73547fb6a096714011de0e30d05657d7b81560 Mon Sep 17 00:00:00 2001 From: dotta Date: Thu, 26 Mar 2026 07:23:09 -0500 Subject: [PATCH 3/4] docs: update SPEC work artifacts and deprecate bootstrapPromptTemplate - SPEC: reflect that Paperclip now manages task-linked documents and attachments (issue documents, file attachments) instead of claiming it does not manage work artifacts - agents-runtime: remove bootstrapPromptTemplate from recommended config, add deprecation notice, update minimal setup checklist Co-Authored-By: Paperclip --- doc/SPEC.md | 4 ++-- docs/agents-runtime.md | 5 +++-- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/doc/SPEC.md b/doc/SPEC.md index 671431bb..6a7039ca 100644 --- a/doc/SPEC.md +++ b/doc/SPEC.md @@ -410,7 +410,7 @@ No separate "agent API" vs. "board API." Same endpoints, different authorization ### Work Artifacts -Paperclip does **not** manage full delivery infrastructure (code repos, deployments, production runtime). It tracks task-linked artifacts (for example issue documents and attachments), while implementation and deployment remain the agent's domain. +Paperclip manages task-linked work artifacts: issue documents (rich-text plans, specs, notes attached to issues) and file attachments. Agents read and write these through the API as part of normal task execution. Full delivery infrastructure (code repos, deployments, production runtime) remains the agent's domain — Paperclip orchestrates the work, not the build pipeline. ### Open Questions @@ -512,7 +512,7 @@ Things Paperclip explicitly does **not** do: - **Not a SaaS** — single-tenant, self-hosted - **Not opinionated about Agent implementation** — any language, any framework, any runtime - **Not automatically self-healing** — surfaces problems, doesn't silently fix them -- **Does not manage work artifacts** — no repo management, no deployment, no file systems +- **Does not manage delivery infrastructure** — no repo management, no deployment, no file systems (but does manage task-linked documents and attachments) - **Does not auto-reassign work** — stale tasks are surfaced, not silently redistributed - **Does not track external revenue/expenses** — that's a future plugin. Token/LLM cost budgeting is core. diff --git a/docs/agents-runtime.md b/docs/agents-runtime.md index ba9bb122..f3672723 100644 --- a/docs/agents-runtime.md +++ b/docs/agents-runtime.md @@ -71,10 +71,11 @@ For local adapters, set: You can set: - `promptTemplate`: used for every run (first run and resumed sessions) -- `bootstrapPromptTemplate`: used only on the first run of a new session (before the agent has any prior context) Templates support variables like `{{agent.id}}`, `{{agent.name}}`, and run context values. +> **Note:** `bootstrapPromptTemplate` is deprecated and should not be used for new agents. Existing configs that use it will continue to work but should be migrated to the managed instructions bundle system. + ## 4. Session resume behavior Paperclip stores session IDs for resumable adapters. @@ -174,7 +175,7 @@ Start with least privilege where possible, and avoid exposing secrets in broad r 1. Choose adapter (e.g. `claude_local`, `codex_local`, `opencode_local`, `hermes_local`, `cursor`, or `openclaw_gateway`). 2. Set `cwd` to the target workspace (for local adapters). -3. Optionally add prompt templates (`promptTemplate` and/or `bootstrapPromptTemplate`). +3. Optionally add a prompt template (`promptTemplate`) or use the managed instructions bundle. 4. Configure heartbeat policy (timer and/or assignment wakeups). 5. Trigger a manual wakeup. 6. Confirm run succeeds and session/token usage is recorded. From eaa765118fcc85a8609f20f93fc2f34f30db9b61 Mon Sep 17 00:00:00 2001 From: dotta Date: Thu, 26 Mar 2026 07:23:44 -0500 Subject: [PATCH 4/4] chore: mark bootstrapPromptTemplate as deprecated Add @deprecated JSDoc and inline comments to bootstrapPromptTemplate references in agent-instructions and company-portability services. This field is superseded by the managed instructions bundle system. Co-Authored-By: Paperclip --- server/src/services/agent-instructions.ts | 1 + server/src/services/company-portability.ts | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/server/src/services/agent-instructions.ts b/server/src/services/agent-instructions.ts index 231ed839..6dcbb38f 100644 --- a/server/src/services/agent-instructions.ts +++ b/server/src/services/agent-instructions.ts @@ -9,6 +9,7 @@ const ROOT_KEY = "instructionsRootPath"; const ENTRY_KEY = "instructionsEntryFile"; const FILE_KEY = "instructionsFilePath"; const PROMPT_KEY = "promptTemplate"; +/** @deprecated Use the managed instructions bundle system instead. */ const BOOTSTRAP_PROMPT_KEY = "bootstrapPromptTemplate"; const LEGACY_PROMPT_TEMPLATE_PATH = "promptTemplate.legacy.md"; const IGNORED_INSTRUCTIONS_FILE_NAMES = new Set([".DS_Store", "Thumbs.db", "Desktop.ini"]); diff --git a/server/src/services/company-portability.ts b/server/src/services/company-portability.ts index 7cfe8ffa..db4be18a 100644 --- a/server/src/services/company-portability.ts +++ b/server/src/services/company-portability.ts @@ -1475,7 +1475,7 @@ function normalizePortableConfig( key === "instructionsRootPath" || key === "instructionsEntryFile" || key === "promptTemplate" || - key === "bootstrapPromptTemplate" || + key === "bootstrapPromptTemplate" || // deprecated — kept for backward compat key === "paperclipSkillSync" ) continue; if (key === "env") continue; @@ -3895,7 +3895,7 @@ export function companyPortabilityService(db: Db, storage?: StorageService) { desiredSkills, ); delete adapterConfigWithSkills.promptTemplate; - delete adapterConfigWithSkills.bootstrapPromptTemplate; + delete adapterConfigWithSkills.bootstrapPromptTemplate; // deprecated delete adapterConfigWithSkills.instructionsFilePath; delete adapterConfigWithSkills.instructionsBundleMode; delete adapterConfigWithSkills.instructionsRootPath;