@iamlbccc/tdxd 1.1.0 → 1.2.0

package/skills/paperclip/references/artifacts.md

@@ -0,0 +1,98 @@
+# Generated Artifacts and Work Products
+
+When work produces a user-inspectable file, upload true deliverables to the current issue before final disposition. Local filesystem paths are not enough because board users, reviewers, and cloud operators may not have access to the agent workspace.
+
+Use the helper bundled with this skill. From an installed `paperclip` skill directory, the helper lives at `scripts/paperclip-upload-artifact.sh`:
+
+```bash
+scripts/paperclip-upload-artifact.sh path/to/output.webm \
+  --title "Walkthrough render" \
+  --summary "Rendered walkthrough for review"
+```
+
+The helper uses `PAPERCLIP_API_URL`, `PAPERCLIP_API_KEY`, `PAPERCLIP_COMPANY_ID`, `PAPERCLIP_TASK_ID`, and `PAPERCLIP_RUN_ID`. It uploads the file as an issue attachment, creates an attachment-backed artifact work product by default, and prints issue-safe markdown links for your final comment.
+
+## Workspace-Only File References
+
+Use a workspace-only reference only when the file should stay in the project or
+execution workspace, such as a source file, committed report, generated index,
+or other file whose value is tied to the checkout. This is not a substitute for
+uploading a deliverable file that a board user should be able to inspect outside
+the workspace.
+
+Annotate the work product with `metadata.resourceRef`:
+
+```json
+{
+  "type": "document",
+  "provider": "workspace",
+  "title": "Regression test plan",
+  "status": "ready_for_review",
+  "reviewState": "needs_board_review",
+  "summary": "Markdown plan committed in the execution workspace.",
+  "metadata": {
+    "resourceRef": {
+      "kind": "workspace_file",
+      "issueId": "<issue-id>",
+      "workspaceKind": "execution_workspace",
+      "workspaceId": "<execution-workspace-id>",
+      "relativePath": "doc/plans/regression-test-plan.md",
+      "line": 1,
+      "displayPath": "doc/plans/regression-test-plan.md"
+    }
+  }
+}
+```
+
+`workspaceKind` is `execution_workspace` for the current issue checkout or
+`project_workspace` for a shared project workspace. `line` and `column` are
+optional positive integers. `relativePath` must be relative to the selected
+workspace root; do not use host-local absolute paths in `resourceRef`.
+
+Create the work product with:
+
+```bash
+curl -sS -X POST \
+  "$PAPERCLIP_API_URL/api/issues/$PAPERCLIP_TASK_ID/work-products" \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+  -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
+  -H "Content-Type: application/json" \
+  --data-binary @workspace-file-work-product.json
+```
+
+If the helper is unavailable, use the Paperclip API directly:
+
+```bash
+curl -sS -X POST \
+  "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/issues/$PAPERCLIP_TASK_ID/attachments" \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+  -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
+  -F 'file=@"path/to/output.webm";type=video/webm'
+```
+
+Then create a work product when the file is the deliverable. The server canonicalizes attachment-backed artifact metadata from the `attachmentId`:
+
+```bash
+curl -sS -X POST \
+  "$PAPERCLIP_API_URL/api/issues/$PAPERCLIP_TASK_ID/work-products" \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+  -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
+  -H "Content-Type: application/json" \
+  --data-binary '{
+    "type": "artifact",
+    "provider": "paperclip",
+    "title": "Walkthrough render",
+    "status": "ready_for_review",
+    "reviewState": "needs_board_review",
+    "isPrimary": true,
+    "metadata": { "attachmentId": "<uploaded-attachment-id>" }
+  }'
+```
+
+In your final issue comment, link the uploaded attachment or work product and
+describe what it contains. If the output is workspace-only, name the work
+product and the relative path that was recorded in `metadata.resourceRef`.
+Browse/search is the fallback for recovering a workspace file when the issue
+chip or link cannot open it; it is not the preferred deliverable path. Do not
+leave artifact-producing work `in_progress` with only a local path or a
+`Remaining` note.

package/skills/paperclip/references/cases.md

@@ -0,0 +1,295 @@
+# Cases
+
+Cases are agent-owned work records for durable outputs such as blog posts,
+research packets, release notes, incidents, QA runs, or generated asset sets.
+They are company-scoped and live beside issues: issues coordinate work, while
+cases preserve the structured object an agent is producing.
+
+Cases are experimental and must be enabled with `experimental.enableCases`.
+If a route returns `403 Cases are disabled`, stop and report that the operator
+must enable cases before the skill can use this surface.
+
+## Core Model
+
+A case has:
+
+- `identifier`: server-assigned display id such as `PAP-C42`
+- `caseType`: skill-owned type such as `blog_post`, `image_assets`, or `incident`
+- `key`: optional deterministic upsert key inside `(companyId, caseType)`
+- `title` and optional `summary`
+- `status`: `draft`, `in_progress`, `in_review`, `approved`, `done`, or `cancelled`
+- `fields`: JSON object owned by the skill using the case
+- `parentCaseId`: optional parent case for child work
+- documents, attachments, issue links, labels, and events
+
+Use deterministic `caseType` + `key` when a skill may be retried. Repeating
+`POST /api/companies/:companyId/cases` with the same `caseType` and `key`
+upserts the same case instead of creating a duplicate.
+
+## Upsert Semantics
+
+`POST /api/companies/:companyId/cases` creates or upserts a case.
+
+Request:
+
+```json
+{
+  "caseType": "blog_post",
+  "key": "launch-announcement",
+  "title": "Launch announcement",
+  "summary": "Draft launch post for operators.",
+  "status": "draft",
+  "fields": {
+    "slug": "launch-announcement",
+    "target_audience": "operators"
+  }
+}
+```
+
+Response:
+
+- `201` when a new case was created
+- `200` when an existing `(caseType, key)` case was updated
+
+Field behavior on upsert:
+
+- `title` is required and replaces the previous title.
+- `projectId`, `summary`, `status`, `fields`, and `parentCaseId` replace the
+  previous value when present.
+- Omitted optional values preserve the previous value during upsert.
+- `fields` is replaced as a whole object when provided. It is not deep-merged.
+  Send the complete desired JSON object each time.
+- Concurrent retries with the same `(caseType, key)` converge to one case.
+
+Do not use a random `key` for retryable skills. Use a stable content slug,
+external id, source URL hash, or parent-derived request key.
+
+## Read And Search
+
+Get a case by UUID or identifier:
+
+```http
+GET /api/cases/PAP-C42
+```
+
+List cases for a company:
+
+```http
+GET /api/companies/:companyId/cases?type=blog_post&status=active&q=launch
+```
+
+Useful filters:
+
+- `type`: exact `caseType`
+- `status`: exact lifecycle status, or `active` for non-terminal cases
+- `projectId` / `project`: project UUID
+- `labelId` / `label`: label UUID
+- `q`: identifier, title, summary, or key search
+- `limit`: 1-200, default 100
+
+## Documents
+
+Use case documents for rich bodies such as drafts, briefs, reports, or plans.
+
+```http
+PUT /api/cases/:caseIdOrIdentifier/documents/body
+Content-Type: application/json
+
+{
+  "title": "Launch announcement body",
+  "format": "markdown",
+  "body": "# Launch announcement\n\nDraft copy...",
+  "changeSummary": "Initial draft"
+}
+```
+
+Updating an existing case document requires `baseRevisionId`:
+
+```json
+{
+  "baseRevisionId": "latest-revision-uuid",
+  "body": "Updated body"
+}
+```
+
+If you get `409 stale_base_revision`, refetch the case detail, read the latest
+document revision id, merge intentionally, and retry with that `baseRevisionId`.
+
+## Fields
+
+Each skill owns the schema of `fields` for the `caseType` it creates. Keep fields
+small, typed, and stable enough for other agents to inspect.
+
+Examples:
+
+```json
+{
+  "slug": "launch-announcement",
+  "target_audience": "operators",
+  "publish_url": "https://example.com/blog/launch-announcement"
+}
+```
+
+Patch fields or status with:
+
+```http
+PATCH /api/cases/:caseIdOrIdentifier
+Content-Type: application/json
+
+{
+  "status": "in_review",
+  "fields": {
+    "slug": "launch-announcement",
+    "target_audience": "operators",
+    "publish_url": "https://example.com/blog/launch-announcement"
+  }
+}
+```
+
+Remember: `fields` replaces the whole object when present.
+
+## Issue Links
+
+Link cases to issues explicitly when needed:
+
+```http
+POST /api/cases/:caseIdOrIdentifier/links
+Content-Type: application/json
+
+{
+  "issueId": "issue-uuid",
+  "role": "reference"
+}
+```
+
+Roles:
+
+- `origin`: the issue/run that created the case
+- `work`: an issue/run that changed the case
+- `reference`: related issue context
+
+Agent run writes auto-link the run's issue when Paperclip can resolve it from
+the run JWT or `X-Paperclip-Run-Id`. Creation/upsert writes use `origin`; later
+document, patch, and attachment writes use `work` when no link already exists.
+You do not need to manually link the current issue before writing the case.
+
+## Child Cases
+
+Create child cases by setting `parentCaseId` to the parent case UUID.
+
+```json
+{
+  "caseType": "image_assets",
+  "key": "launch-announcement:hero-images",
+  "title": "Hero images for launch announcement",
+  "parentCaseId": "parent-case-uuid",
+  "fields": {
+    "required_assets": ["hero", "social-card"]
+  }
+}
+```
+
+Use child cases when the output has independently inspectable pieces or when
+another agent can work on a bounded part without editing the parent case body.
+
+## Attachments
+
+Attach generated files with multipart form data:
+
+```http
+POST /api/cases/:caseIdOrIdentifier/attachments
+Content-Type: multipart/form-data
+
+file=@hero.png
+```
+
+The server records an asset and adds an `attachment_added` case event.
+
+## Lifecycle
+
+Use the lifecycle consistently:
+
+- `draft`: case exists but useful work has not started
+- `in_progress`: an agent is actively producing or revising it
+- `in_review`: ready for reviewer, board, or downstream approval
+- `approved`: accepted but not finally shipped or archived
+- `done`: complete and no further action remains
+- `cancelled`: intentionally abandoned
+
+Terminal statuses are `done` and `cancelled`; setting either records
+`completedAt`. Moving back to a non-terminal status clears `completedAt`.
+
+## Worked Blog Post Example
+
+Create or upsert the parent blog post:
+
+```http
+POST /api/companies/:companyId/cases
+Content-Type: application/json
+
+{
+  "caseType": "blog_post",
+  "key": "paperclip-cases-launch",
+  "title": "Introducing Paperclip Cases",
+  "summary": "Blog post explaining the cases surface for agent outputs.",
+  "status": "in_progress",
+  "fields": {
+    "slug": "paperclip-cases-launch",
+    "target_audience": "AI company operators",
+    "publish_url": null
+  }
+}
+```
+
+Write the body:
+
+```http
+PUT /api/cases/PAP-C42/documents/body
+Content-Type: application/json
+
+{
+  "title": "Introducing Paperclip Cases",
+  "format": "markdown",
+  "body": "# Introducing Paperclip Cases\n\n..."
+}
+```
+
+Create the child image-assets case:
+
+```http
+POST /api/companies/:companyId/cases
+Content-Type: application/json
+
+{
+  "caseType": "image_assets",
+  "key": "paperclip-cases-launch:image-assets",
+  "title": "Image assets for Introducing Paperclip Cases",
+  "parentCaseId": "parent-case-uuid",
+  "status": "in_progress",
+  "fields": {
+    "slug": "paperclip-cases-launch",
+    "required_assets": ["hero", "social-card"],
+    "publish_url": null
+  }
+}
+```
+
+Attach generated assets to the child, then patch both cases as they move through
+review:
+
+```http
+PATCH /api/cases/PAP-C42
+Content-Type: application/json
+
+{
+  "status": "in_review",
+  "fields": {
+    "slug": "paperclip-cases-launch",
+    "target_audience": "AI company operators",
+    "publish_url": "https://example.com/blog/paperclip-cases-launch"
+  }
+}
+```
+
+If the same skill retries the example with the same keys, it updates the parent
+and child cases rather than creating duplicates.

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 `@paperclipai/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
+`paperclipai 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.