The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
Add company packages spec draft
Dottadbb5bd48cc2b
diff --git a/docs/companies/companies-spec.md b/docs/companies/companies-spec.mdnew file mode 100644index 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