aevgarik/paperclip
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: sync docs and skills updates from backup branch

Browse Source
This commit is contained in:
Dotta
2026-03-02 16:44:10 -06:00
parent 8ee063c4e5
commit cabd16bc70
60 changed files with 209 additions and 246 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
doc/CLI.md
View File

@@ -84,8 +84,21 @@ export PAPERCLIP_API_KEY=...
```sh
pnpm paperclip company list
pnpm paperclip company get <company-id>
pnpm paperclip company delete <company-id-or-prefix> --yes --confirm <same-id-or-prefix>
```
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

13
doc/DEVELOPING.md
View File

@@ -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.

22
doc/SPEC-implementation.md
View File

@@ -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/<slug>/AGENTS.md` (required for V1 export/import)
- `agents/<slug>/HEARTBEAT.md` (optional, import accepted)
- `agents/<slug>/*.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

3
doc/plans/cursor-cloud-adapter.md
View File

@@ -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`

10
doc/spec/agent-runs.md
View File

@@ -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.

3
doc/spec/agents-runtime.md
View File

@@ -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.

5
docs/adapters/claude-local.md
View File

@@ -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 |

5
docs/adapters/codex-local.md
View File

@@ -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 |

2
docs/adapters/creating-an-adapter.md
View File

@@ -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

2
docs/adapters/http.md
View File

@@ -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

2
docs/adapters/overview.md
View File

@@ -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

2
docs/adapters/process.md
View File

@@ -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

3
docs/agents-runtime.md
View File

@@ -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.

2
docs/api/activity.md
View File

@@ -3,8 +3,6 @@ title: Activity
summary: Activity log queries
---
# Activity API
Query the audit trail of all mutations across the company.
## List Activity

2
docs/api/agents.md
View File

@@ -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

2
docs/api/approvals.md
View File

@@ -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

2
docs/api/authentication.md
View File

@@ -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

2
docs/api/companies.md
View File

@@ -3,8 +3,6 @@ title: Companies
summary: Company CRUD endpoints
---
# Companies API
Manage companies within your Paperclip instance.
## List Companies

2
docs/api/costs.md
View File

@@ -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

2
docs/api/dashboard.md
View File

@@ -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

2
docs/api/goals-and-projects.md
View File

@@ -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

2
docs/api/issues.md
View File

@@ -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

2
docs/api/overview.md
View File

@@ -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

2
docs/api/secrets.md
View File

@@ -3,8 +3,6 @@ title: Secrets
summary: Secrets CRUD
---
# Secrets API
Manage encrypted secrets that agents reference in their environment configuration.
## List Secrets

20
docs/cli/control-plane-commands.md
View File

@@ -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 <issue-id>
```sh
pnpm paperclip company list
pnpm paperclip company get <company-id>
# Export to portable folder package (writes manifest + markdown files)
pnpm paperclip company export <company-id> --out ./exports/acme --include company,agents
# Preview import (no writes)
pnpm paperclip company import \
--from https://github.com/<owner>/<repo>/tree/main/<path> \
--target existing \
--company-id <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

2
docs/cli/overview.md
View File

@@ -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

2
docs/cli/setup-commands.md
View File

@@ -3,8 +3,6 @@ title: Setup Commands
summary: Onboard, run, doctor, and configure
---
# Setup Commands
Instance setup and diagnostics commands.
## `paperclip run`

2
docs/deploy/database.md
View File

@@ -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)

2
docs/deploy/deployment-modes.md
View File

@@ -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`

2
docs/deploy/docker.md
View File

@@ -3,8 +3,6 @@ title: Docker
summary: Docker Compose quickstart
---
# Docker
Run Paperclip in Docker without installing Node or pnpm locally.
## Compose Quickstart (Recommended)

2
docs/deploy/environment-variables.md
View File

@@ -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

2
docs/deploy/local-development.md
View File

@@ -3,8 +3,6 @@ title: Local Development
summary: Set up Paperclip for local development
---
# Local Development
Run Paperclip locally with zero external dependencies.
## Prerequisites

2
docs/deploy/overview.md
View File

@@ -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

2
docs/deploy/secrets.md
View File

@@ -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`

2
docs/deploy/storage.md
View File

@@ -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)

12
docs/docs.json
View File

@@ -15,15 +15,8 @@
"url": "https://github.com/paperclip-ai/paperclip"
}
],
"navigation": {
"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": [
@@ -136,7 +129,8 @@
}
]
}
],
]
},
"footerSocials": {
"github": "https://github.com/paperclip-ai/paperclip"
}

2
docs/guides/agent-developer/comments-and-communication.md
View File

@@ -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

2
docs/guides/agent-developer/cost-reporting.md
View File

@@ -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

2
docs/guides/agent-developer/handling-approvals.md
View File

@@ -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

2
docs/guides/agent-developer/heartbeat-protocol.md
View File

@@ -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

2
docs/guides/agent-developer/how-agents-work.md
View File

@@ -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

2
docs/guides/agent-developer/task-workflow.md
View File

@@ -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

2
docs/guides/agent-developer/writing-a-skill.md
View File

@@ -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

2
docs/guides/board-operator/activity-log.md
View File

@@ -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

2
docs/guides/board-operator/approvals.md
View File

@@ -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

2
docs/guides/board-operator/costs-and-budgets.md
View File

@@ -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

2
docs/guides/board-operator/creating-a-company.md
View File

@@ -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

2
docs/guides/board-operator/dashboard.md
View File

@@ -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

2
docs/guides/board-operator/managing-agents.md
View File

@@ -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

2
docs/guides/board-operator/managing-tasks.md
View File

@@ -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

2
docs/guides/board-operator/org-structure.md
View File

@@ -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

1
docs/specs/agent-config-ui.md
View File

@@ -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):**

2
docs/start/architecture.md
View File

@@ -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

2
docs/start/core-concepts.md
View File

@@ -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

2
docs/start/quickstart.md
View File

@@ -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)

2
docs/start/what-is-paperclip.md
View File

@@ -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.

3
skills/create-agent-adapter/SKILL.md
View File

@@ -370,7 +370,6 @@ export function buildMyAgentConfig(v: CreateConfigValues): Record<string, unknow
const ac: Record<string, unknown> = {};
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."`

4
skills/paperclip-create-agent/SKILL.md
View File

@@ -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/<approval-id>" \
curl -sS -X POST "$PAPERCLIP_API_URL/api/approvals/<approval-id>/comments" \
-H "Authorization: Bearer $PAPERCLIP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"body":"## CTO hire request submitted\n\n- Approval: [<approval-id>](/approvals/<approval-id>)\n- Pending agent: [<agent-id>](/agents/<agent-id>)\n- Source issue: [<issue-id>](/issues/<issue-id>)\n\nUpdated prompt and adapter config per board feedback."}'
-d '{"body":"## CTO hire request submitted\n\n- Approval: [<approval-id>](/approvals/<approval-id>)\n- Pending agent: [<agent-ref>](/agents/<agent-url-key-or-id>)\n- Source issue: [<issue-ref>](/issues/<issue-identifier-or-id>)\n\nUpdated prompt and adapter config per board feedback."}'
```
If the approval already exists and needs manual linking to the issue:

20
skills/paperclip/SKILL.md
View File

@@ -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: "<requesting-user-id>"`, 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/<id>)`, `[Approval](/approvals/<id>)`, `[Agent](/agents/<id>)`)
- links to related entities when available (`[Issue PAP-123](/issues/<issue-identifier>)`, `[Approval](/approvals/<approval-id>)`, `[Agent](/agents/<agent-url-key-or-id>)`)
Prefer canonical UI links:
- Issues: `/issues/<issue-identifier>` (for example `PAP-224`)
- Agents: `/agents/<agent-url-key>` (id fallback allowed)
- Projects: `/projects/<project-url-key>` (id fallback allowed)
- Runs: `/agents/<agent-url-key-or-id>/runs/<run-id>`
Compatibility redirect behavior: UUID/id links such as `/issues/<uuid>`, `/agents/<id>`, `/projects/<id>`, and `/agents/<id>/runs/<run-id>` 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)

4
skills/paperclip/references/api-reference.md
View File

@@ -217,8 +217,8 @@ Use markdown formatting and include links to related entities when they exist:
## Update
- Approval: [APPROVAL_ID](/approvals/<approval-id>)
- Pending agent: [AGENT_NAME](/agents/<agent-id>)
- Source issue: [ISSUE_ID](/issues/<issue-id>)
- Pending agent: [AGENT_NAME](/agents/<agent-url-key-or-id>)
- Source issue: [ISSUE_ID](/issues/<issue-identifier-or-id>)
```
**@-mentions:** Mention another agent by name using `@AgentName` to automatically wake them: