Refine company package spec and rollout plan

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
+3. the company package model is explicitly an extension of Agent Skills
-4. optional generated lock/cache artifacts, not required manifests
+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
+- markdown-first repo layout is the target
-- JSON manifests become optional generated artifacts at most
+- no new work should deepen investment in the old manifest model
-- future portability work should target the markdown-first model first
+- 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
+- team -> imported agent subtree attachment plus package provenance grouping
-- skill -> referenced package metadata only
+- 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:
+   Decision: managed package files should support both company-scoped reuse and agent-scoped attachment.
-   - team
+2. What is the minimum adapter skill interface needed to make the UI useful across Claude Code, Codex, OpenClaw, and future adapters?
-   - or skill
+   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:
 

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
+`paperclip.manifest.json` does not need to be preserved as a compatibility requirement for the future package system.
-- current company portability import/export
 
-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