Skip to content

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

Add company packages spec draft

Dottadbb5bd48cc2b
diff --git a/docs/companies/companies-spec.md b/docs/companies/companies-spec.md
new file mode 100644
index 0000000000..1b4578fe32
--- /dev/null
+++ b/docs/companies/companies-spec.md
@@ -0,0 +1,412 @@
+# Company Packages 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.
+
+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
+- be useful outside Paperclip
+
+## 2. Core Principles
+
+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.
+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.
+
+## 3. Package Kinds
+
+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
+
+A GitHub repo may contain one package at root or many packages in subdirectories.
+
+## 4. Reserved Files And Directories
+
+Common conventions:
+
+```text
+COMPANY.md
+TEAM.md
+AGENTS.md
+SKILL.md
+
+agents/<slug>/AGENTS.md
+teams/<slug>/TEAM.md
+skills/<slug>/SKILL.md
+
+HEARTBEAT.md
+SOUL.md
+TOOLS.md
+README.md
+assets/
+scripts/
+references/
+```
+
+Rules:
+- only markdown files are canonical content docs
+- non-markdown directories like `assets/`, `scripts/`, and `references/` are allowed
+- package tools may generate optional lock files, but lock files are not required for authoring
+
+## 5. Common Frontmatter
+
+All package root docs should support these fields:
+
+```yaml
+schema: company-packages/v0.1
+kind: company | team | agent
+slug: my-slug
+name: Human Readable Name
+description: Short description
+version: 0.1.0
+license: MIT
+authors:
+ - name: Jane Doe
+homepage: https://example.com
+tags:
+ - startup
+ - engineering
+metadata: {}
+sources: []
+```
+
+Notes:
+- `schema` is required for `COMPANY.md`, `TEAM.md`, and `AGENTS.md`
+- `kind` is required
+- `slug` should be URL-safe and stable
+- `sources` is for provenance and external references
+- `metadata` is for tool-specific extensions
+
+## 6. COMPANY.md
+
+`COMPANY.md` is the root entrypoint for a whole company package.
+
+### Required fields
+
+```yaml
+schema: company-packages/v0.1
+kind: company
+slug: lean-dev-shop
+name: Lean Dev Shop
+description: Small engineering-focused AI company
+```
+
+### Recommended fields
+
+```yaml
+version: 1.0.0
+license: MIT
+authors:
+ - name: Example Org
+brandColor: "#22c55e"
+goals:
+ - Build and ship software products
+defaults:
+ requireBoardApprovalForNewAgents: true
+includes:
+ - path: agents/ceo/AGENTS.md
+ - path: teams/engineering/TEAM.md
+ - path: skills/review/SKILL.md
+requirements:
+ secrets:
+ - OPENAI_API_KEY
+```
+
+### Semantics
+
+- `includes` defines the package graph
+- included items may be local or external references
+- `COMPANY.md` may include agents directly, teams, or skills
+- a company importer may render `includes` as the tree/checkbox import UI
+
+## 7. TEAM.md
+
+`TEAM.md` defines an org subtree.
+
+### Example
+
+```yaml
+schema: company-packages/v0.1
+kind: team
+slug: engineering
+name: Engineering
+description: Product and platform engineering team
+manager:
+ path: ../cto/AGENTS.md
+includes:
+ - path: ../platform-lead/AGENTS.md
+ - path: ../frontend-lead/AGENTS.md
+ - path: ../../skills/review/SKILL.md
+tags:
+ - team
+ - engineering
+```
+
+### Semantics
+
+- a team package is a reusable subtree, not necessarily a runtime database table
+- `manager` identifies the root agent of the subtree
+- `includes` may contain child agents, child teams, or shared skills
+- a team package can be imported into an existing company and attached under a target manager
+
+## 8. AGENTS.md
+
+`AGENTS.md` defines an agent.
+
+### Example
+
+```yaml
+schema: company-packages/v0.1
+kind: agent
+slug: ceo
+name: CEO
+role: ceo
+title: Chief Executive Officer
+description: Sets strategy and manages executives
+icon: crown
+capabilities:
+ - strategy
+ - delegation
+reportsTo: null
+adapter:
+ type: codex_local
+ config:
+ model: gpt-5
+runtime:
+ heartbeat:
+ intervalSec: 3600
+permissions:
+ canCreateAgents: true
+skills:
+ - path: ../../skills/plan-ceo-review/SKILL.md
+docs:
+ instructions: AGENTS.md
+ heartbeat: HEARTBEAT.md
+ soul: SOUL.md
+requirements:
+ secrets:
+ - OPENAI_API_KEY
+metadata: {}
+```
+
+### Semantics
+
+- body content is the canonical default instruction content for the agent
+- `docs` points to sibling markdown docs when present
+- `skills` references reusable `SKILL.md` packages
+- `adapter.config` and `runtime` should contain only portable values
+- local absolute paths, machine-specific cwd values, and secret values must not be exported as canonical package data
+
+## 9. SKILL.md Compatibility
+
+A skill package must remain a valid Agent Skills package.
+
+Rules:
+- `SKILL.md` should follow the Agent Skills spec
+- Paperclip must not require extra top-level fields for skill validity
+- 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
+
+### Example compatible extension
+
+```yaml
+---
+name: review
+description: Paranoid code review skill
+allowed-tools:
+ - Read
+ - Grep
+metadata:
+ paperclip:
+ tags:
+ - engineering
+ - review
+ sources:
+ - kind: github-file
+ repo: vercel-labs/skills
+ path: review/SKILL.md
+ commit: 0123456789abcdef0123456789abcdef01234567
+ sha256: 3b7e...9a
+ attribution: Vercel Labs
+ usage: referenced
+---
+```
+
+## 10. Source References
+
+A package may point to upstream content instead of vendoring it.
+
+### Source object
+
+```yaml
+sources:
+ - kind: github-file
+ repo: owner/repo
+ path: path/to/file.md
+ commit: 0123456789abcdef0123456789abcdef01234567
+ blob: abcdef0123456789abcdef0123456789abcdef01
+ sha256: 3b7e...9a
+ url: https://github.com/owner/repo/blob/0123456789abcdef0123456789abcdef01234567/path/to/file.md
+ rawUrl: https://raw.githubusercontent.com/owner/repo/0123456789abcdef0123456789abcdef01234567/path/to/file.md
+ attribution: Owner Name
+ license: MIT
+ usage: referenced
+```
+
+### Supported kinds
+
+- `local-file`
+- `local-dir`
+- `github-file`
+- `github-dir`
+- `url`
+
+### Usage modes
+
+- `vendored`: bytes are included in the package
+- `referenced`: package points to upstream immutable content
+- `mirrored`: bytes are cached locally but upstream attribution remains canonical
+
+### Rules
+
+- `commit` is required for `github-file` and `github-dir` in strict mode
+- `sha256` is strongly recommended and should be verified on fetch
+- branch-only refs may be allowed in development mode but must warn
+- exporters should default to `referenced` for third-party content unless redistribution is clearly allowed
+
+## 11. Resolution Rules
+
+Given a package root, an importer resolves in this order:
+
+1. local relative paths
+2. local absolute paths if explicitly allowed by the importing tool
+3. pinned GitHub refs
+4. generic URLs
+
+For pinned GitHub refs:
+1. resolve `repo + commit + path`
+2. fetch content
+3. verify `sha256` if present
+4. verify `blob` if present
+5. fail closed on mismatch
+
+An importer must surface:
+- missing files
+- hash mismatches
+- missing licenses
+- referenced upstream content that requires network fetch
+- executable content in skills or scripts
+
+## 12. Import Graph
+
+A package importer should build a graph from:
+- `COMPANY.md`
+- `TEAM.md`
+- `AGENTS.md`
+- `SKILL.md`
+- local and external refs
+
+Suggested import UI behavior:
+- render graph as a tree
+- checkbox at entity level, not raw file level
+- selecting an agent auto-selects required docs and referenced skills
+- selecting a team auto-selects its subtree
+- selecting referenced third-party content shows attribution, license, and fetch policy
+
+## 13. Export Rules
+
+A compliant exporter should:
+- emit markdown roots and relative folder layout
+- omit machine-local ids and timestamps
+- omit secret values
+- omit machine-specific paths
+- preserve attribution and source references
+- prefer `referenced` over silent vendoring for third-party content
+- preserve `SKILL.md` as-is when exporting compatible skills
+
+## 14. Licensing And Attribution
+
+A compliant tool must:
+- preserve `license` and `attribution` metadata when importing and exporting
+- distinguish vendored vs referenced content
+- not silently inline referenced third-party content during export
+- surface missing license metadata as a warning
+- surface restrictive or unknown licenses before install/import if content is vendored or mirrored
+
+## 15. Optional Lock File
+
+Authoring does not require a lock file.
+
+Tools may generate an optional lock file such as:
+
+```text
+company-package.lock.json
+```
+
+Purpose:
+- cache resolved refs
+- record final hashes
+- support reproducible installs
+
+Rules:
+- lock files are optional
+- lock files are generated artifacts, not canonical authoring input
+- the markdown package remains the source of truth
+
+## 16. Paperclip Mapping
+
+Paperclip can map this spec to its runtime model like this:
+
+- `COMPANY.md` -> company metadata
+- `TEAM.md` -> importable org subtree
+- `AGENTS.md` -> agent records plus adapter/runtime config
+- `SKILL.md` -> imported skill package, ideally as a managed reusable skill reference
+- `sources[]` -> provenance and pinned upstream refs
+
+Paperclip-specific data should live under:
+- `metadata.paperclip`
+
+That keeps the base format broader than Paperclip.
+
+## 17. Backward Compatibility
+
+Paperclip may continue to support:
+- existing `paperclip.manifest.json` packages
+- current company portability import/export
+
+But the markdown-first repo layout should become the preferred authoring format.
+
+## 18. Minimal Example
+
+```text
+lean-dev-shop/
+├── COMPANY.md
+├── agents/
+│ ├── ceo/AGENTS.md
+│ └── cto/AGENTS.md
+├── teams/
+│ └── engineering/TEAM.md
+└── skills/
+ └── review/SKILL.md
+```
+
+**Recommendation**
+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
+- make `companies.sh` a discovery layer for repos implementing this spec, not a publishing authority