forked from farhoodlabs/paperclip
Dotta
9eac727cf1
## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies through company-scoped control-plane workflows. > - Agents need reusable, inspectable skills that can be installed, reset, audited, exported, and assigned without bespoke local setup. > - The existing skill truth model needed cleanup so bundled skills, optional catalog skills, runtime skills, and adapter-provided skills have clear provenance. > - Operators also need a practical CLI and board UI for discovering and managing company skills. > - This pull request adds the skills CLI, packaged skills catalog, company skills APIs, and catalog-aware board UI. > - The benefit is a more reusable Paperclip company setup where skills are portable, auditable, and easier for operators and agents to manage. ## What Changed - Added `paperclipai skills` CLI commands and coverage for catalog listing, installing, resetting, and inspecting company skills. - Added a packaged `@paperclipai/skills-catalog` workspace with bundled and optional skill content plus validation/build tests. - Added shared company-skill types and validators used across CLI, server, and UI contracts. - Added server catalog APIs/services for company skill catalog operations, reset semantics, audit behavior, and portability provenance. - Updated adapter skill handling so runtime/catalog provenance remains explicit across local adapters. - Added board UI support for browsing and managing catalog-backed company skills. - Updated docs for the skills CLI/catalog flow and the company skills Paperclip skill reference. - Rebased the branch onto current `paperclipai/paperclip:master`; no `pnpm-lock.yaml`, `.github/workflows`, or migration files are included in the final PR diff. ## Verification - Passed: `pnpm run preflight:workspace-links && pnpm exec vitest run cli/src/__tests__/skills.test.ts packages/skills-catalog/src/catalog-builder.test.ts packages/skills-catalog/src/shipped-catalog.test.ts packages/shared/src/validators/company-skill.test.ts packages/adapter-utils/src/server-utils.test.ts packages/plugins/create-paperclip-plugin/src/entrypoints.test.ts server/src/__tests__/company-skills-catalog-service.test.ts server/src/__tests__/company-skills-routes.test.ts server/src/__tests__/company-portability.test.ts`. - Passed: `pnpm exec vitest run server/src/__tests__/workspace-runtime.test.ts -t "default branch|origin/master|symbolic-ref"`. - Attempted: full `server/src/__tests__/workspace-runtime.test.ts`. Four provisioning tests failed while seeding an isolated worktree database from the local Paperclip instance because the local plugin schema dump contains a duplicate-column foreign key (`plugin_content_machine_18a7bc327b.content_case_signals`). The default-branch tests touched by the rebase conflict passed in the focused run above. - Checked final diff: no `pnpm-lock.yaml`, no `.github/workflows`, and no migration-file changes relative to `master`. ## Risks - Medium: this is a broad skills/catalog change touching CLI, server APIs, shared contracts, adapter skill sync, and UI. - Catalog validation and reset semantics need careful reviewer attention because they affect reusable company setup and portability. - No database migrations are included in this PR, so there is no migration ordering/idempotency risk in the final diff. - No lockfile is included by design; dependency resolution will be handled by the repository lockfile workflow. ## Model Used - OpenAI Codex coding agent based on GPT-5, running in Paperclip via the `codex_local` adapter with shell, git, GitHub CLI, and code-editing tool access. Exact hosted model build/context-window metadata is not exposed in this runtime. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have run targeted tests locally and documented the local workspace-runtime seed failure above - [x] I have added or updated tests where applicable - [x] If this change affects the UI, screenshots were intentionally omitted per PAP-10124 instructions; UI behavior is covered by tests and reviewer inspection - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
414 lines
9.7 KiB
Markdown
414 lines
9.7 KiB
Markdown
# 2026-03-14 Adapter Skill Sync Rollout
|
||
|
||
Status: Implemented for local adapters; gateway remains unsupported
|
||
Date: 2026-03-14
|
||
Audience: Product and engineering
|
||
Related:
|
||
- `doc/plans/2026-03-14-skills-ui-product-plan.md`
|
||
- `doc/plans/2026-03-13-company-import-export-v2.md`
|
||
- `docs/companies/companies-spec.md`
|
||
|
||
## 1. Purpose
|
||
|
||
This document defines the rollout plan for adapter-wide skill support in Paperclip.
|
||
|
||
The goal is not just “show a skills tab.” The goal is:
|
||
|
||
- every adapter has a deliberate skill-sync truth model
|
||
- the UI tells the truth for that adapter
|
||
- Paperclip stores desired skill state consistently even when the adapter cannot fully reconcile it
|
||
- unsupported adapters degrade clearly and safely
|
||
|
||
## 2. Current Adapter Matrix
|
||
|
||
Paperclip currently has these adapters:
|
||
|
||
- `claude_local`
|
||
- `codex_local`
|
||
- `cursor`
|
||
- `gemini_local`
|
||
- `grok_local`
|
||
- `acpx_local`
|
||
- `opencode_local`
|
||
- `pi_local`
|
||
- `openclaw_gateway`
|
||
|
||
The current skill API supports:
|
||
|
||
- `unsupported`
|
||
- `persistent`
|
||
- `ephemeral`
|
||
|
||
Current implementation state:
|
||
|
||
- `codex_local`: implemented, `ephemeral`
|
||
- `claude_local`: implemented, `ephemeral`
|
||
- `cursor`: implemented, `persistent`
|
||
- `gemini_local`: implemented, `persistent`
|
||
- `pi_local`: implemented, `persistent`
|
||
- `opencode_local`: implemented, `persistent`, with shared Claude skills home caveats
|
||
- `acpx_local`: implemented, `ephemeral` for Claude/Codex sub-agents and `unsupported` for custom commands
|
||
- `grok_local`: implemented, `ephemeral`
|
||
- `openclaw_gateway`: not yet implemented; blocked on gateway protocol support, so `unsupported` for now
|
||
|
||
## 3. Product Principles
|
||
|
||
1. Desired skills live in Paperclip for every adapter.
|
||
2. Adapters may expose different truth models, and the UI must reflect that honestly.
|
||
3. Persistent adapters should read and reconcile actual installed state.
|
||
4. Ephemeral adapters should report effective runtime state, not pretend they own a persistent install.
|
||
5. Shared-home adapters need stronger safeguards than isolated-home adapters.
|
||
6. Gateway or cloud adapters must not fake local filesystem sync.
|
||
|
||
## 4. Adapter Classification
|
||
|
||
### 4.1 Persistent local-home adapters
|
||
|
||
These adapters have a stable local skills directory that Paperclip can read and manage.
|
||
|
||
Candidates:
|
||
|
||
- `cursor`
|
||
- `gemini_local`
|
||
- `pi_local`
|
||
- `opencode_local` with caveats
|
||
|
||
Expected UX:
|
||
|
||
- show actual installed skills
|
||
- show managed vs external skills
|
||
- support `sync`
|
||
- support stale removal
|
||
- preserve unknown external skills
|
||
|
||
### 4.2 Ephemeral mount adapters
|
||
|
||
These adapters do not have a meaningful Paperclip-owned persistent install state.
|
||
|
||
Current adapter:
|
||
|
||
- `codex_local`
|
||
- `claude_local`
|
||
- `acpx_local` when configured for Claude or Codex
|
||
- `grok_local`
|
||
|
||
Expected UX:
|
||
|
||
- show desired Paperclip skills
|
||
- show any discoverable external dirs if available
|
||
- say “mounted on next run” instead of “installed”
|
||
- do not imply a persistent adapter-owned install state
|
||
|
||
### 4.3 Unsupported / remote adapters
|
||
|
||
These adapters cannot support skill sync without new external capabilities.
|
||
|
||
Current adapter:
|
||
|
||
- `acpx_local` when configured for custom commands
|
||
- `openclaw_gateway`
|
||
|
||
Expected UX:
|
||
|
||
- company skill library still works
|
||
- agent attachment UI still works at the desired-state level
|
||
- actual adapter state is `unsupported`
|
||
- sync button is disabled or replaced with explanatory text
|
||
|
||
## 5. Per-Adapter Plan
|
||
|
||
### 5.1 Codex Local
|
||
|
||
Target mode:
|
||
|
||
- `ephemeral`
|
||
|
||
Current state:
|
||
|
||
- already implemented
|
||
|
||
Requirements to finish:
|
||
|
||
- keep runtime-mounted snapshots separate from persistent install snapshots
|
||
- ensure imported company skills can be attached and mounted without manual path work
|
||
- keep `CODEX_HOME/skills` mutation scoped to heartbeat execution, not `skills/sync`
|
||
|
||
Success criteria:
|
||
|
||
- desired skills are stored in Paperclip
|
||
- selected skills are linked into the effective `CODEX_HOME/skills` during runs
|
||
- no persistent installed/stale state is reported from `skills/sync`
|
||
|
||
### 5.2 Claude Local
|
||
|
||
Target mode:
|
||
|
||
- `ephemeral`
|
||
|
||
Current state:
|
||
|
||
- already implemented
|
||
|
||
Requirements to finish:
|
||
|
||
- polish status language in UI
|
||
- clearly distinguish “desired” from “mounted on next run”
|
||
- optionally surface configured external skill dirs if Claude exposes them
|
||
|
||
Success criteria:
|
||
|
||
- desired skills stored in Paperclip
|
||
- selected skills mounted per run
|
||
- no misleading “installed” language
|
||
|
||
### 5.3 Cursor Local
|
||
|
||
Target mode:
|
||
|
||
- `persistent`
|
||
|
||
Technical basis:
|
||
|
||
- Paperclip reconciles desired skills into `~/.cursor/skills`
|
||
|
||
Current state:
|
||
|
||
- implemented
|
||
|
||
Testing:
|
||
|
||
- unit tests for discovery
|
||
- unit tests for sync and stale removal
|
||
- verify shared auth/session setup is not disturbed
|
||
|
||
Success criteria:
|
||
|
||
- Cursor agents show real installed state
|
||
- syncing from the agent Skills tab works
|
||
|
||
### 5.4 Gemini Local
|
||
|
||
Target mode:
|
||
|
||
- `persistent`
|
||
|
||
Technical basis:
|
||
|
||
- Paperclip reconciles desired skills into `~/.gemini/skills`
|
||
|
||
Current state:
|
||
|
||
- implemented
|
||
|
||
Potential caveat:
|
||
|
||
- if Gemini treats that skills directory as shared user state, the UI should warn before removing stale managed skills
|
||
|
||
Success criteria:
|
||
|
||
- Gemini agents can reconcile desired vs actual skill state
|
||
|
||
### 5.5 Pi Local
|
||
|
||
Target mode:
|
||
|
||
- `persistent`
|
||
|
||
Technical basis:
|
||
|
||
- Paperclip reconciles desired skills into `~/.pi/agent/skills`
|
||
|
||
Current state:
|
||
|
||
- implemented
|
||
|
||
Success criteria:
|
||
|
||
- Pi agents expose actual installed skill state
|
||
- Paperclip can sync desired skills into Pi’s persistent home
|
||
|
||
### 5.6 OpenCode Local
|
||
|
||
Target mode:
|
||
|
||
- `persistent`
|
||
|
||
Special case:
|
||
|
||
- OpenCode currently injects Paperclip skills into `~/.claude/skills`
|
||
|
||
This is product-risky because:
|
||
|
||
- it shares state with Claude
|
||
- Paperclip may accidentally imply the skills belong only to OpenCode when the home is shared
|
||
|
||
Plan:
|
||
|
||
- implemented `listSkills` and `syncSkills`
|
||
- treat it as `persistent`
|
||
- explicitly label the home as shared in UI copy
|
||
- only remove stale managed Paperclip skills that are clearly marked as Paperclip-managed
|
||
|
||
Phase 2:
|
||
|
||
- investigate whether OpenCode supports its own isolated skills home
|
||
- if yes, migrate to an adapter-specific home and remove the shared-home caveat
|
||
|
||
Success criteria:
|
||
|
||
- OpenCode agents show real state
|
||
- shared-home risk is visible and bounded
|
||
|
||
### 5.7 OpenClaw Gateway
|
||
|
||
Target mode:
|
||
|
||
- `unsupported` until gateway protocol support exists
|
||
|
||
Required external work:
|
||
|
||
- gateway API to list installed/available skills
|
||
- gateway API to install/remove or otherwise reconcile skills
|
||
- gateway metadata for whether state is persistent or ephemeral
|
||
|
||
Until then:
|
||
|
||
- Paperclip stores desired skills only
|
||
- UI shows unsupported actual state
|
||
- no fake sync implementation
|
||
|
||
Future target:
|
||
|
||
- likely a fourth truth model eventually, such as remote-managed persistent state
|
||
- for now, keep the current API and treat gateway as unsupported
|
||
|
||
### 5.8 ACPX Local
|
||
|
||
Target mode:
|
||
|
||
- `ephemeral` for built-in Claude/Codex ACPX sub-agents
|
||
- `unsupported` for custom ACP commands
|
||
|
||
Success criteria:
|
||
|
||
- Claude/Codex ACPX snapshots show skills as configured for the next session
|
||
- custom command snapshots keep desired skills tracked only and do not imply runtime sync
|
||
|
||
### 5.9 Grok Local
|
||
|
||
Target mode:
|
||
|
||
- `ephemeral`
|
||
|
||
Success criteria:
|
||
|
||
- desired skills are stored in Paperclip
|
||
- selected skills are copied into the execution workspace for the next run
|
||
- no persistent installed/stale state is reported from `skills/sync`
|
||
|
||
## 6. API Plan
|
||
|
||
## 6.1 Keep the current minimal adapter API
|
||
|
||
Near-term adapter contract remains:
|
||
|
||
- `listSkills(ctx)`
|
||
- `syncSkills(ctx, desiredSkills)`
|
||
|
||
This is enough for all local adapters.
|
||
|
||
## 6.2 Optional extension points
|
||
|
||
Add only if needed after the first broad rollout:
|
||
|
||
- `skillHomeLabel`
|
||
- `sharedHome: boolean`
|
||
- `supportsExternalDiscovery: boolean`
|
||
- `supportsDestructiveSync: boolean`
|
||
|
||
These should be optional metadata additions to the snapshot, not required new adapter methods.
|
||
|
||
## 7. UI Plan
|
||
|
||
The company-level skill library can stay adapter-neutral.
|
||
|
||
The agent-level Skills tab must become adapter-aware by copy and status:
|
||
|
||
- `persistent`: installed / missing / stale / external
|
||
- `ephemeral`: mounted on next run / external / desired only
|
||
- `unsupported`: desired only, adapter cannot report actual state
|
||
|
||
Additional UI requirement for shared-home adapters:
|
||
|
||
- show a small warning that the adapter uses a shared user skills home
|
||
- avoid destructive wording unless Paperclip can prove a skill is Paperclip-managed
|
||
|
||
## 8. Rollout Phases
|
||
|
||
### Phase 1: Finish the local filesystem family
|
||
|
||
Ship:
|
||
|
||
- `cursor`
|
||
- `gemini_local`
|
||
- `pi_local`
|
||
|
||
Status:
|
||
|
||
- implemented
|
||
|
||
### Phase 2: OpenCode shared-home support
|
||
|
||
Ship:
|
||
|
||
- `opencode_local`
|
||
|
||
Status:
|
||
|
||
- implemented with shared Claude skills-home warning
|
||
|
||
### Phase 3: Gateway support decision
|
||
|
||
Decide:
|
||
|
||
- keep `openclaw_gateway` unsupported for V1
|
||
- or extend the gateway protocol for remote skill management
|
||
|
||
My recommendation:
|
||
|
||
- do not block V1 on gateway support
|
||
- keep it explicitly unsupported until the remote protocol exists
|
||
|
||
## 9. Definition Of Done
|
||
|
||
Adapter-wide skill support is ready when all are true:
|
||
|
||
1. Every adapter has an explicit truth model:
|
||
- `persistent`
|
||
- `ephemeral`
|
||
- `unsupported`
|
||
2. The UI copy matches that truth model.
|
||
3. All local persistent adapters implement:
|
||
- `listSkills`
|
||
- `syncSkills`
|
||
4. Tests cover:
|
||
- desired-state storage
|
||
- actual-state discovery
|
||
- managed vs external distinctions
|
||
- stale managed-skill cleanup where supported
|
||
5. `openclaw_gateway` is either:
|
||
- explicitly unsupported with clean UX
|
||
- or backed by a real remote skill API
|
||
|
||
## 10. Recommendation
|
||
|
||
The recommended immediate order is:
|
||
|
||
1. `cursor`
|
||
2. `gemini_local`
|
||
3. `pi_local`
|
||
4. `opencode_local`
|
||
5. defer `openclaw_gateway`
|
||
|
||
The local-adapter family now has explicit truth models. The remaining V1 boundary is `openclaw_gateway`, which should stay unsupported until the gateway protocol can report real remote skill state.
|