From dbb5bd48cc2b792c6c4d902a7face25b51a50795 Mon Sep 17 00:00:00 2001 From: Dotta Date: Fri, 13 Mar 2026 20:53:22 -0500 Subject: [PATCH] Add company packages spec draft --- docs/companies/companies-spec.md | 412 +++++++++++++++++++++++++++++++ 1 file changed, 412 insertions(+) create mode 100644 docs/companies/companies-spec.md diff --git a/docs/companies/companies-spec.md b/docs/companies/companies-spec.md new file mode 100644 index 00000000..1b4578fe --- /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//AGENTS.md +teams//TEAM.md +skills//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