@tickernelz/paperclip-pro-adapter-codex-local 2026.925.0

package/skills/paperclip/references/company-skills.md

@@ -0,0 +1,266 @@
+# Company Skills Workflow
+
+Use this reference when a board user, CEO, or manager asks you to find a skill, install it into the company library, or assign it to an agent.
+
+## What Exists
+
+- App-shipped catalog: a curated set of company skills in `@tickernelz/paperclip-pro-skills-catalog`, browseable and installable without leaving Paperclip.
+- Company skill library: install, inspect, update, audit, reset, and read company skills for the whole company.
+- Agent skill assignment: add or remove company skills on an existing agent.
+- Hire/create composition: pass `desiredSkills` when creating or hiring an agent so the same assignment model applies immediately.
+
+The canonical model is:
+
+1. add the skill to the company library — either from the app catalog (`skills install`), an external source (`skills import`), or a managed local skill (`skills create`/`skills scan-projects`)
+2. attach the company skill to the agent (`skills agent sync`)
+3. optionally do step 2 during hire/create with `desiredSkills`
+
+Catalog install ≠ agent attach. Installing a catalog skill only adds the row to
+`company_skills`. The agent will not use it until you sync the agent's desired
+set.
+
+## Permission Model
+
+- Company skill reads: any same-company actor
+- Company skill mutations: open to same-company actors by default. Missing `skills:create` grants and `canCreateSkills` settings do not deny ordinary skill work; only an explicit company skill policy restriction does. Core safety and company-boundary checks always remain enforced.
+- Agent skill assignment: same permission model as updating that agent
+- Team installs continue to require `agents:create` because they import or create agents in addition to attaching skills.
+
+## Core Endpoints
+
+App-shipped catalog (read-only browse + company install):
+
+- `GET /api/skills/catalog`
+- `GET /api/skills/catalog/:catalogId`
+- `GET /api/skills/catalog/ref?ref=<id|key|slug>`
+- `GET /api/skills/catalog/:catalogId/files?path=SKILL.md`
+- `POST /api/companies/:companyId/skills/install-catalog`
+
+Company library:
+
+- `GET /api/companies/:companyId/skills`
+- `GET /api/companies/:companyId/skills/:skillId`
+- `GET /api/companies/:companyId/skills/:skillId/files?path=SKILL.md`
+- `POST /api/companies/:companyId/skills` (managed local create)
+- `POST /api/companies/:companyId/skills/import`
+- `POST /api/companies/:companyId/skills/scan-projects`
+- `GET /api/companies/:companyId/skills/:skillId/update-status`
+- `POST /api/companies/:companyId/skills/:skillId/install-update`
+- `POST /api/companies/:companyId/skills/:skillId/audit`
+- `POST /api/companies/:companyId/skills/:skillId/reset`
+- `DELETE /api/companies/:companyId/skills/:skillId`
+
+Agent attach and hire/create composition:
+
+- `GET /api/agents/:agentId/skills`
+- `POST /api/agents/:agentId/skills/sync`
+- `POST /api/companies/:companyId/agent-hires`
+- `POST /api/companies/:companyId/agents`
+
+If a board user, CEO, or manager is driving locally, prefer the
+`paperclip-pro skills` CLI documented in `doc/CLI.md` — it wraps every endpoint
+above, accepts company skill or catalog refs by `id`/`key`/`slug`, and prints
+the same JSON these endpoints return when called with `--json`.
+
+## Install A Skill Into The Company
+
+Two paths cover the common cases:
+
+1. **App-shipped catalog** (preferred when the right skill exists in the
+   bundled/optional catalog) — browse it first, then install with the catalog
+   install endpoint. No external network fetch happens.
+2. **External source** (skills.sh, GitHub, local path, or URL) — use the
+   import endpoint below.
+
+### App-shipped catalog
+
+Browse, inspect, and install catalog skills before reaching for an external
+source. Bundled skills are the curated defaults for any company; optional
+skills are role- or domain-specific.
+
+```sh
+curl -sS "$PAPERCLIP_API_URL/api/skills/catalog?kind=bundled" \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY"
+
+curl -sS "$PAPERCLIP_API_URL/api/skills/catalog/ref?ref=github-pr-workflow" \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY"
+
+curl -sS -X POST "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/skills/install-catalog" \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "catalogSkillId": "paperclipai:bundled:software-development:github-pr-workflow"
+  }'
+```
+
+The install response records provenance (`catalogId`, `catalogKey`,
+`packageVersion`, `originHash`) on the company skill so update/audit/reset
+flows know the pinned origin. `force: true` may replace a same-key
+catalog-managed skill but never bypasses hard-stop audit findings.
+
+### External source import
+
+Import using a **skills.sh URL**, a key-style source string, a GitHub URL, or a local path.
+
+### Source types (in order of preference)
+
+| Source format | Example | When to use |
+|---|---|---|
+| **skills.sh URL** | `https://skills.sh/google-labs-code/stitch-skills/design-md` | When a user gives you a `skills.sh` link. This is the managed skill registry — **always prefer it when available**. |
+| **Key-style string** | `google-labs-code/stitch-skills/design-md` | Shorthand for the same skill — `org/repo/skill-name` format. Equivalent to the skills.sh URL. |
+| **GitHub URL** | `https://github.com/vercel-labs/agent-browser` | When the skill is in a GitHub repo but not on skills.sh. |
+| **Local path** | `/abs/path/to/skill-dir` | When the skill is on disk (dev/testing only). |
+
+**Critical:** If a user gives you a `https://skills.sh/...` URL, use that URL or its key-style equivalent (`org/repo/skill-name`) as the `source`. Do **not** convert it to a GitHub URL — skills.sh is the managed registry and the source of truth for versioning, discovery, and updates.
+
+### Example: skills.sh import (preferred)
+
+```sh
+curl -sS -X POST "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/skills/import" \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "source": "https://skills.sh/google-labs-code/stitch-skills/design-md"
+  }'
+```
+
+Or equivalently using the key-style string:
+
+```sh
+curl -sS -X POST "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/skills/import" \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "source": "google-labs-code/stitch-skills/design-md"
+  }'
+```
+
+### Example: GitHub import
+
+```sh
+curl -sS -X POST "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/skills/import" \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "source": "https://github.com/vercel-labs/agent-browser"
+  }'
+```
+
+You can also use source strings such as:
+
+- `google-labs-code/stitch-skills/design-md`
+- `vercel-labs/agent-browser/agent-browser`
+- `npx skills add https://github.com/vercel-labs/agent-browser --skill agent-browser`
+
+If the task is to discover skills from the company project workspaces first:
+
+```sh
+curl -sS -X POST "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/skills/scan-projects" \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+## Inspect What Was Installed
+
+```sh
+curl -sS "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/skills" \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY"
+```
+
+Read the skill entry and its `SKILL.md`:
+
+```sh
+curl -sS "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/skills/<skill-id>" \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY"
+
+curl -sS "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/skills/<skill-id>/files?path=SKILL.md" \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY"
+```
+
+## Assign Skills To An Existing Agent
+
+`desiredSkills` accepts:
+
+- exact company skill key
+- exact company skill id
+- exact slug when it is unique in the company
+
+The server persists canonical company skill keys.
+
+The request must include a merge mode:
+
+- `add` adds the named skills and keeps every other assignment.
+- `remove` removes only the named skills.
+- `replace` overwrites the complete desired skill set. Use it only after explicit confirmation.
+
+```sh
+curl -sS -X POST "$PAPERCLIP_API_URL/api/agents/<agent-id>/skills/sync" \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "mode": "add",
+    "desiredSkills": [
+      "vercel-labs/agent-browser/agent-browser"
+    ]
+  }'
+```
+
+If you need the current state first:
+
+```sh
+curl -sS "$PAPERCLIP_API_URL/api/agents/<agent-id>/skills" \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY"
+```
+
+## Include Skills During Hire Or Create
+
+Use the same company skill keys or references in `desiredSkills` when hiring or creating an agent:
+
+```sh
+curl -sS -X POST "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/agent-hires" \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "QA Browser Agent",
+    "role": "qa",
+    "adapterType": "codex_local",
+    "adapterConfig": {
+      "cwd": "/abs/path/to/repo"
+    },
+    "desiredSkills": [
+      "agent-browser"
+    ]
+  }'
+```
+
+For direct create without approval:
+
+```sh
+curl -sS -X POST "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/agents" \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "QA Browser Agent",
+    "role": "qa",
+    "adapterType": "codex_local",
+    "adapterConfig": {
+      "cwd": "/abs/path/to/repo"
+    },
+    "desiredSkills": [
+      "agent-browser"
+    ]
+  }'
+```
+
+## Notes
+
+- Built-in Paperclip runtime skills are still added automatically when required by the adapter.
+- If a reference is missing or ambiguous, the API returns `422`.
+- Prefer linking back to the relevant issue, approval, and agent when you comment about skill changes.
+- Use company portability routes when you need whole-package import/export, not just a skill:
+  - `POST /api/companies/:companyId/imports/preview`
+  - `POST /api/companies/:companyId/imports/apply`
+  - `POST /api/companies/:companyId/exports/preview`
+  - `POST /api/companies/:companyId/exports`
+- Use skill-only import when the task is specifically to add a skill to the company library without importing the surrounding company/team/package structure.

package/skills/paperclip/references/issue-workspaces.md

@@ -0,0 +1,80 @@
+# Issue Workspace Runtime Controls
+
+Use this reference when an issue has an isolated execution workspace and you need to inspect or run that workspace's services, especially for QA/browser verification.
+
+## Discover the Workspace
+
+Start from the issue, not from memory:
+
+```sh
+curl -sS -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+  "$PAPERCLIP_API_URL/api/issues/$PAPERCLIP_TASK_ID/heartbeat-context"
+```
+
+Read `currentExecutionWorkspace`:
+
+- `id` — execution workspace id for control endpoints
+- `cwd` / `branchName` — local checkout context
+- `status` / `closedAt` — whether the workspace is usable
+- `runtimeServices[]` — current services, including `serviceName`, `status`, `healthStatus`, `url`, `port`, and `runtimeServiceId`
+
+If `currentExecutionWorkspace` is `null`, the issue does not currently have a realized execution workspace. For child/follow-up work, create the child with `parentId` or use `inheritExecutionWorkspaceFromIssueId` so Paperclip preserves workspace continuity.
+
+## Control Services
+
+Prefer Paperclip-managed runtime service controls over manual `pnpm dev &` or ad-hoc background processes. These endpoints keep service state, URLs, logs, and ownership visible to other agents and the board.
+
+```sh
+# Start all configured services; waits for configured readiness checks.
+curl -sS -X POST \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+  -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
+  -H "Content-Type: application/json" \
+  "$PAPERCLIP_API_URL/api/execution-workspaces/<workspace-id>/runtime-services/start" \
+  -d '{}'
+
+# Restart all configured services.
+curl -sS -X POST \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+  -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
+  -H "Content-Type: application/json" \
+  "$PAPERCLIP_API_URL/api/execution-workspaces/<workspace-id>/runtime-services/restart" \
+  -d '{}'
+
+# Stop all running services.
+curl -sS -X POST \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+  -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
+  -H "Content-Type: application/json" \
+  "$PAPERCLIP_API_URL/api/execution-workspaces/<workspace-id>/runtime-services/stop" \
+  -d '{}'
+```
+
+To target a configured service, pass one of:
+
+```json
+{ "workspaceCommandId": "web" }
+{ "runtimeServiceId": "<runtime-service-id>" }
+{ "serviceIndex": 0 }
+```
+
+The response includes an updated `workspace.runtimeServices[]` list and a `workspaceOperation`/`operation` record for logs.
+
+## Read the URL
+
+After `start` or `restart`, read the service URL from:
+
+- response `workspace.runtimeServices[].url`
+- or a fresh `GET /api/issues/:issueId/heartbeat-context` response at `currentExecutionWorkspace.runtimeServices[].url`
+
+For QA/browser checks, use the service whose `status` is `running` and whose `healthStatus` is not `unhealthy`. If multiple services are running, prefer the one named `web`, `preview`, or the configured service the issue mentions.
+
+## MCP Tools
+
+When the Paperclip MCP tools are available, prefer these issue-scoped tools:
+
+- `paperclipGetIssueWorkspaceRuntime` — reads `currentExecutionWorkspace` and service URLs for an issue.
+- `paperclipControlIssueWorkspaceServices` — starts, stops, or restarts the current issue workspace services.
+- `paperclipWaitForIssueWorkspaceService` — waits until a selected service is running and returns its URL when exposed.
+
+These tools resolve the issue's workspace id for you, so QA agents do not need to know the lower-level execution workspace endpoint first.

package/skills/paperclip/references/routines.md

@@ -0,0 +1,231 @@
+# Paperclip Routines
+
+Routines are recurring tasks. Each time a routine fires it creates an execution issue assigned to the routine's agent — the agent picks it up in the normal heartbeat flow.
+
+A routine has:
+- One assigned agent and one project
+- One or more triggers (`schedule`, `webhook`, or `api`)
+- A concurrency policy (what to do when a previous run is still active)
+- A catch-up policy (what to do with missed scheduled runs)
+- An activity gate policy (whether quiet scheduled ticks should be skipped)
+
+**Authorization:** Agents can read all routines in their company but can only create or manage routines assigned to themselves. Board operators have full access, including reassignment.
+
+---
+
+## Lifecycle
+
+```
+active <-> paused
+active  -> archived  (terminal — cannot be reactivated)
+```
+
+Paused routines do not fire. Archived routines do not fire and cannot be unarchived.
+
+---
+
+## Creating a Routine
+
+```
+POST /api/companies/{companyId}/routines
+{
+  "title": "Weekly CEO briefing",
+  "description": "Compile status report and post to Slack",
+  "assigneeAgentId": "{agentId}",
+  "projectId": "{projectId}",
+  "goalId": "{goalId}",           // optional
+  "parentIssueId": "{issueId}",   // optional — parent for run issues
+  "priority": "medium",
+  "status": "active",
+  "concurrencyPolicy": "coalesce_if_active",
+  "catchUpPolicy": "skip_missed",
+  "activityGatePolicy": "always",
+  "activityGateScope": "company"
+}
+```
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `title` | yes | Max 200 chars |
+| `description` | no | Human-readable description of the routine |
+| `assigneeAgentId` | yes | Agents: must be themselves |
+| `projectId` | yes | |
+| `goalId` | no | Inherited by run issues |
+| `parentIssueId` | no | Run issues become children of this issue |
+| `priority` | no | `critical` `high` `medium` (default) `low` |
+| `status` | no | `active` (default) `paused` `archived` |
+| `concurrencyPolicy` | no | See below |
+| `catchUpPolicy` | no | See below |
+| `activityGatePolicy` | no | `always` (default) or `require_external_activity`; see below |
+| `activityGateScope` | no | `company` (default) or `project`; see below |
+
+---
+
+## Concurrency Policies
+
+Controls what happens when a trigger fires while the previous run issue is still open or active.
+
+| Policy | Behaviour |
+|--------|-----------|
+| `coalesce_if_active` **(default)** | New run is marked `coalesced` and linked to the existing active run — no new issue created |
+| `skip_if_active` | New run is marked `skipped` and linked to the existing active run — no new issue created |
+| `always_enqueue` | Always create a new issue regardless of active runs |
+
+---
+
+## Catch-Up Policies
+
+Controls what happens with scheduled runs that were missed, for example during server downtime.
+
+| Policy | Behaviour |
+|--------|-----------|
+| `skip_missed` **(default)** | Missed runs are dropped |
+| `enqueue_missed_with_cap` | Missed runs are enqueued, capped at 25 |
+
+---
+
+## Activity-Gated Scheduled Runs
+
+`activityGatePolicy` controls whether a **schedule trigger** runs when the system has been quiet. It does not gate manual, API, or webhook runs.
+
+| Policy | Behaviour |
+|--------|-----------|
+| `always` **(default)** | Run on every scheduled tick |
+| `require_external_activity` | Run only when qualifying activity occurred after this routine's last dispatched, non-skipped run |
+
+`activityGateScope` selects where qualifying activity is checked:
+
+| Scope | Behaviour |
+|-------|-----------|
+| `company` **(default)** | Activity anywhere in the routine's company can wake it |
+| `project` | Only activity attributed to the routine's project can wake it |
+
+The activity window starts at the `triggeredAt` time of the last dispatched run. A routine that has never dispatched always runs once. Runs skipped for quiet activity do not advance the window, so one later qualifying event still wakes the next scheduled tick.
+
+The gate excludes activity generated by the routine's own dispatched run issues, scheduler bookkeeping for that routine, and pure-read actions such as issue read/unread changes and inbox archive/unarchive actions. Work performed by other agents on tasks the routine delegated is external activity and wakes the routine on its next tick.
+
+### Example: skip quiet nights
+
+This hourly watcher runs after company activity, follows up while delegated work continues, and stops consuming runs once the company settles overnight:
+
+```json
+{
+  "title": "Hourly work watcher",
+  "description": "Review recent work and follow up on delegated tasks",
+  "assigneeAgentId": "{agentId}",
+  "projectId": "{projectId}",
+  "activityGatePolicy": "require_external_activity",
+  "activityGateScope": "company"
+}
+```
+
+Add a schedule trigger with `cronExpression: "0 * * * *"`. The first tick runs. Later ticks run only after qualifying company activity since the last dispatched run; quiet skipped ticks keep the original activity window open.
+
+---
+
+## Adding Triggers
+
+A routine can have multiple triggers of different kinds.
+
+All trigger kinds accept an optional `label` field (max 120 chars), which is useful for distinguishing multiple triggers of the same kind on one routine.
+
+```
+POST /api/routines/{routineId}/triggers
+```
+
+### Schedule (cron)
+
+```json
+{
+  "kind": "schedule",
+  "cronExpression": "0 9 * * 1",
+  "timezone": "Europe/Amsterdam"
+}
+```
+
+- `cronExpression`: standard 5-field cron syntax
+- `timezone`: IANA timezone string (for example `UTC` or `America/New_York`)
+- The server computes `nextRunAt` automatically
+
+### Webhook
+
+```json
+{
+  "kind": "webhook",
+  "signingMode": "hmac_sha256",
+  "replayWindowSec": 300
+}
+```
+
+- `signingMode`: `bearer` (default) or `hmac_sha256`
+- `replayWindowSec`: 30-86400 (default 300)
+- Response includes the webhook URL (`publicId`-based) and the signing secret
+- Fire externally: `POST /api/routine-triggers/public/{publicId}/fire`
+  - Bearer: `Authorization: Bearer <secret>`
+  - HMAC: `X-Paperclip-Signature` + `X-Paperclip-Timestamp` headers
+
+### API (manual only)
+
+```json
+{
+  "kind": "api"
+}
+```
+
+No configuration. Fire via the manual run endpoint.
+
+---
+
+## Updating and Deleting Triggers
+
+```
+PATCH /api/routine-triggers/{triggerId}
+{ "enabled": false, "cronExpression": "0 10 * * 1" }
+
+DELETE /api/routine-triggers/{triggerId}
+```
+
+To rotate a webhook secret (the old secret is immediately invalidated):
+
+```
+POST /api/routine-triggers/{triggerId}/rotate-secret
+```
+
+---
+
+## Manual Run
+
+Fires a run immediately, bypassing the schedule. Concurrency policy still applies.
+
+```
+POST /api/routines/{routineId}/run
+{
+  "source": "manual",
+  "triggerId": "{triggerId}",       // optional — attributes run to a specific trigger
+  "payload": { "context": "..." }, // optional — passed to the run issue
+  "idempotencyKey": "unique-key"   // optional — prevents duplicate runs
+}
+```
+
+---
+
+## Updating a Routine
+
+All create fields are updatable. Agents cannot reassign a routine to another agent.
+
+```
+PATCH /api/routines/{routineId}
+{ "status": "paused", "title": "New title" }
+```
+
+---
+
+## Reading Routines and Runs
+
+```
+GET /api/companies/{companyId}/routines
+GET /api/routines/{routineId}
+GET /api/routines/{routineId}/runs?limit=50
+```
+
+Use the generic API endpoint tables in `skills/paperclip/references/api-reference.md` when you need a full cross-domain reference. Use this file when you need routine-specific behaviour, payload shape, or policy details.