From 2975aa950b8a0affefc5eb592ea59219b368fb09 Mon Sep 17 00:00:00 2001 From: Dotta Date: Fri, 13 Mar 2026 21:36:19 -0500 Subject: [PATCH] Refine company package spec and rollout plan --- .../2026-03-13-company-import-export-v2.md | 98 ++++++++++++++++--- docs/companies/companies-spec.md | 25 +++-- 2 files changed, 98 insertions(+), 25 deletions(-) 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 9bbf7585..4d00a743 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 0b4e1000..f7ea4802 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