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
updated spec
Dotta3f48b61bfab4
diff --git a/docs/companies/companies-spec.md b/docs/companies/companies-spec.mdindex 1b4578fe32..0b4e1000da 100644--- a/docs/companies/companies-spec.md+++ b/docs/companies/companies-spec.md@@ -1,4 +1,5 @@# Company Packages Specification+Version: `0.1-draft`## 1. Purpose@@ -6,6 +7,7 @@ Version: `0.1-draft`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@@ -58,6 +60,7 @@ 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@@ -85,6 +88,7 @@ sources: []```Notes:+- `schema` is required for `COMPANY.md`, `TEAM.md`, and `AGENTS.md`- `kind` is required- `slug` should be URL-safe and stable@@ -216,6 +220,7 @@ metadata: {}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`@@ -298,6 +303,7 @@ Given a package root, an importer resolves in this order:4. generic URLsFor pinned GitHub refs:+1. resolve `repo + commit + path`2. fetch content3. verify `sha256` if present@@ -305,6 +311,7 @@ For pinned GitHub refs:5. fail closed on mismatchAn importer must surface:+- missing files- hash mismatches- missing licenses@@ -314,6 +321,7 @@ An importer must surface:## 12. Import GraphA package importer should build a graph from:+- `COMPANY.md`- `TEAM.md`- `AGENTS.md`@@ -321,6 +329,7 @@ A package importer should build a graph from:- local and external refsSuggested 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@@ -330,6 +339,7 @@ Suggested import UI behavior:## 13. Export RulesA compliant exporter should:+- emit markdown roots and relative folder layout- omit machine-local ids and timestamps- omit secret values@@ -341,6 +351,7 @@ A compliant exporter should:## 14. Licensing And AttributionA 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@@ -358,11 +369,13 @@ company-package.lock.json```Purpose:+- cache resolved refs- record final hashes- support reproducible installsRules:+- lock files are optional- lock files are generated artifacts, not canonical authoring input- the markdown package remains the source of truth@@ -378,6 +391,7 @@ Paperclip can map this spec to its runtime model like this:- `sources[]` -> provenance and pinned upstream refsPaperclip-specific data should live under:+- `metadata.paperclip`That keeps the base format broader than Paperclip.@@ -385,6 +399,7 @@ That keeps the base format broader than Paperclip.## 17. Backward CompatibilityPaperclip may continue to support:+- existing `paperclip.manifest.json` packages- current company portability import/export@@ -406,6 +421,7 @@ lean-dev-shop/**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