Add company packages spec draft
This commit is contained in:
Dotta
parent
bcce5b7ec2
commit
dbb5bd48cc
1 changed files with 412 additions and 0 deletions
412
docs/companies/companies-spec.md
Normal file
412
docs/companies/companies-spec.md
Normal file
|
|
@ -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
|
||||||
Loading…
Add table
Reference in a new issue