doc/plans/2026-03-13-company-import-export-v2.md
Status: Proposed implementation plan Date: 2026-03-13 Audience: Product and engineering Supersedes for package-format direction:
doc/plans/2026-02-16-module-system.md sections that describe company templates as JSON-onlydocs/specs/cliphub-plan.md assumptions about blueprint bundle shape where they conflict with the markdown-first package modelThis document defines the next-stage plan for Paperclip company import/export.
The core shift is:
The normative package format draft lives in:
docs/companies/companies-spec.mdThis plan is about implementation and rollout inside Paperclip.
Adapter-wide skill rollout details live in:
doc/plans/2026-03-14-adapter-skill-sync-rollout.mdPaperclip already has portability primitives in the repo:
Those primitives are being cut over to the new package model rather than extended for backward compatibility.
The new direction is:
paperclip.manifest.json.paperclip.yaml sidecar for high-fidelity Paperclip-specific detailsskills.sh compatibility is a V1 requirement for skill packages and skill installation flowsskills.sh / Agent Skills ecosystem.companies.sh can later act as a discovery/index layer over repos implementing this format.teams table before team portability ships.Current implementation exists here:
packages/shared/src/types/company-portability.tspackages/shared/src/validators/company-portability.tsserver/src/routes/companies.tsserver/src/services/company-portability.tscli/src/commands/client/company.tsCurrent product limitations:
The canonical authoring format becomes a markdown-first package rooted in one of:
COMPANY.mdTEAM.mdAGENTS.mdPROJECT.mdTASK.mdSKILL.mdThe normative draft is:
docs/companies/companies-spec.mdPaperclip must not redefine SKILL.md.
Rules:
SKILL.md stays Agent Skills compatible.paperclip.yamlSKILL.md packages, but it must not require a Paperclip-only skill formatskills.sh compatibility is a V1 requirement, not a future nice-to-haveAGENTS.md should associate skills by skill shortname or slug, not by verbose path in the common case.
Preferred example:
skills: [review, react-best-practices]Resolution model:
review resolves to skills/review/SKILL.md by package conventionAGENTS.mdThe repo format should have two layers:
.paperclip.yamlpaperclip.manifest.json is not part of the future package direction.
This should be treated as a hard cutover in product direction.
Paperclip import/export should support these entity kinds:
team is a package concept first, not a database-table requirement.
In Paperclip V2 portability:
This avoids blocking portability on a future runtime teams model.
Imported-team tracking should initially be package/provenance-based:
teams table later if product needs move beyond what provenance grouping can expressImport should operate on an entity graph, not raw file selection.
Examples:
The preview output should reflect graph resolution explicitly.
Some packages will:
Paperclip should support source references in package metadata with:
Usage modes:
vendoredreferencedmirroredDefault exporter behavior for third-party content should be:
referencedImported package content should be classified by trust level:
The UI and CLI should surface this clearly before apply.
Registry-based discovery may be added later, but must remain optional.
For existing company imports, the preview must support:
Current rename | skip | replace support remains, but matching should improve over time.
Preferred matching order:
Slug-only matching is acceptable only as a transitional strategy.
Every import preview should 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:
Examples:
Planned adapter capability shape:
supportsSkillReadsupportsSkillWritesupportsSkillRemovesupportsSkillSyncskillStorageKind such as filesystem, remote_api, inline_config, or unknownBaseline adapter interface:
listSkills(agent)applySkills(agent, desiredSkills)removeSkill(agent, skillId) optionalgetSkillSyncState(agent, desiredSkills) optionalPlanned Paperclip behavior:
Default export target should become a markdown-first folder structure.
Example:
my-company/
├── COMPANY.md
├── agents/
├── teams/
└── skills/
Exports should:
.paperclip.yaml when AGENTS.md already carries the instructions.paperclip.yaml alongside the base packageSKILL.md content as-isProjects and issues should not be exported by default.
They should be opt-in through selectors such as:
--projects project-shortname-1,project-shortname-2--issues PAP-1,PAP-3--project-issues project-shortname-1,project-shortname-2This supports “clean public company package” workflows where a maintainer exports a follower-facing company package without bundling active work items every time.
Initial export units:
Later optional units:
In the first phase, imported entities can continue mapping onto current runtime tables:
Paperclip should add managed package/provenance records so imports are not anonymous one-off copies.
Needed capabilities:
teams table immediatelySuggested future tables:
This is not required for phase 1 UI, but it is required for a robust long-term system.
Retain:
POST /api/companies/:companyId/exportPOST /api/companies/import/previewPOST /api/companies/importBut evolve payloads toward the markdown-first graph model.
Add support for:
Replace the current ad hoc markdown frontmatter parser with a real parser that can handle:
This is a prerequisite for the new package model.
The CLI should continue to support direct import/export without a registry.
Target commands:
paperclipai company export <company-id> --out <path>paperclipai company import <path-or-url> --dry-runpaperclipai company import <path-or-url> --target existing -C <company-id>Planned additions:
--package-kind company|team|agent--attach-under <agent-id-or-slug> for team imports--strict-pins--allow-unpinned--materialize-references--sync-skillsAdd a real import/export section to Company Settings.
Export UI:
Import UI:
If importing a team into an existing company:
See also:
doc/plans/2026-03-14-skills-ui-product-plan.mdIf importing skills:
skills.sh compatibility in both import and install flowsCOMPANY.md / TEAM.md / AGENTS.md root detectionskills/<slug>/SKILL.md packages by conventionskills.sh-compatible skill repos as V1 package sourcesSkills tab groundworkThis phase is intentionally after the structural model is stable.
Primary docs:
docs/companies/companies-spec.md as the package-format draftDocs to update later as implementation lands:
doc/SPEC-implementation.mddocs/api/companies.mddocs/cli/control-plane-commands.mdteams table?
Decision: provenance grouping is enough for the import/export product model for now.Engineering should treat this as the current plan of record for company import/export beyond the existing V1 portability feature.
Immediate next steps:
docs/companies/companies-spec.md as the package-format draftcompanies.shThis keeps Paperclip aligned with: