Skip to content

The open-source app everyone uses to manage agents at work

Refine company package spec and rollout plan

Dotta2975aa950b8a
diff --git a/doc/plans/2026-03-13-company-import-export-v2.md b/doc/plans/2026-03-13-company-import-export-v2.md
index 9bbf75858a..4d00a743f5 100644
--- a/doc/plans/2026-03-13-company-import-export-v2.md
+++ b/doc/plans/2026-03-13-company-import-export-v2.md
@@ -15,7 +15,7 @@ The core shift is:
- move from a Paperclip-specific JSON-first portability package toward a markdown-first package format
- make GitHub repositories first-class package sources
-- stay compatible with the existing Agent Skills ecosystem instead of inventing a separate skill format
+- treat the company package model as an extension of the existing Agent Skills ecosystem instead of inventing a separate skill format
- support company, team, agent, and skill reuse without requiring a central registry
The normative package format draft lives in:
@@ -39,10 +39,11 @@ The new direction is:
1. markdown-first package authoring
2. GitHub repo or local folder as the default source of truth
-3. `SKILL.md` compatibility as a hard constraint
-4. optional generated lock/cache artifacts, not required manifests
+3. the company package model is explicitly an extension of Agent Skills
+4. no future dependency on `paperclip.manifest.json`
5. package graph resolution at import time
6. entity-level import UI with dependency-aware tree selection
+7. adapter-aware skill sync surfaces so Paperclip can read, diff, enable, disable, and reconcile skills where the adapter supports it
## 3. Product Goals
@@ -119,18 +120,19 @@ Paperclip must not redefine `SKILL.md`.
Rules:
- `SKILL.md` stays Agent Skills compatible
+- the company package model is an extension of Agent Skills
- Paperclip-specific extensions live under metadata
- Paperclip may resolve and install `SKILL.md` packages, but it must not require a Paperclip-only skill format
### 5.3 Relationship To Current V1 Manifest
-The current `paperclip.manifest.json` format stays supported as a compatibility format during transition.
+`paperclip.manifest.json` is not part of the future package direction.
-But:
+This should be treated as a hard cutover in product direction.
-- markdown-first repo layout becomes the preferred export target
-- JSON manifests become optional generated artifacts at most
-- future portability work should target the markdown-first model first
+- markdown-first repo layout is the target
+- no new work should deepen investment in the old manifest model
+- future portability APIs and UI should target the markdown-first model only
## 6. Package Graph Model
@@ -161,6 +163,13 @@ In Paperclip V2 portability:
This avoids blocking portability on a future runtime `teams` model.
+Imported-team tracking should initially be package/provenance-based:
+
+- if a team package was imported, the imported agents should carry enough provenance to reconstruct that grouping
+- Paperclip can treat “this set of agents came from team package X” as the imported-team model
+- provenance grouping is the intended near- and medium-term team model for import/export
+- only add a first-class runtime `teams` table later if product needs move beyond what provenance grouping can express
+
### 6.3 Dependency Graph
Import should operate on an entity graph, not raw file selection.
@@ -267,6 +276,48 @@ Every import preview should surface:
- unsupported content types
- trust/licensing warnings
+### 8.5 Adapter Skill Sync Surface
+
+People want skill management in the UI, but skills are adapter-dependent.
+
+That means portability and UI planning must include an adapter capability model for skills.
+
+Paperclip should define a new adapter surface area around skills:
+
+- list currently enabled skills for an agent
+- report how those skills are represented by the adapter
+- install or enable a skill
+- disable or remove a skill
+- report sync state between desired package config and actual adapter state
+
+Examples:
+
+- Claude Code / Codex style adapters may manage skills as local filesystem packages or adapter-owned skill directories
+- OpenClaw-style adapters may expose currently enabled skills through an API or a reflected config surface
+- some adapters may be read-only and only report what they have
+
+Planned adapter capability shape:
+
+- `supportsSkillRead`
+- `supportsSkillWrite`
+- `supportsSkillRemove`
+- `supportsSkillSync`
+- `skillStorageKind` such as `filesystem`, `remote_api`, `inline_config`, or `unknown`
+
+Baseline adapter interface:
+
+- `listSkills(agent)`
+- `applySkills(agent, desiredSkills)`
+- `removeSkill(agent, skillId)` optional
+- `getSkillSyncState(agent, desiredSkills)` optional
+
+Planned Paperclip behavior:
+
+- if an adapter supports read, Paperclip should show current skills in the UI
+- if an adapter supports write, Paperclip should let the user enable/disable imported skills
+- if an adapter supports sync, Paperclip should compute desired vs actual state and offer reconcile actions
+- if an adapter does not support these capabilities, the UI should still show the package-level desired skills but mark them unmanaged
+
## 9. Export Behavior
### 9.1 Default Export Target
@@ -315,8 +366,8 @@ In the first phase, imported entities can continue mapping onto current runtime
- company -> companies
- agent -> agents
-- team -> imported agent subtree attachment
-- skill -> referenced package metadata only
+- team -> imported agent subtree attachment plus package provenance grouping
+- skill -> company-scoped reusable package metadata plus agent-scoped desired-skill attachment state where supported
### 10.2 Medium-Term
@@ -328,12 +379,17 @@ Needed capabilities:
- support re-import / upgrade
- distinguish local edits from upstream package state
- preserve external refs and package-level metadata
+- preserve imported team grouping without requiring a runtime `teams` table immediately
+- preserve desired-skill state separately from adapter runtime state
+- support both company-scoped reusable skills and agent-scoped skill attachments
Suggested future tables:
- package_installs
- package_install_entities
- package_sources
+- agent_skill_desires
+- adapter_skill_snapshots
This is not required for phase 1 UI, but it is required for a robust long-term system.
@@ -387,6 +443,7 @@ Planned additions:
- `--strict-pins`
- `--allow-unpinned`
- `--materialize-references`
+- `--sync-skills`
## 13. UI Plan
@@ -422,6 +479,7 @@ If importing a team into an existing company:
- show the subtree structure
- require the user to choose where to attach it
- preview manager/reporting updates before apply
+- preserve imported-team provenance so the UI can later say “these agents came from team package X”
### 13.3 Skills UX
@@ -430,6 +488,9 @@ If importing skills:
- show whether each skill is local, vendored, or referenced
- show whether it contains scripts/assets
- preserve Agent Skills compatibility in presentation and export
+- show current adapter-reported skills when supported
+- show desired package skills separately from actual adapter state
+- offer reconcile actions when the adapter supports sync
## 14. Rollout Phases
@@ -438,7 +499,7 @@ If importing skills:
- add tests for current portability flows
- replace the frontmatter parser
- add Company Settings UI for current import/export capabilities
-- preserve current manifest compatibility
+- start cutover work toward the markdown-first package reader
### Phase 2: Markdown-First Package Reader
@@ -446,23 +507,25 @@ If importing skills:
- build internal graph from markdown-first packages
- support local folder and GitHub repo inputs natively
-### Phase 3: Graph-Based Import UX
+### Phase 3: Graph-Based Import UX And Skill Surfaces
- entity tree preview
- checkbox selection
- team subtree attach flow
- licensing/trust/reference warnings
+- adapter skill read/sync UI groundwork
### Phase 4: New Export Model
- export markdown-first folder structure by default
-- continue optional legacy manifest export for compatibility
### Phase 5: Provenance And Upgrades
- persist install provenance
- support package-aware re-import and upgrades
- improve collision matching beyond slug-only
+- add imported-team provenance grouping
+- add desired-vs-actual skill sync state
### Phase 6: Optional Seed Content
@@ -489,14 +552,16 @@ Docs to update later as implementation lands:
## 16. Open Questions
1. Should imported skill packages be stored as managed package files in Paperclip storage, or only referenced at import time?
-2. Should the first generalized package import after company+agent be:
- - team
- - or skill
+ Decision: managed package files should support both company-scoped reuse and agent-scoped attachment.
+2. What is the minimum adapter skill interface needed to make the UI useful across Claude Code, Codex, OpenClaw, and future adapters?
+ Decision: use the baseline interface in section 8.5.
3. Should Paperclip support direct local folder selection in the web UI, or keep that CLI-only initially?
4. Do we want optional generated lock files in phase 2, or defer them until provenance work?
5. How strict should pinning be by default for GitHub references:
- warn on unpinned
- or block in normal mode
+6. Is package-provenance grouping enough for imported teams, or do we expect product requirements soon that would justify a first-class runtime `teams` table?
+ Decision: provenance grouping is enough for the import/export product model for now.
## 17. Recommendation
@@ -507,6 +572,7 @@ Immediate next steps:
1. accept `docs/companies/companies-spec.md` as the package-format draft
2. implement phase 1 stabilization work
3. build phase 2 markdown-first package reader before expanding ClipHub or `companies.sh`
+4. treat the old manifest-based format as deprecated and not part of the future surface
This keeps Paperclip aligned with:
diff --git a/docs/companies/companies-spec.md b/docs/companies/companies-spec.md
index 0b4e1000da..f7ea480217 100644
--- a/docs/companies/companies-spec.md
+++ b/docs/companies/companies-spec.md
@@ -1,18 +1,24 @@
# Company Packages Specification
+Extension of the Agent Skills Specification
+
Version: `0.1-draft`
## 1. Purpose
A Company Package is a filesystem- and GitHub-native format for describing a company, team, agent, and associated skills using markdown files with YAML frontmatter.
+This specification is an extension of the Agent Skills specification, not a replacement for it.
+
+It defines how company-, team-, and agent-level package structure composes around the existing `SKILL.md` model.
+
The format is designed to:
- be readable and writable by humans
- work directly from a local folder or GitHub repository
- require no central registry
- support attribution and pinned references to upstream files
-- be compatible with the existing Agent Skills ecosystem
+- extend the existing Agent Skills ecosystem without redefining it
- be useful outside Paperclip
## 2. Core Principles
@@ -20,7 +26,7 @@ The format is designed to:
1. Markdown is canonical.
2. Git repositories are valid package containers.
3. Registries are optional discovery layers, not authorities.
-4. `SKILL.md` remains Agent Skills compatible.
+4. `SKILL.md` remains owned by the Agent Skills specification.
5. External references must be pinnable to immutable Git commits.
6. Attribution and license metadata must survive import/export.
7. Slugs and relative paths are the portable identity layer, not database ids.
@@ -32,7 +38,7 @@ A package root is identified by one primary markdown file:
- `COMPANY.md` for a company package
- `TEAM.md` for a team package
- `AGENTS.md` for an agent package
-- `SKILL.md` for a skill package
+- `SKILL.md` for a skill package defined by the Agent Skills specification
A GitHub repo may contain one package at root or many packages in subdirectories.
@@ -226,6 +232,8 @@ Rules:
- Paperclip-specific extensions must live under `metadata.paperclip` or `metadata.sources`
- a skill directory may include `scripts/`, `references/`, and `assets/` exactly as the Agent Skills ecosystem expects
+In other words, this spec extends Agent Skills upward into company/team/agent composition. It does not redefine skill package semantics.
+
### Example compatible extension
```yaml
@@ -396,14 +404,13 @@ Paperclip-specific data should live under:
That keeps the base format broader than Paperclip.
-## 17. Backward Compatibility
+## 17. Cutover
-Paperclip may continue to support:
+Paperclip should cut over to this markdown-first package model as the primary portability format.
-- existing `paperclip.manifest.json` packages
-- current company portability import/export
+`paperclip.manifest.json` does not need to be preserved as a compatibility requirement for the future package system.
-But the markdown-first repo layout should become the preferred authoring format.
+For Paperclip, this should be treated as a hard cutover in product direction rather than a long-lived dual-format strategy.
## 18. Minimal Example
@@ -423,6 +430,6 @@ lean-dev-shop/
This is the direction I would take:
- make this the human-facing spec
-- keep JSON manifests only as optional generated lock/cache artifacts
- define `SKILL.md` compatibility as non-negotiable
+- treat this spec as an extension of Agent Skills, not a parallel format
- make `companies.sh` a discovery layer for repos implementing this spec, not a publishing authority