The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
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.mdindex 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 registryThe normative package format draft lives in:@@ -39,10 +39,11 @@ The new direction is:1. markdown-first package authoring2. 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 time6. 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 GraphImport 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 attachmentsSuggested future tables:- package_installs- package_install_entities- package_sources+- agent_skill_desires+- adapter_skill_snapshotsThis 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 Questions1. 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 draft2. implement phase 1 stabilization work3. 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 surfaceThis keeps Paperclip aligned with:diff --git a/docs/companies/companies-spec.md b/docs/companies/companies-spec.mdindex 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. PurposeA 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 specificationA 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