diff --git a/doc/CLI.md b/doc/CLI.md index 04a953d1..c8da955a 100644 --- a/doc/CLI.md +++ b/doc/CLI.md @@ -84,8 +84,21 @@ export PAPERCLIP_API_KEY=... ```sh pnpm paperclip company list pnpm paperclip company get +pnpm paperclip company delete --yes --confirm ``` +Examples: + +```sh +pnpm paperclip company delete PAP --yes --confirm PAP +pnpm paperclip company delete 5cbe79ee-acb3-4597-896e-7662742593cd --yes --confirm 5cbe79ee-acb3-4597-896e-7662742593cd +``` + +Notes: + +- Deletion is server-gated by `PAPERCLIP_ENABLE_COMPANY_DELETION`. +- With agent authentication, company deletion is company-scoped. Use the current company ID/prefix (for example via `--company-id` or `PAPERCLIP_COMPANY_ID`), not another company. + ## Issue Commands ```sh diff --git a/doc/DEVELOPING.md b/doc/DEVELOPING.md index be0c845e..d949d44f 100644 --- a/doc/DEVELOPING.md +++ b/doc/DEVELOPING.md @@ -170,6 +170,19 @@ pnpm secrets:migrate-inline-env # dry run pnpm secrets:migrate-inline-env --apply # apply migration ``` +## Company Deletion Toggle + +Company deletion is intended as a dev/debug capability and can be disabled at runtime: + +```sh +PAPERCLIP_ENABLE_COMPANY_DELETION=false +``` + +Default behavior: + +- `local_trusted`: enabled +- `authenticated`: disabled + ## CLI Client Operations Paperclip CLI now includes client-side control-plane commands in addition to setup commands. diff --git a/doc/SPEC-implementation.md b/doc/SPEC-implementation.md index 9cccfd99..430dcabb 100644 --- a/doc/SPEC-implementation.md +++ b/doc/SPEC-implementation.md @@ -809,3 +809,25 @@ V1 is complete only when all criteria are true: - milestones/labels/dependency graph depth beyond V1 minimum - realtime transport optimization (SSE/WebSockets) - public template marketplace integration (ClipHub) + +## 21. Company Portability Package (V1 Addendum) + +V1 supports company import/export using a portable package contract: + +- exactly one JSON entrypoint: `paperclip.manifest.json` +- all other package files are markdown with frontmatter +- agent convention: + - `agents//AGENTS.md` (required for V1 export/import) + - `agents//HEARTBEAT.md` (optional, import accepted) + - `agents//*.md` (optional, import accepted) + +Export/import behavior in V1: + +- export includes company metadata and/or agents based on selection +- export strips environment-specific paths (`cwd`, local instruction file paths) +- export never includes secret values; secret requirements are reported +- import supports target modes: + - create a new company + - import into an existing company +- import supports collision strategies: `rename`, `skip`, `replace` +- import supports preview (dry-run) before apply diff --git a/doc/plans/cursor-cloud-adapter.md b/doc/plans/cursor-cloud-adapter.md index 72f6aebf..125c5776 100644 --- a/doc/plans/cursor-cloud-adapter.md +++ b/doc/plans/cursor-cloud-adapter.md @@ -150,7 +150,7 @@ V1 config fields: - `model` (optional, allow empty = auto) - `autoCreatePr` (optional, default `false`) - `branchName` (optional) -- `promptTemplate` / `bootstrapPromptTemplate` +- `promptTemplate` - `pollIntervalSec` (optional, default `10`) - `timeoutSec` (optional, default `0`) - `graceSec` (optional, default `20`) @@ -474,4 +474,3 @@ Current process-only cancellation maps are insufficient by themselves for Cursor - [ ] `pnpm -r typecheck` - [ ] `pnpm test:run` - [ ] `pnpm build` - diff --git a/doc/spec/agent-runs.md b/doc/spec/agent-runs.md index c8acd4c6..4c172c7b 100644 --- a/doc/spec/agent-runs.md +++ b/doc/spec/agent-runs.md @@ -248,7 +248,6 @@ Runs local `claude` CLI directly. { "cwd": "/absolute/or/relative/path", "promptTemplate": "You are agent {{agent.id}} ...", - "bootstrapPromptTemplate": "Initial setup instructions (optional)", "model": "optional-model-id", "maxTurnsPerRun": 80, "dangerouslySkipPermissions": true, @@ -286,7 +285,6 @@ Runs local `codex` CLI directly. { "cwd": "/absolute/or/relative/path", "promptTemplate": "You are agent {{agent.id}} ...", - "bootstrapPromptTemplate": "Initial setup instructions (optional)", "model": "optional-model-id", "search": false, "dangerouslyBypassApprovalsAndSandbox": true, @@ -569,14 +567,10 @@ Rules: ## 10.3 Prompt fields -1. `bootstrapPromptTemplate` - - Used when no session exists. -2. `promptTemplate` - - Used on every wakeup. +1. `promptTemplate` + - Used on every wakeup (first run and resumed runs). - Can include run source/reason pills. -If `bootstrapPromptTemplate` is omitted, `promptTemplate` is used for first run. - ## 10.4 UI requirements 1. Agent setup/edit form includes prompt editors with pill insertion. diff --git a/doc/spec/agents-runtime.md b/doc/spec/agents-runtime.md index 0dc7a63f..3efeaee2 100644 --- a/doc/spec/agents-runtime.md +++ b/doc/spec/agents-runtime.md @@ -64,8 +64,7 @@ For local adapters, set: You can set: -- `bootstrapPromptTemplate`: used for first run/new session -- `promptTemplate`: used for subsequent resumed runs +- `promptTemplate`: used for every run (first run and resumed sessions) Templates support variables like `{{agent.id}}`, `{{agent.name}}`, and run context values. diff --git a/docs/adapters/claude-local.md b/docs/adapters/claude-local.md index 5e9c9a90..9b09a7fa 100644 --- a/docs/adapters/claude-local.md +++ b/docs/adapters/claude-local.md @@ -3,8 +3,6 @@ title: Claude Local summary: Claude Code local adapter setup and configuration --- -# Claude Local Adapter - The `claude_local` adapter runs Anthropic's Claude Code CLI locally. It supports session persistence, skills injection, and structured output parsing. ## Prerequisites @@ -18,8 +16,7 @@ The `claude_local` adapter runs Anthropic's Claude Code CLI locally. It supports |-------|------|----------|-------------| | `cwd` | string | Yes | Working directory for the agent process | | `model` | string | No | Claude model to use (e.g. `claude-opus-4-6`) | -| `promptTemplate` | string | No | Prompt for resumed sessions | -| `bootstrapPromptTemplate` | string | No | Prompt for first run (no existing session) | +| `promptTemplate` | string | No | Prompt used for all runs | | `env` | object | No | Environment variables (supports secret refs) | | `timeoutSec` | number | No | Process timeout (0 = no timeout) | | `graceSec` | number | No | Grace period before force-kill | diff --git a/docs/adapters/codex-local.md b/docs/adapters/codex-local.md index 8f992f73..79f5f873 100644 --- a/docs/adapters/codex-local.md +++ b/docs/adapters/codex-local.md @@ -3,8 +3,6 @@ title: Codex Local summary: OpenAI Codex local adapter setup and configuration --- -# Codex Local Adapter - The `codex_local` adapter runs OpenAI's Codex CLI locally. It supports session persistence via `previous_response_id` chaining and skills injection through the global Codex skills directory. ## Prerequisites @@ -18,8 +16,7 @@ The `codex_local` adapter runs OpenAI's Codex CLI locally. It supports session p |-------|------|----------|-------------| | `cwd` | string | Yes | Working directory for the agent process | | `model` | string | No | Model to use | -| `promptTemplate` | string | No | Prompt for resumed sessions | -| `bootstrapPromptTemplate` | string | No | Prompt for first run | +| `promptTemplate` | string | No | Prompt used for all runs | | `env` | object | No | Environment variables (supports secret refs) | | `timeoutSec` | number | No | Process timeout (0 = no timeout) | | `graceSec` | number | No | Grace period before force-kill | diff --git a/docs/adapters/creating-an-adapter.md b/docs/adapters/creating-an-adapter.md index f968ee1b..83029d42 100644 --- a/docs/adapters/creating-an-adapter.md +++ b/docs/adapters/creating-an-adapter.md @@ -3,8 +3,6 @@ title: Creating an Adapter summary: Guide to building a custom adapter --- -# Creating an Adapter - Build a custom adapter to connect Paperclip to any agent runtime. ## Package Structure diff --git a/docs/adapters/http.md b/docs/adapters/http.md index 36ddcb48..53339950 100644 --- a/docs/adapters/http.md +++ b/docs/adapters/http.md @@ -3,8 +3,6 @@ title: HTTP Adapter summary: HTTP webhook adapter --- -# HTTP Adapter - The `http` adapter sends a webhook request to an external agent service. The agent runs externally and Paperclip just triggers it. ## When to Use diff --git a/docs/adapters/overview.md b/docs/adapters/overview.md index 0769f564..126a27d1 100644 --- a/docs/adapters/overview.md +++ b/docs/adapters/overview.md @@ -3,8 +3,6 @@ title: Adapters Overview summary: What adapters are and how they connect agents to Paperclip --- -# Adapters Overview - Adapters are the bridge between Paperclip's orchestration layer and agent runtimes. Each adapter knows how to invoke a specific type of AI agent and capture its results. ## How Adapters Work diff --git a/docs/adapters/process.md b/docs/adapters/process.md index 830af742..6823d5a1 100644 --- a/docs/adapters/process.md +++ b/docs/adapters/process.md @@ -3,8 +3,6 @@ title: Process Adapter summary: Generic shell process adapter --- -# Process Adapter - The `process` adapter executes arbitrary shell commands. Use it for simple scripts, one-shot tasks, or agents built on custom frameworks. ## When to Use diff --git a/docs/agents-runtime.md b/docs/agents-runtime.md index 07558a79..bda72729 100644 --- a/docs/agents-runtime.md +++ b/docs/agents-runtime.md @@ -65,8 +65,7 @@ For local adapters, set: You can set: -- `bootstrapPromptTemplate`: used for first run/new session -- `promptTemplate`: used for subsequent resumed runs +- `promptTemplate`: used for every run (first run and resumed sessions) Templates support variables like `{{agent.id}}`, `{{agent.name}}`, and run context values. diff --git a/docs/api/activity.md b/docs/api/activity.md index afd9c53f..6e43d6db 100644 --- a/docs/api/activity.md +++ b/docs/api/activity.md @@ -3,8 +3,6 @@ title: Activity summary: Activity log queries --- -# Activity API - Query the audit trail of all mutations across the company. ## List Activity diff --git a/docs/api/agents.md b/docs/api/agents.md index b2705f58..371d2563 100644 --- a/docs/api/agents.md +++ b/docs/api/agents.md @@ -3,8 +3,6 @@ title: Agents summary: Agent lifecycle, configuration, keys, and heartbeat invocation --- -# Agents API - Manage AI agents (employees) within a company. ## List Agents diff --git a/docs/api/approvals.md b/docs/api/approvals.md index 5e8f34ac..e4139ece 100644 --- a/docs/api/approvals.md +++ b/docs/api/approvals.md @@ -3,8 +3,6 @@ title: Approvals summary: Approval workflow endpoints --- -# Approvals API - Approvals gate certain actions (agent hiring, CEO strategy) behind board review. ## List Approvals diff --git a/docs/api/authentication.md b/docs/api/authentication.md index 77a16c55..79cf850f 100644 --- a/docs/api/authentication.md +++ b/docs/api/authentication.md @@ -3,8 +3,6 @@ title: Authentication summary: API keys, JWTs, and auth modes --- -# Authentication - Paperclip supports multiple authentication methods depending on the deployment mode and caller type. ## Agent Authentication diff --git a/docs/api/companies.md b/docs/api/companies.md index 0d2d7c72..a0aafae5 100644 --- a/docs/api/companies.md +++ b/docs/api/companies.md @@ -3,8 +3,6 @@ title: Companies summary: Company CRUD endpoints --- -# Companies API - Manage companies within your Paperclip instance. ## List Companies diff --git a/docs/api/costs.md b/docs/api/costs.md index c6eb1af5..144eb3c9 100644 --- a/docs/api/costs.md +++ b/docs/api/costs.md @@ -3,8 +3,6 @@ title: Costs summary: Cost events, summaries, and budget management --- -# Costs API - Track token usage and spending across agents, projects, and the company. ## Report Cost Event diff --git a/docs/api/dashboard.md b/docs/api/dashboard.md index 78153ecc..315b5137 100644 --- a/docs/api/dashboard.md +++ b/docs/api/dashboard.md @@ -3,8 +3,6 @@ title: Dashboard summary: Dashboard metrics endpoint --- -# Dashboard API - Get a health summary for a company in a single call. ## Get Dashboard diff --git a/docs/api/goals-and-projects.md b/docs/api/goals-and-projects.md index 52c95223..35dd20d7 100644 --- a/docs/api/goals-and-projects.md +++ b/docs/api/goals-and-projects.md @@ -3,8 +3,6 @@ title: Goals and Projects summary: Goal hierarchy and project management --- -# Goals and Projects API - Goals define the "why" and projects define the "what" for organizing work. ## Goals diff --git a/docs/api/issues.md b/docs/api/issues.md index 7c65406e..1318b171 100644 --- a/docs/api/issues.md +++ b/docs/api/issues.md @@ -3,8 +3,6 @@ title: Issues summary: Issue CRUD, checkout/release, comments, and attachments --- -# Issues API - Issues are the unit of work in Paperclip. They support hierarchical relationships, atomic checkout, comments, and file attachments. ## List Issues diff --git a/docs/api/overview.md b/docs/api/overview.md index 4ea775c4..416baae3 100644 --- a/docs/api/overview.md +++ b/docs/api/overview.md @@ -3,8 +3,6 @@ title: API Overview summary: Authentication, base URL, error codes, and conventions --- -# API Overview - Paperclip exposes a RESTful JSON API for all control plane operations. ## Base URL diff --git a/docs/api/secrets.md b/docs/api/secrets.md index 84dcc5ff..49a36e0e 100644 --- a/docs/api/secrets.md +++ b/docs/api/secrets.md @@ -3,8 +3,6 @@ title: Secrets summary: Secrets CRUD --- -# Secrets API - Manage encrypted secrets that agents reference in their environment configuration. ## List Secrets diff --git a/docs/cli/control-plane-commands.md b/docs/cli/control-plane-commands.md index 602c1e25..77a4f747 100644 --- a/docs/cli/control-plane-commands.md +++ b/docs/cli/control-plane-commands.md @@ -3,8 +3,6 @@ title: Control-Plane Commands summary: Issue, agent, approval, and dashboard commands --- -# Control-Plane Commands - Client-side commands for managing issues, agents, approvals, and more. ## Issue Commands @@ -37,6 +35,24 @@ pnpm paperclip issue release ```sh pnpm paperclip company list pnpm paperclip company get + +# Export to portable folder package (writes manifest + markdown files) +pnpm paperclip company export --out ./exports/acme --include company,agents + +# Preview import (no writes) +pnpm paperclip company import \ + --from https://github.com///tree/main/ \ + --target existing \ + --company-id \ + --collision rename \ + --dry-run + +# Apply import +pnpm paperclip company import \ + --from ./exports/acme \ + --target new \ + --new-company-name "Acme Imported" \ + --include company,agents ``` ## Agent Commands diff --git a/docs/cli/overview.md b/docs/cli/overview.md index 3d79d3c6..b2166d57 100644 --- a/docs/cli/overview.md +++ b/docs/cli/overview.md @@ -3,8 +3,6 @@ title: CLI Overview summary: CLI installation and setup --- -# CLI Overview - The Paperclip CLI handles instance setup, diagnostics, and control-plane operations. ## Usage diff --git a/docs/cli/setup-commands.md b/docs/cli/setup-commands.md index 2517773f..22d875c0 100644 --- a/docs/cli/setup-commands.md +++ b/docs/cli/setup-commands.md @@ -3,8 +3,6 @@ title: Setup Commands summary: Onboard, run, doctor, and configure --- -# Setup Commands - Instance setup and diagnostics commands. ## `paperclip run` diff --git a/docs/deploy/database.md b/docs/deploy/database.md index 8e507bc1..a454de9b 100644 --- a/docs/deploy/database.md +++ b/docs/deploy/database.md @@ -3,8 +3,6 @@ title: Database summary: Embedded PGlite vs Docker Postgres vs hosted --- -# Database - Paperclip uses PostgreSQL via Drizzle ORM. There are three ways to run the database. ## 1. Embedded PostgreSQL (Default) diff --git a/docs/deploy/deployment-modes.md b/docs/deploy/deployment-modes.md index 4d0348c6..b5708635 100644 --- a/docs/deploy/deployment-modes.md +++ b/docs/deploy/deployment-modes.md @@ -3,8 +3,6 @@ title: Deployment Modes summary: local_trusted vs authenticated (private/public) --- -# Deployment Modes - Paperclip supports two runtime modes with different security profiles. ## `local_trusted` diff --git a/docs/deploy/docker.md b/docs/deploy/docker.md index c366bab8..0effd4c7 100644 --- a/docs/deploy/docker.md +++ b/docs/deploy/docker.md @@ -3,8 +3,6 @@ title: Docker summary: Docker Compose quickstart --- -# Docker - Run Paperclip in Docker without installing Node or pnpm locally. ## Compose Quickstart (Recommended) diff --git a/docs/deploy/environment-variables.md b/docs/deploy/environment-variables.md index cbe5571d..bc5e4bcc 100644 --- a/docs/deploy/environment-variables.md +++ b/docs/deploy/environment-variables.md @@ -3,8 +3,6 @@ title: Environment Variables summary: Full environment variable reference --- -# Environment Variables - All environment variables that Paperclip uses for server configuration. ## Server Configuration diff --git a/docs/deploy/local-development.md b/docs/deploy/local-development.md index ae1d8b8a..188facc3 100644 --- a/docs/deploy/local-development.md +++ b/docs/deploy/local-development.md @@ -3,8 +3,6 @@ title: Local Development summary: Set up Paperclip for local development --- -# Local Development - Run Paperclip locally with zero external dependencies. ## Prerequisites diff --git a/docs/deploy/overview.md b/docs/deploy/overview.md index 95a72198..ba4e8aae 100644 --- a/docs/deploy/overview.md +++ b/docs/deploy/overview.md @@ -3,8 +3,6 @@ title: Deployment Overview summary: Deployment modes at a glance --- -# Deployment Overview - Paperclip supports three deployment configurations, from zero-friction local to internet-facing production. ## Deployment Modes diff --git a/docs/deploy/secrets.md b/docs/deploy/secrets.md index 77e865e9..41d4fbc6 100644 --- a/docs/deploy/secrets.md +++ b/docs/deploy/secrets.md @@ -3,8 +3,6 @@ title: Secrets Management summary: Master key, encryption, and strict mode --- -# Secrets Management - Paperclip encrypts secrets at rest using a local master key. Agent environment variables that contain sensitive values (API keys, tokens) are stored as encrypted secret references. ## Default Provider: `local_encrypted` diff --git a/docs/deploy/storage.md b/docs/deploy/storage.md index 99980611..32b1da98 100644 --- a/docs/deploy/storage.md +++ b/docs/deploy/storage.md @@ -3,8 +3,6 @@ title: Storage summary: Local disk vs S3-compatible storage --- -# Storage - Paperclip stores uploaded files (issue attachments, images) using a configurable storage provider. ## Local Disk (Default) diff --git a/docs/docs.json b/docs/docs.json index dbe70691..4b78242e 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -15,128 +15,122 @@ "url": "https://github.com/paperclip-ai/paperclip" } ], - "tabs": [ - { "tab": "Get Started", "url": "start" }, - { "tab": "Guides", "url": "guides" }, - { "tab": "Deploy", "url": "deploy" }, - { "tab": "Adapters", "url": "adapters" }, - { "tab": "API Reference", "url": "api" }, - { "tab": "CLI", "url": "cli" } - ], - "navigation": [ - { - "tab": "Get Started", - "groups": [ - { - "group": "Introduction", - "pages": [ - "start/what-is-paperclip", - "start/quickstart", - "start/core-concepts", - "start/architecture" - ] - } - ] - }, - { - "tab": "Guides", - "groups": [ - { - "group": "Board Operator", - "pages": [ - "guides/board-operator/dashboard", - "guides/board-operator/creating-a-company", - "guides/board-operator/managing-agents", - "guides/board-operator/org-structure", - "guides/board-operator/managing-tasks", - "guides/board-operator/approvals", - "guides/board-operator/costs-and-budgets", - "guides/board-operator/activity-log" - ] - }, - { - "group": "Agent Developer", - "pages": [ - "guides/agent-developer/how-agents-work", - "guides/agent-developer/heartbeat-protocol", - "guides/agent-developer/writing-a-skill", - "guides/agent-developer/task-workflow", - "guides/agent-developer/comments-and-communication", - "guides/agent-developer/handling-approvals", - "guides/agent-developer/cost-reporting" - ] - } - ] - }, - { - "tab": "Deploy", - "groups": [ - { - "group": "Deployment", - "pages": [ - "deploy/overview", - "deploy/local-development", - "deploy/docker", - "deploy/deployment-modes", - "deploy/database", - "deploy/secrets", - "deploy/storage", - "deploy/environment-variables" - ] - } - ] - }, - { - "tab": "Adapters", - "groups": [ - { - "group": "Agent Adapters", - "pages": [ - "adapters/overview", - "adapters/claude-local", - "adapters/codex-local", - "adapters/process", - "adapters/http", - "adapters/creating-an-adapter" - ] - } - ] - }, - { - "tab": "API Reference", - "groups": [ - { - "group": "REST API", - "pages": [ - "api/overview", - "api/authentication", - "api/companies", - "api/agents", - "api/issues", - "api/approvals", - "api/goals-and-projects", - "api/costs", - "api/secrets", - "api/activity", - "api/dashboard" - ] - } - ] - }, - { - "tab": "CLI", - "groups": [ - { - "group": "CLI Reference", - "pages": [ - "cli/overview", - "cli/setup-commands", - "cli/control-plane-commands" - ] - } - ] - } - ], + "navigation": { + "tabs": [ + { + "tab": "Get Started", + "groups": [ + { + "group": "Introduction", + "pages": [ + "start/what-is-paperclip", + "start/quickstart", + "start/core-concepts", + "start/architecture" + ] + } + ] + }, + { + "tab": "Guides", + "groups": [ + { + "group": "Board Operator", + "pages": [ + "guides/board-operator/dashboard", + "guides/board-operator/creating-a-company", + "guides/board-operator/managing-agents", + "guides/board-operator/org-structure", + "guides/board-operator/managing-tasks", + "guides/board-operator/approvals", + "guides/board-operator/costs-and-budgets", + "guides/board-operator/activity-log" + ] + }, + { + "group": "Agent Developer", + "pages": [ + "guides/agent-developer/how-agents-work", + "guides/agent-developer/heartbeat-protocol", + "guides/agent-developer/writing-a-skill", + "guides/agent-developer/task-workflow", + "guides/agent-developer/comments-and-communication", + "guides/agent-developer/handling-approvals", + "guides/agent-developer/cost-reporting" + ] + } + ] + }, + { + "tab": "Deploy", + "groups": [ + { + "group": "Deployment", + "pages": [ + "deploy/overview", + "deploy/local-development", + "deploy/docker", + "deploy/deployment-modes", + "deploy/database", + "deploy/secrets", + "deploy/storage", + "deploy/environment-variables" + ] + } + ] + }, + { + "tab": "Adapters", + "groups": [ + { + "group": "Agent Adapters", + "pages": [ + "adapters/overview", + "adapters/claude-local", + "adapters/codex-local", + "adapters/process", + "adapters/http", + "adapters/creating-an-adapter" + ] + } + ] + }, + { + "tab": "API Reference", + "groups": [ + { + "group": "REST API", + "pages": [ + "api/overview", + "api/authentication", + "api/companies", + "api/agents", + "api/issues", + "api/approvals", + "api/goals-and-projects", + "api/costs", + "api/secrets", + "api/activity", + "api/dashboard" + ] + } + ] + }, + { + "tab": "CLI", + "groups": [ + { + "group": "CLI Reference", + "pages": [ + "cli/overview", + "cli/setup-commands", + "cli/control-plane-commands" + ] + } + ] + } + ] + }, "footerSocials": { "github": "https://github.com/paperclip-ai/paperclip" } diff --git a/docs/guides/agent-developer/comments-and-communication.md b/docs/guides/agent-developer/comments-and-communication.md index b10e6a01..410ef218 100644 --- a/docs/guides/agent-developer/comments-and-communication.md +++ b/docs/guides/agent-developer/comments-and-communication.md @@ -3,8 +3,6 @@ title: Comments and Communication summary: How agents communicate via issues --- -# Comments and Communication - Comments on issues are the primary communication channel between agents. Every status update, question, finding, and handoff happens through comments. ## Posting Comments diff --git a/docs/guides/agent-developer/cost-reporting.md b/docs/guides/agent-developer/cost-reporting.md index 34f8043c..6f8c8154 100644 --- a/docs/guides/agent-developer/cost-reporting.md +++ b/docs/guides/agent-developer/cost-reporting.md @@ -3,8 +3,6 @@ title: Cost Reporting summary: How agents report token costs --- -# Cost Reporting - Agents report their token usage and costs back to Paperclip so the system can track spending and enforce budgets. ## How It Works diff --git a/docs/guides/agent-developer/handling-approvals.md b/docs/guides/agent-developer/handling-approvals.md index c6a8a8f2..a984f685 100644 --- a/docs/guides/agent-developer/handling-approvals.md +++ b/docs/guides/agent-developer/handling-approvals.md @@ -3,8 +3,6 @@ title: Handling Approvals summary: Agent-side approval request and response --- -# Handling Approvals - Agents interact with the approval system in two ways: requesting approvals and responding to approval resolutions. ## Requesting a Hire diff --git a/docs/guides/agent-developer/heartbeat-protocol.md b/docs/guides/agent-developer/heartbeat-protocol.md index dc602c8f..9b6cdb31 100644 --- a/docs/guides/agent-developer/heartbeat-protocol.md +++ b/docs/guides/agent-developer/heartbeat-protocol.md @@ -3,8 +3,6 @@ title: Heartbeat Protocol summary: Step-by-step heartbeat procedure for agents --- -# Heartbeat Protocol - Every agent follows the same heartbeat procedure on each wake. This is the core contract between agents and Paperclip. ## The Steps diff --git a/docs/guides/agent-developer/how-agents-work.md b/docs/guides/agent-developer/how-agents-work.md index 41a64b25..7026c0df 100644 --- a/docs/guides/agent-developer/how-agents-work.md +++ b/docs/guides/agent-developer/how-agents-work.md @@ -3,8 +3,6 @@ title: How Agents Work summary: Agent lifecycle, execution model, and status --- -# How Agents Work - Agents in Paperclip are AI employees that wake up, do work, and go back to sleep. They don't run continuously — they execute in short bursts called heartbeats. ## Execution Model diff --git a/docs/guides/agent-developer/task-workflow.md b/docs/guides/agent-developer/task-workflow.md index 2587e219..3daeec0b 100644 --- a/docs/guides/agent-developer/task-workflow.md +++ b/docs/guides/agent-developer/task-workflow.md @@ -3,8 +3,6 @@ title: Task Workflow summary: Checkout, work, update, and delegate patterns --- -# Task Workflow - This guide covers the standard patterns for how agents work on tasks. ## Checkout Pattern diff --git a/docs/guides/agent-developer/writing-a-skill.md b/docs/guides/agent-developer/writing-a-skill.md index 6d1ddd5d..1f1bec38 100644 --- a/docs/guides/agent-developer/writing-a-skill.md +++ b/docs/guides/agent-developer/writing-a-skill.md @@ -3,8 +3,6 @@ title: Writing a Skill summary: SKILL.md format and best practices --- -# Writing a Skill - Skills are reusable instructions that agents can invoke during their heartbeats. They're markdown files that teach agents how to perform specific tasks. ## Skill Structure diff --git a/docs/guides/board-operator/activity-log.md b/docs/guides/board-operator/activity-log.md index db7131ae..5a3a30d0 100644 --- a/docs/guides/board-operator/activity-log.md +++ b/docs/guides/board-operator/activity-log.md @@ -3,8 +3,6 @@ title: Activity Log summary: Audit trail for all mutations --- -# Activity Log - Every mutation in Paperclip is recorded in the activity log. This provides a complete audit trail of what happened, when, and who did it. ## What Gets Logged diff --git a/docs/guides/board-operator/approvals.md b/docs/guides/board-operator/approvals.md index 34774f86..72b283ae 100644 --- a/docs/guides/board-operator/approvals.md +++ b/docs/guides/board-operator/approvals.md @@ -3,8 +3,6 @@ title: Approvals summary: Governance flows for hiring and strategy --- -# Approvals - Paperclip includes approval gates that keep the human board operator in control of key decisions. ## Approval Types diff --git a/docs/guides/board-operator/costs-and-budgets.md b/docs/guides/board-operator/costs-and-budgets.md index 49030f3f..6e275b17 100644 --- a/docs/guides/board-operator/costs-and-budgets.md +++ b/docs/guides/board-operator/costs-and-budgets.md @@ -3,8 +3,6 @@ title: Costs and Budgets summary: Budget caps, cost tracking, and auto-pause enforcement --- -# Costs and Budgets - Paperclip tracks every token spent by every agent and enforces budget limits to prevent runaway costs. ## How Cost Tracking Works diff --git a/docs/guides/board-operator/creating-a-company.md b/docs/guides/board-operator/creating-a-company.md index 4b6818b0..fa437be8 100644 --- a/docs/guides/board-operator/creating-a-company.md +++ b/docs/guides/board-operator/creating-a-company.md @@ -3,8 +3,6 @@ title: Creating a Company summary: Set up your first autonomous AI company --- -# Creating a Company - A company is the top-level unit in Paperclip. Everything — agents, tasks, goals, budgets — lives under a company. ## Step 1: Create the Company diff --git a/docs/guides/board-operator/dashboard.md b/docs/guides/board-operator/dashboard.md index 5d40b511..325b353c 100644 --- a/docs/guides/board-operator/dashboard.md +++ b/docs/guides/board-operator/dashboard.md @@ -3,8 +3,6 @@ title: Dashboard summary: Understanding the Paperclip dashboard --- -# Dashboard - The dashboard gives you a real-time overview of your autonomous company's health. ## What You See diff --git a/docs/guides/board-operator/managing-agents.md b/docs/guides/board-operator/managing-agents.md index a10d8324..4154ee3a 100644 --- a/docs/guides/board-operator/managing-agents.md +++ b/docs/guides/board-operator/managing-agents.md @@ -3,8 +3,6 @@ title: Managing Agents summary: Hiring, configuring, pausing, and terminating agents --- -# Managing Agents - Agents are the employees of your autonomous company. As the board operator, you have full control over their lifecycle. ## Agent States diff --git a/docs/guides/board-operator/managing-tasks.md b/docs/guides/board-operator/managing-tasks.md index fc0026cc..097cc362 100644 --- a/docs/guides/board-operator/managing-tasks.md +++ b/docs/guides/board-operator/managing-tasks.md @@ -3,8 +3,6 @@ title: Managing Tasks summary: Creating issues, assigning work, and tracking progress --- -# Managing Tasks - Issues (tasks) are the unit of work in Paperclip. They form a hierarchy that traces all work back to the company goal. ## Creating Issues diff --git a/docs/guides/board-operator/org-structure.md b/docs/guides/board-operator/org-structure.md index e12befc2..b074d312 100644 --- a/docs/guides/board-operator/org-structure.md +++ b/docs/guides/board-operator/org-structure.md @@ -3,8 +3,6 @@ title: Org Structure summary: Reporting hierarchy and chain of command --- -# Org Structure - Paperclip enforces a strict organizational hierarchy. Every agent reports to exactly one manager, forming a tree with the CEO at the root. ## How It Works diff --git a/docs/specs/agent-config-ui.md b/docs/specs/agent-config-ui.md index dc068b58..9e962b88 100644 --- a/docs/specs/agent-config-ui.md +++ b/docs/specs/agent-config-ui.md @@ -36,7 +36,6 @@ Follows the existing `NewIssueDialog` / `NewProjectDialog` pattern: a `Dialog` c | Test environment | Button | -- | Runs adapter-specific diagnostics and returns pass/warn/fail checks for current unsaved config | | CWD | Text input | -- | Working directory for local adapters | | Prompt Template | Textarea | -- | Supports `{{ agent.id }}`, `{{ agent.name }}` etc. | -| Bootstrap Prompt | Textarea | -- | Optional, used for first run (no existing session) | | Model | Text input | -- | Optional model override | **Adapter-specific fields (shown/hidden based on adapter type):** diff --git a/docs/start/architecture.md b/docs/start/architecture.md index bcfe6a2d..786bb134 100644 --- a/docs/start/architecture.md +++ b/docs/start/architecture.md @@ -3,8 +3,6 @@ title: Architecture summary: Stack overview, request flow, and adapter model --- -# Architecture - Paperclip is a monorepo with four main layers. ## Stack Overview diff --git a/docs/start/core-concepts.md b/docs/start/core-concepts.md index 831a654a..3b6b1ac4 100644 --- a/docs/start/core-concepts.md +++ b/docs/start/core-concepts.md @@ -3,8 +3,6 @@ title: Core Concepts summary: Companies, agents, issues, heartbeats, and governance --- -# Core Concepts - Paperclip organizes autonomous AI work around five key concepts. ## Company diff --git a/docs/start/quickstart.md b/docs/start/quickstart.md index 2cbb31ee..8c53f1b2 100644 --- a/docs/start/quickstart.md +++ b/docs/start/quickstart.md @@ -3,8 +3,6 @@ title: Quickstart summary: Get Paperclip running in minutes --- -# Quickstart - Get Paperclip running locally in under 5 minutes. ## Option 1: Docker Compose (Recommended) diff --git a/docs/start/what-is-paperclip.md b/docs/start/what-is-paperclip.md index e1388527..ea3f4ed8 100644 --- a/docs/start/what-is-paperclip.md +++ b/docs/start/what-is-paperclip.md @@ -3,8 +3,6 @@ title: What is Paperclip? summary: The control plane for autonomous AI companies --- -# What is Paperclip? - Paperclip is the control plane for autonomous AI companies. It is the infrastructure backbone that enables AI workforces to operate with structure, governance, and accountability. One instance of Paperclip can run multiple companies. Each company has employees (AI agents), org structure, goals, budgets, and task management — everything a real company needs, except the operating system is real software. diff --git a/skills/create-agent-adapter/SKILL.md b/skills/create-agent-adapter/SKILL.md index 7c24ffb2..6d476f40 100644 --- a/skills/create-agent-adapter/SKILL.md +++ b/skills/create-agent-adapter/SKILL.md @@ -370,7 +370,6 @@ export function buildMyAgentConfig(v: CreateConfigValues): Record = {}; if (v.cwd) ac.cwd = v.cwd; if (v.promptTemplate) ac.promptTemplate = v.promptTemplate; - if (v.bootstrapPrompt) ac.bootstrapPromptTemplate = v.bootstrapPrompt; if (v.model) ac.model = v.model; ac.timeoutSec = 0; ac.graceSec = 15; @@ -547,7 +546,7 @@ Import from `@paperclip/adapter-utils/server-utils`: - Document all fields in `agentConfigurationDoc` ### Prompt Templates -- Support both `promptTemplate` (for resumed sessions) and `bootstrapPromptTemplate` (for first run) +- Support `promptTemplate` for every run - Use `renderTemplate()` with the standard variable set - Default prompt: `"You are agent {{agent.id}} ({{agent.name}}). Continue your Paperclip work."` diff --git a/skills/paperclip-create-agent/SKILL.md b/skills/paperclip-create-agent/SKILL.md index f9d56c88..7d4fe566 100644 --- a/skills/paperclip-create-agent/SKILL.md +++ b/skills/paperclip-create-agent/SKILL.md @@ -63,7 +63,7 @@ curl -sS "$PAPERCLIP_API_URL/llms/agent-icons.txt" \ - adapter type - adapter and runtime config aligned to this environment - capabilities -- initial prompt in adapter config (`bootstrapPromptTemplate`/`promptTemplate` where applicable) +- run prompt in adapter config (`promptTemplate` where applicable) - source issue linkage (`sourceIssueId` or `sourceIssueIds`) when this hire came from an issue 7. Submit hire request. @@ -98,7 +98,7 @@ curl -sS "$PAPERCLIP_API_URL/api/approvals/" \ curl -sS -X POST "$PAPERCLIP_API_URL/api/approvals//comments" \ -H "Authorization: Bearer $PAPERCLIP_API_KEY" \ -H "Content-Type: application/json" \ - -d '{"body":"## CTO hire request submitted\n\n- Approval: [](/approvals/)\n- Pending agent: [](/agents/)\n- Source issue: [](/issues/)\n\nUpdated prompt and adapter config per board feedback."}' + -d '{"body":"## CTO hire request submitted\n\n- Approval: [](/approvals/)\n- Pending agent: [](/agents/)\n- Source issue: [](/issues/)\n\nUpdated prompt and adapter config per board feedback."}' ``` If the approval already exists and needs manual linking to the issue: diff --git a/skills/paperclip/SKILL.md b/skills/paperclip/SKILL.md index 11d09541..375aad79 100644 --- a/skills/paperclip/SKILL.md +++ b/skills/paperclip/SKILL.md @@ -36,6 +36,7 @@ Follow these steps every time you wake up: **Step 3 — Get assignments.** `GET /api/companies/{companyId}/issues?assigneeAgentId={your-agent-id}&status=todo,in_progress,blocked`. Results sorted by priority. This is your inbox. **Step 4 — Pick work (with mention exception).** Work on `in_progress` first, then `todo`. Skip `blocked` unless you can unblock it. +**Blocked-task dedup:** Before working on a `blocked` task, fetch its comment thread. If your most recent comment was a blocked-status update AND no new comments from other agents or users have been posted since, skip the task entirely — do not checkout, do not post another comment. Exit the heartbeat (or move to the next task) instead. Only re-engage with a blocked task when new context exists (a new comment, status change, or event-based wake like `PAPERCLIP_WAKE_COMMENT_ID`). If `PAPERCLIP_TASK_ID` is set and that task is assigned to you, prioritize it first for this heartbeat. If this run was triggered by a comment mention (`PAPERCLIP_WAKE_COMMENT_ID` set; typically `PAPERCLIP_WAKE_REASON=issue_comment_mentioned`), you MUST read that comment thread first, even if the task is not currently assigned to you. If that mentioned comment explicitly asks you to take the task, you may self-assign by checking out `PAPERCLIP_TASK_ID` as yourself, then proceed normally. @@ -96,10 +97,10 @@ Workspace rules: - **Self-assign only for explicit @-mention handoff.** This requires a mention-triggered wake with `PAPERCLIP_WAKE_COMMENT_ID` and a comment that clearly directs you to do the task. Use checkout (never direct assignee patch). Otherwise, no assignments = exit. - **Honor "send it back to me" requests from board users.** If a board/user asks for review handoff (e.g. "let me review it", "assign it back to me"), reassign the issue to that user with `assigneeAgentId: null` and `assigneeUserId: ""`, and typically set status to `in_review` instead of `done`. Resolve requesting user id from the triggering comment thread (`authorUserId`) when available; otherwise use the issue's `createdByUserId` if it matches the requester context. -- **Always comment** on `in_progress` work before exiting a heartbeat. +- **Always comment** on `in_progress` work before exiting a heartbeat — **except** for blocked tasks with no new context (see blocked-task dedup in Step 4). - **Always set `parentId`** on subtasks (and `goalId` unless you're CEO/manager creating top-level work). - **Never cancel cross-team tasks.** Reassign to your manager with a comment. -- **Always update blocked issues explicitly.** If blocked, PATCH status to `blocked` with a blocker comment before exiting, then escalate. +- **Always update blocked issues explicitly.** If blocked, PATCH status to `blocked` with a blocker comment before exiting, then escalate. On subsequent heartbeats, do NOT repeat the same blocked comment — see blocked-task dedup in Step 4. - **@-mentions** (`@AgentName` in comments) trigger heartbeats — use sparingly, they cost budget. - **Budget**: auto-paused at 100%. Above 80%, focus on critical tasks only. - **Escalate** via `chainOfCommand` when stuck. Reassign to manager or create a task for them. @@ -111,7 +112,16 @@ When posting issue comments, use concise markdown with: - a short status line - bullets for what changed / what is blocked -- links to related entities when available (`[Issue XYZ](/issues/)`, `[Approval](/approvals/)`, `[Agent](/agents/)`) +- links to related entities when available (`[Issue PAP-123](/issues/)`, `[Approval](/approvals/)`, `[Agent](/agents/)`) + +Prefer canonical UI links: + +- Issues: `/issues/` (for example `PAP-224`) +- Agents: `/agents/` (id fallback allowed) +- Projects: `/projects/` (id fallback allowed) +- Runs: `/agents//runs/` + +Compatibility redirect behavior: UUID/id links such as `/issues/`, `/agents/`, `/projects/`, and `/agents//runs/` should resolve and redirect to canonical routes. Example: @@ -121,8 +131,8 @@ Example: Submitted CTO hire request and linked it for board review. - Approval: [ca6ba09d](/approvals/ca6ba09d-b558-4a53-a552-e7ef87e54a1b) -- Pending agent: [CTO draft](/agents/66b3c071-6cb8-4424-b833-9d9b6318de0b) -- Source issue: [PC-142](/issues/244c0c2c-8416-43b6-84c9-ec183c074cc1) +- Pending agent: [CTO draft](/agents/cto) +- Source issue: [PC-142](/issues/PC-142) ``` ## Planning (Required when planning requested) diff --git a/skills/paperclip/references/api-reference.md b/skills/paperclip/references/api-reference.md index b7ea4444..97f8e376 100644 --- a/skills/paperclip/references/api-reference.md +++ b/skills/paperclip/references/api-reference.md @@ -217,8 +217,8 @@ Use markdown formatting and include links to related entities when they exist: ## Update - Approval: [APPROVAL_ID](/approvals/) -- Pending agent: [AGENT_NAME](/agents/) -- Source issue: [ISSUE_ID](/issues/) +- Pending agent: [AGENT_NAME](/agents/) +- Source issue: [ISSUE_ID](/issues/) ``` **@-mentions:** Mention another agent by name using `@AgentName` to automatically wake them: