From 2ff55391270e743e4caa456436c61f20d30a4600 Mon Sep 17 00:00:00 2001 From: Aron Prins Date: Mon, 22 Jun 2026 11:42:03 +0200 Subject: [PATCH] nightly: skills "required" retirement, paperclip-dev cleanup, task watchdogs guide (paperclip d1e6662e) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Round 2 — worked the human-review items, verified each against parent source: - Skills: the per-agent `required` attribute is retired upstream (AgentSkillEntry dropped required/requiredReason; AgentSkillOrigin dropped paperclip_required; resolveDesiredSkillAssignment now persists exactly the desired set with no bundled union). Fixed reference/skills.md and reference/cli/skills.md: removed "non-required" qualifiers, the retired `required` frontmatter row, the wrong "forced into every agent" claim, and corrected the snapshot example + the UI grouping (Company skills + Unmanaged, no "Required" group). - paperclip-dev skill removed upstream: dropped from the bundled list and swapped stale source/key examples to paperclip-create-agent. - Experimental features: strengthened the settings.md caution to match the new in-app "no compatibility guarantees" warning. - Task watchdogs: new operator guide page (guides/projects-workflow/ task-watchdogs.md) + nav entry. API/config/behaviour verified against routes/issues.ts, schema/issue_watchdogs.ts, and doc/TASK-WATCHDOG.md intent. Reviewed, no change needed: instance-scoped environments (routes still match docs), skills store (UI reframe; guide already accurate), plugin-sdk lease params (fields not documented). verify-edit all clean; build/links/nav/drift all green. Co-Authored-By: Claude Opus 4.8 (1M context) --- PENDING.md | 47 +++----- docs/administration/settings.md | 2 +- .../projects-workflow/task-watchdogs.md | 114 ++++++++++++++++++ docs/reference/cli/skills.md | 14 +-- docs/reference/skills.md | 26 ++-- site/content.json | 4 + 6 files changed, 155 insertions(+), 52 deletions(-) create mode 100644 docs/guides/projects-workflow/task-watchdogs.md diff --git a/PENDING.md b/PENDING.md index 66da611..c090fcf 100644 --- a/PENDING.md +++ b/PENDING.md @@ -4,37 +4,26 @@ _Regenerated by `/sync-docs` on 2026-06-22 (nightly mode). Cumulative window: pa This file is overwritten each run — it always reflects the current cumulative manifest, not an append log. -## ✅ Applied to `nightly` this run (PR-tier, verified against parent) +## ✅ Applied to `nightly` this run (verified against parent) -| Surface | Doc target | Change | Parent evidence | -|---|---|---|---| -| codex-local: inactivity monitor | `docs/reference/adapters/codex-local.md` | New `outputInactivityTimeoutMs` config field (default 7 min, `null` disables) | `packages/adapters/codex-local/src/index.ts`, `output-inactivity-monitor.ts` (#5017) | -| codex-local: host login inheritance | `docs/reference/adapters/codex-local.md` | New "Authentication And Per-Agent Homes" section — agents inherit host Codex login by default; per-agent home seeding; fail-fast on no creds | `codex-home.ts`, commit `d1e6662e` (#8425) | -| gemini-local: execution model | `docs/reference/adapters/gemini-local.md` | Note now states `--prompt` (not stdin) + headless-safe terminal/browser env for unattended runs | `packages/adapters/gemini-local/src/index.ts`, `execute.ts` | -| CLI `auth login --no-browser` | `docs/reference/cli/authentication.md` | New flag: print approval URL instead of opening a browser | `cli/src/commands/client/auth.ts` | +| Surface | Doc target | Change | +|---|---|---| +| codex-local: inactivity monitor | `reference/adapters/codex-local.md` | New `outputInactivityTimeoutMs` config field (default 7 min / `420000`, `null` disables) | +| codex-local: host login inheritance | `reference/adapters/codex-local.md` | New "Authentication And Per-Agent Homes" section — agents inherit host Codex login by default; per-agent home seeding; fail-fast on no creds | +| gemini-local: execution model | `reference/adapters/gemini-local.md` | Note now states `--prompt` (not stdin) + headless-safe terminal/browser env | +| CLI `auth login --no-browser` | `reference/cli/authentication.md` | New flag: print approval URL instead of opening a browser | +| Skills: `required` attribute retired | `reference/cli/skills.md`, `reference/skills.md` | Dropped "non-required" qualifiers; removed `required`/`requiredReason` snapshot fields + `paperclip_required` origin; corrected "bundled skills forced into desired set" → exact desired-set resolution; UI grouping is now Company skills + Unmanaged (no "Required" group); removed retired `required` frontmatter row | +| `paperclip-dev` skill removed | `reference/skills.md` | Removed from bundled list; replaced stale `paperclip-dev` source/key examples with `paperclip-create-agent` | +| Experimental features caution | `administration/settings.md` | Strengthened to match the new in-app warning (no compatibility guarantees; may break/change/be removed) | +| **Task watchdogs (new feature)** | `guides/projects-workflow/task-watchdogs.md` **(new page)** + `site/content.json` nav | New operator guide: what it is, when it wakes, how to set one (UI + `GET/PUT/DELETE /api/issues/:id/watchdog`), writing instructions, hard limits, when-not-to-use | -Verification: codex-local 38/40, gemini-local 27/28, authentication 37/37 claims verified. The 2 unverified records (`my-gateway`, `secret-id`) are pre-existing illustrative example placeholders, not this run's edits. +Verification (verify-edit against `master`): codex-local 38/40, gemini-local 27/28, authentication 37/37, reference/skills 7/7, cli/skills 37/37 — all clean. The only unverified records (`my-gateway`, `secret-id`) are pre-existing example placeholders, not this run's edits. Build ✓, links ✓, nav ✓ (133 entries), drift ✓. -## ⚠ Surfaced for human review (NOT auto-applied) +## ✓ Reviewed — no doc change needed -These are user-visible but need judgement, touch multiple files, involve a removal, or need a new doc home + screenshots. Decide and draft manually. - -1. **Skills: "required skill attribute" retired** (#7029, `33353ce` + `skills.ts`, `shared/src/types/adapter-skills.ts -3`, `validators/adapter-skills.ts -3`). - - The per-agent *desired-skill* `required` attribute was removed; CLI `skills agent sync/clear` descriptions dropped the "non-required" qualifier and the snapshot no longer prints a `required` column. Bundled/server-enforced (`paperclip_required`) skills still exist. - - Affected docs (currently describe `required`/`non-required`/server-enforced wording): `docs/reference/cli/skills.md` (lines ~20, 23, 165, 175–177, 181), `docs/reference/skills.md` (lines ~54, 326, 336, 352–393). - - **Why not auto:** semantic removal — risk of mis-documenting which "required" notion survived. Verify against `packages/shared/src/validators/adapter-skills.ts` before editing. - -2. **`skills/paperclip-dev/SKILL.md` removed** (#7029). The bundled `paperclip-dev` skill was deleted from parent. Drift checker found no `.ts/.mjs` refs, but `paperclip-dev` is named in: `docs/reference/cli/common-options.md`, `setup-commands.md`, `installation.md`, `deploy/environment-variables.md`, `reference/skills.md`. Confirm whether these references should be removed/updated. - -3. **Execution environments are now instance-scoped** (#8375 `547463d3`, migration `0105_instance_scoped_environments.sql`). Large UI rewrite (`CompanyEnvironments.tsx` +453/-396), routes (`environments.ts`, `instance-settings.ts`), services. Environments moved from company-scoped to instance-scoped; create/edit moved into a dialog (#8391); adapter support matrix table removed (#8398). → Needs review of any environments guide/CLI page + screenshot refresh. - -4. **Task watchdogs** — major new feature. New `server/src/services/task-watchdogs.ts` (+1565), `task-watchdog-scope.ts`, routes in `issues.ts` (+801), migration `0104_issue_watchdogs.sql`, schema `issue_watchdogs.ts`, UI `task-watchdog-surfaces.stories.tsx`. Parent added internal `doc/TASK-WATCHDOG.md`. → No doc home yet; decide whether/where to document for operators. - -5. **Experimental features (operator-facing)** (#8382 `fce3b439`). New `InstanceExperimentalSettings.tsx` warning + CLI surface `paperclipai instance settings:experimental[:update]` and `settings:general[:update]`. Parent added `docs/guides/board-operator/experimental-features.md` and a control-plane CLI section. → Consider adding the CLI commands to the reference + a short "experimental features" operator note. Screenshot `settings/experimental.png` is stale. - -6. **Skills store** — parent added `docs/guides/agent-developer/skills-store.md`; `server/src/services/skills-catalog.ts` (+126/-15), `company-skills`. → Review whether `docs/reference/skills.md` / `docs/guides/org/skills.md` need a "skills store" framing update. - -7. **Plugin SDK lease params** — `packages/plugins/sdk/src/protocol.ts` added `agentId` and `executionWorkspaceId?` to `PluginEnvironmentAcquireLeaseParams`. Minor; relevant to environment-driver plugin authors. → Optional touch-up to `docs/reference/plugins/sdk.md`. +- **Instance-scoped execution environments** (#8375 `547463d3`). Checked every documented environment route in `reference/api/instance-admin.md` against current `routes/environments.ts` — all still present and correct (including `POST .../environments/probe-config`). No doc prose claims company-scoping. Impact is UI/storage only → handled by screenshot refresh below. +- **Skills store** (#skills-catalog). Our `guides/org/skills.md` describes the Skills page functionally and accurately. "Skills Store" is a UI nav reframe of the existing catalog + company library; no rendered heading cleanly confirmed, so no terminology edit forced — screenshot recapture will surface any naming. +- **Plugin SDK lease params** — `protocol.ts` added `agentId` / `executionWorkspaceId?` to `PluginEnvironmentAcquireLeaseParams`. `reference/plugins/sdk.md` only lists the type name, not its fields, so nothing to update. ## ⚠ Drift (Phase 1.5) @@ -42,8 +31,8 @@ None. Drift checker against `master` returned 0 records. ## ↻ Reconciliation (Phase 3.5) -None. No previously-applied manifest entries disappeared (prior state carried no `last_applied_manifest_hash`). +None. ## 📸 Screenshots -80 of 276 registry entries are stale (heavy UI churn in `ui/src/**`). See `SCREENSHOTS_PENDING.md`. Run `npm run screenshots:refresh` and review the resulting PR. +80 of 276 registry entries are stale (heavy UI churn in `ui/src/**`, incl. agents, issues, routines, environments, experimental settings). See `SCREENSHOTS_PENDING.md`. Run `npm run screenshots:refresh` and review the resulting PR. Task-watchdog UI surfaces (issue properties / new-issue dialog) are not yet in the screenshot registry — add captures when the feature stabilizes. diff --git a/docs/administration/settings.md b/docs/administration/settings.md index e850853..5fd39d0 100644 --- a/docs/administration/settings.md +++ b/docs/administration/settings.md @@ -243,7 +243,7 @@ An experimental flag in Paperclip is a feature that: - Is being evaluated against real usage before it becomes the default, and - May be renamed, reworked, or promoted to a core setting in a future release. -Turning one on is not dangerous in the "this will break your data" sense — but it does mean you're opting into behavior that may change how agents run or how the backend restarts. Flip flags when you have a reason to, not for curiosity, and expect to re-read the release notes if you upgrade. +Turning one on is not dangerous in the "this will break your data" sense — but experimental features come **without compatibility guarantees**. They may break, change, or be removed at any time, and Paperclip doesn't promise migration or long-term support for them. The app shows a warning to this effect when you enable one. Flip flags when you have a reason to, not for curiosity; don't lean on an experimental feature for a workflow that has to stay stable, and expect to re-read the release notes if you upgrade. ### The available flags diff --git a/docs/guides/projects-workflow/task-watchdogs.md b/docs/guides/projects-workflow/task-watchdogs.md new file mode 100644 index 0000000..2ac052f --- /dev/null +++ b/docs/guides/projects-workflow/task-watchdogs.md @@ -0,0 +1,114 @@ +# Task Watchdogs + +Sometimes an agent stops work for the wrong reason. It misreads a blocker, declares an issue "done" without real proof, accepts a stale plan confirmation, or hits a recoverable error and gives up. When that happens, nothing wakes anyone — the issue tree just goes quiet and sits there. + +A **task watchdog** is an agent you put in charge of double-checking a stopped issue tree and putting it back into motion when stopping was a mistake. You attach it to one issue; it watches that issue and its descendants. When everything in that subtree has come to rest and there's no live path forward, Paperclip wakes the watchdog to read the evidence and decide whether the stop is genuine — or whether work should continue. + +Think of it as a second pass on stopped work, without re-running the original assignee. It's verification-shaped, not execution-shaped: it checks what other agents claimed against what's actually in the thread, then either accepts the stop or restores a live path. + +> **Heads up:** Watchdogs are opt-in, per issue. There's no global "watch everything" switch — you decide which trees are worth the extra pass. + +--- + +## Three things called "watchdog" + +The word shows up in a few places in Paperclip. Keep them straight: + +- **Task watchdog** (this page) — an agent *you* assign to a specific issue. Fires only when the whole watched subtree has stopped. Configurable. +- **Silent active-run watchdog** — automatic monitoring of a single *running* agent for output silence. No configuration, nothing to set up. (See your adapter's inactivity settings, e.g. codex-local's `outputInactivityTimeoutMs`.) +- **Liveness recovery** — automatic restart of stalled agent-owned issues. + +Only the first one is something you turn on by hand. + +--- + +## When a watchdog wakes + +A watchdog stays asleep while there's still live work to do. It wakes only when **every leaf** in the watched subtree has come to rest — done, cancelled, blocked, in review, or waiting on an interaction — and there's no continuation path left to follow. + +At that point Paperclip hands the watchdog agent the tree and a mandate: treat every stopped leaf as a *claim* that has to be verified, not a fact to be trusted. The watchdog then: + +- **Leaves genuinely-finished leaves alone**, with a short note on what it checked. +- **Restores a live path** when a leaf isn't really done — by reopening the issue, reassigning it, commenting actionable next steps, opening a follow-up child issue inside the watched subtree, or accepting an eligible plan confirmation. +- **Confirms real blockers**, leaving a clear waiting state that names who can unblock it and what happens next. + +It will not take "I couldn't" or "waiting for approval" at face value — that's the whole point. + +--- + +## Set a watchdog + +A watchdog has three parts: + +| Field | Required | What it is | +|---|---|---| +| Watched issue | yes | The issue you attach the watchdog to. Set implicitly — it's whichever issue you're editing. | +| Watchdog agent | yes | Any agent in the same company that can be invoked. It can't be paused, terminated, or out of budget. | +| Instructions | no | Free-form text. Use it to narrow focus or refuse specific shortcuts. It can't grant the watchdog more authority. | + +An issue can have **at most one active watchdog**. Re-assigning the agent or editing the instructions resets the watchdog's memory of what it already reviewed, so the next scan starts fresh. + +### From the app + +Two places let you set one: + +- **New issue dialog** — open the three-dot menu and pick the **Watchdog** row. Choose an agent and, optionally, type instructions. The watchdog is created together with the issue, and a chip in the dialog footer shows your choice. +- **Issue properties** — find the **Watchdog** row next to **Monitor**. It reads `Set watchdog` when empty; once configured it shows the agent and a preview of your instructions. Click it to open the editor, where you pick an agent, write instructions, and hit **Set watchdog** (or **Update**). There's a **Remove** button too. When a watchdog run has spun up a review task, the row shows a small badge linking straight to it. + +### From the API + +```http +GET /api/issues/:issueId/watchdog +PUT /api/issues/:issueId/watchdog { "agentId": "...", "instructions": "..." } +DELETE /api/issues/:issueId/watchdog +``` + +`PUT` is an upsert — it creates the watchdog or updates the existing one. `DELETE` disables it (the row is kept for audit history, not hard-deleted). All three need write access to the watched issue, and each one writes an activity record (`issue.watchdog_created`, `issue.watchdog_updated`, `issue.watchdog_removed`) with the actor and run id. + +--- + +## Writing good instructions + +Instructions work best when they tell the watchdog *what evidence to look at* and *what shortcuts to refuse*. For example: + +> Before accepting any leaf as done, check there's a green CI run linked in the comments. If there isn't, reopen the leaf and ask for one. + +> Don't accept a plan that proposes more than five subtasks without my review. Leave the issue in review and ping me. + +> If a leaf is blocked on the marketing team, accept the wait — but make sure the blocker names who can unblock it. + +What instructions **can't** do: reach outside the watched subtree, approve board-level decisions, expand the kinds of interactions the watchdog can resolve, or relax its safety limits. The server enforces those boundaries no matter what the instructions say. + +--- + +## What a watchdog can't do + +A watchdog operates under hard, server-enforced limits — custom instructions can tighten them but never loosen them: + +- It stays **inside the watched subtree**. No changes to issues outside that tree, and nothing cross-company. +- It **can't approve board-only decisions** — spend, hiring, security-sensitive interactions — or bypass an execution-policy stage that requires a named reviewer or approver. +- It **can't touch its own configuration** or create another watchdog for the same tree, and it can't wake itself. + +Any move that crosses those lines is rejected at the API layer, so the watchdog has to take a legitimate path instead: comment, open an in-subtree follow-up, leave a valid waiting state, or escalate to a human. + +--- + +## When not to use one + +A task watchdog earns its keep when a tree has many leaves and you want a second pass before trusting "all green," when the original assignee tends to call things done too early, or when the work matters enough that a missed false-stop is worth an extra agent run. + +It's the wrong tool when you want to: + +- **Watch a single running process for silence** — that's the automatic silent active-run watchdog, no setup needed. +- **Recover a stalled agent-owned issue** — that's automatic too. +- **Gate board-level or security-sensitive decisions** — a watchdog can't resolve those. +- **Stand in for a human reviewer** on a typed execution-policy stage — it can't bypass typed participants. + +And if what you really want is "wake me when this is done," reach for a [routine](./routines.md) or an issue-thread interaction instead. + +--- + +## Where to go next + +- [Heartbeats & Routines](./routines.md) — timer- and event-driven wakes, the other way to keep work moving. +- [Projects](./projects.md) — how issue trees are organized in the first place. diff --git a/docs/reference/cli/skills.md b/docs/reference/cli/skills.md index 61354d1..302700b 100644 --- a/docs/reference/cli/skills.md +++ b/docs/reference/cli/skills.md @@ -17,10 +17,10 @@ There are two command groups. The plural `paperclipai skills` group is the one y | Operation | Commands | What it changes | | --- | --- | --- | | **Company install** | `skills install`, `import`, `create`, `scan-projects` | Adds or updates a skill in the company's library. Available to the whole company; does **not** attach it to any agent. | -| **Agent attach** | `skills agent sync`, `skills agent clear` | Replaces an agent's *desired* (non-required) company-skill set. A desired-state operation — it is not additive. | +| **Agent attach** | `skills agent sync`, `skills agent clear` | Replaces an agent's *desired* company-skill set. A desired-state operation — it is not additive. | | **Adapter runtime sync** | reported by `skills agent list`; triggered by `sync`/`clear` | The server-side adapter reconciles the desired set with files on disk and returns an `AgentSkillSnapshot`. | -> **Note:** Required Paperclip runtime skills (heartbeat and friends) are enforced by the server. They always remain on an agent — `skills agent clear` only removes the *non-required* desired skills you added. +> **Note:** `skills agent sync` and `skills agent clear` operate on the agent's full desired set — `clear` empties it. Bundled Paperclip skills still live in the company library as read-only entries, but the server no longer force-attaches them to an agent. > **Tip:** Add `--json` to any command to print the raw API result for scripting. Every company-scoped command takes `--company-id ` (and respects your selected profile/context). See [common options](./common-options.md). @@ -162,7 +162,7 @@ paperclipai skills remove --yes --company-id ## Agent attach: desired skills -Once a skill is in the library, attaching it to an agent is a desired-state replacement, not an addition. `skills agent sync` sets the agent's full non-required desired set; anything you omit is dropped. The adapter then reconciles and the command returns an `AgentSkillSnapshot`. +Once a skill is in the library, attaching it to an agent is a desired-state replacement, not an addition. `skills agent sync` sets the agent's full desired set; anything you omit is dropped. The adapter then reconciles and the command returns an `AgentSkillSnapshot`. ```sh paperclipai skills agent list --company-id @@ -172,16 +172,16 @@ paperclipai skills agent clear --yes --company-id | Command | Use | | --- | --- | -| `agent list ` | Show the agent's runtime skill snapshot: adapter type, whether sync is `supported`, the `mode`, the desired count, and per-skill runtime entries (state, origin, managed/required flags). | -| `agent sync ` | Replace the agent's non-required desired company skills and sync runtime state. Requires at least one `--skill`. | -| `agent clear ` | Clear the non-required desired set (sends an empty list). Prompts in a TTY; requires `--yes` otherwise. | +| `agent list ` | Show the agent's runtime skill snapshot: adapter type, whether sync is `supported`, the `mode`, the desired count, and per-skill runtime entries (state, origin, managed flag). | +| `agent sync ` | Replace the agent's desired company skills and sync runtime state. Requires at least one `--skill`. | +| `agent clear ` | Clear the desired set (sends an empty list). Prompts in a TTY; requires `--yes` otherwise. | | Flag | Use | | --- | --- | | `--skill ` | (`sync`) A desired company skill `id`, `key`, or `slug`. Repeat for several. At least one is required. | | `--yes` | (`clear`) Confirm without the interactive prompt. | -An `` is an agent `id` or shortname/url-key. Because `sync` is a full replacement, list the complete desired set every time. Required Paperclip skills survive both `sync` and `clear` — the server keeps enforcing them. +An `` is an agent `id` or shortname/url-key. Because `sync` is a full replacement, list the complete desired set every time — anything you omit is detached, and `clear` detaches everything. --- diff --git a/docs/reference/skills.md b/docs/reference/skills.md index 916dc6e..48bdb54 100644 --- a/docs/reference/skills.md +++ b/docs/reference/skills.md @@ -51,7 +51,6 @@ The frontmatter is parsed by Paperclip's own minimal YAML reader (`parseFrontmat | `name` | recommended | string | Human-readable label. Falls back to the slug when missing. | | `description` | recommended | string | The routing logic the agent reads first. Block scalars (`>`, `|`) are supported. | | `slug` | optional | string | Stable kebab-case identifier. Derived from `name` (or the folder name) if absent, normalized via `normalizeAgentUrlKey`. | -| `required` | optional | boolean | Most installs leave this `false`. The server itself only treats bundled Paperclip skills as required at runtime. | | `key` / `skillKey` | optional | string | Canonical key override. See [Naming collisions](#naming-collisions-and-resolution). | | `metadata` | optional | object | Arbitrary record persisted alongside the skill. Recognised sub-fields are listed below. | @@ -92,7 +91,6 @@ Bundled with the Paperclip server (`skills/` next to the server): - `paperclip` — base heartbeat procedure. - `paperclip-board` — manage a company as a board member via chat: onboarding (company creation, CEO setup, hiring plans), agent management, approvals, task monitoring, cost oversight, and work-product review. Set up by `paperclipai board setup`. - `paperclip-create-agent` — governance-aware hire workflow. -- `paperclip-dev` — operating a local Paperclip instance. - `paperclip-converting-plans-to-tasks` — the Paperclip way of translating a plan into assigned issues with the right specialty, dependencies, and parallelization. - `para-memory-files` — file-based memory using Tiago Forte's PARA method, covering the knowledge-graph, daily-notes, and tacit-knowledge layers plus weekly synthesis and recall. @@ -149,9 +147,9 @@ Mutating routes require either `agents:create` permission or `permissions.canCre { "source": "https://github.com/paperclipai/paperclip/tree/main/skills/paperclip" } { "source": "https://github.com/paperclipai/paperclip/blob/main/skills/paperclip/SKILL.md" } { "source": "paperclipai/paperclip" } -{ "source": "paperclipai/paperclip/paperclip-dev" } -{ "source": "https://skills.sh/paperclipai/paperclip/paperclip-dev" } -{ "source": "npx skills add paperclipai/paperclip --skill paperclip-dev" } +{ "source": "paperclipai/paperclip/paperclip-create-agent" } +{ "source": "https://skills.sh/paperclipai/paperclip/paperclip-create-agent" } +{ "source": "npx skills add paperclipai/paperclip --skill paperclip-create-agent" } { "source": "https://example.com/raw/SKILL.md" } { "source": "/Users/me/code/my-project/skills/code-review" } ``` @@ -323,7 +321,7 @@ Each entry can be: - a canonical **key** (`paperclipai/paperclip/paperclip`), - or a **slug** (`code-review`) — but only when the slug is unique inside the company. -The server resolves each reference (`resolveRequestedSkillKeys`), unions the result with all bundled-required keys, and persists the final list under `adapterConfig.paperclipSkillSync.desiredSkills`. Unknown or ambiguous references fail the request with `Invalid company skill selection (...)`. +The server resolves each reference to its canonical key and persists exactly that list under `adapterConfig.paperclipSkillSync.desiredSkills` — the desired set is precisely what you send, with no extra keys folded in. Unknown or ambiguous references fail the request with `Invalid company skill selection (...)`. ### After hire — `POST /api/agents/{agentId}/skills/sync` @@ -333,7 +331,7 @@ The server resolves each reference (`resolveRequestedSkillKeys`), unions the res } ``` -This route reconciles the agent's attachments to match exactly what you send: any skill in the list is attached, anything not in the list is detached. Bundled-required skills cannot be removed — they are always added back to the resolved set. +This route reconciles the agent's attachments to match exactly what you send: any skill in the list is attached, anything not in the list is detached. An empty list detaches everything. The response is an `AgentSkillSnapshot`: @@ -349,9 +347,8 @@ The response is an `AgentSkillSnapshot`: "runtimeName": "paperclip", "desired": true, "managed": true, - "required": true, "state": "installed", - "origin": "paperclip_required" + "origin": "company_managed" } ], "warnings": [] @@ -386,13 +383,12 @@ Returns the same snapshot shape without changing anything. For adapters without Adapters declare which materialisation strategy they need via `requiresMaterializedRuntimeSkills` (or fall back to a legacy hardcoded set: `cursor`, `gemini_local`, `opencode_local`, `pi_local`). -**Bundled skills are always available.** `paperclip` and any other skill marked `paperclip_bundled` are forced into every agent's resolved set, regardless of `desiredSkills`. This is enforced in `resolveDesiredSkillAssignment`. +**Bundled skills live in the library.** `paperclip` and any other skill marked `paperclip_bundled` are imported into the company library as read-only entries. They are no longer force-added to an agent's resolved set — `resolveDesiredSkillAssignment` now persists exactly the desired set you sync, nothing more. -**Required vs. optional in the UI.** The Agent → Skills tab splits the company library into three groups: +**Managed vs. unmanaged in the UI.** The Agent → Skills tab shows two groups: -- **Required** — bundled-required skills the adapter cannot drop. -- **Optional** — every other installed skill, opt-in via checkbox. -- **Unmanaged** — read-only entries surfaced when an adapter reports skills it discovered itself (for example, a global skills bundle on the host machine). +- **Company skills** — every installed library skill, each opt-in via checkbox. What you tick becomes the agent's desired set. +- **Unmanaged** — read-only entries (collapsed by default) surfaced when an adapter reports skills it discovered itself (for example, a global skills bundle on the host machine). These carry a `user_installed` or `external_unknown` origin and cannot be edited from here. --- @@ -423,7 +419,7 @@ Every persisted skill has a `key` field — the unique identifier for that skill | Source | Key form | Example | |---|---|---| | Bundled with Paperclip | `paperclipai/paperclip/{slug}` | `paperclipai/paperclip/paperclip` | -| GitHub / skills.sh | `{owner}/{repo}/{slug}` | `paperclipai/paperclip/paperclip-dev` | +| GitHub / skills.sh | `{owner}/{repo}/{slug}` | `paperclipai/paperclip/paperclip-create-agent` | | URL | `url/{host}/{hash}/{slug}` | `url/example.com/9f2a3b1c4d/code-review` | | Local path (project scan, raw folder) | `local/{hash}/{slug}` | `local/4e8a91c2d3/code-review` | | Paperclip-managed (created from the UI) | `company/{companyId}/{slug}` | `company/5cbe79ee.../delegation-checklist` | diff --git a/site/content.json b/site/content.json index e1ebc8c..89c8779 100644 --- a/site/content.json +++ b/site/content.json @@ -137,6 +137,10 @@ { "title": "Execution Workspaces", "file": "../docs/guides/projects-workflow/workspaces.md" + }, + { + "title": "Task Watchdogs", + "file": "../docs/guides/projects-workflow/task-watchdogs.md" } ] },