AIP-6: COMPANY.md — agentcompanies/v1 (company, role & objective primitives)
A filesystem-first, vendor-neutral file format for representing AI companies — their org structure, roles, and objectives — as portable git-native packages.
| Field | Value |
|---|---|
| AIP | 6 |
| Title | COMPANY.md — agentcompanies/v1 (company, role & objective primitives) |
| Status | Final |
| Type | Core |
| Domain | companies.sh |
| Spec author | Paperclip team (paperclipai/paperclip) |
| AIP editor | Jeremy André |
| Reference Impl | COMPANY.md doctype spec |
Abstract
agentcompanies/v1 is an open file-format standard for representing the
structural primitives of an AI company — the company itself, its roles,
its objectives, its operators — as a set of markdown-with-frontmatter and
JSON files in a filesystem-first, vendor-neutral package. Any git
repository conforming to the layout is a valid company package. AIP-6
mirrors the upstream spec maintained at
paperclipai/paperclip and
anchors it inside the AIP registry so dependent specs (AIP-7, AIP-8) can
reference it by AIP number.
Motivation
AI-company products today represent org structure in vendor-specific databases. That makes:
- Portability impossible: moving a company between vendors requires re-authoring it.
- Audit opaque: there is no diffable, version-controlled artifact.
- Composition ad-hoc: governance specs (AIP-7) and operational specs (AIP-8) have no shared substrate to extend.
agentcompanies/v1 fixes this by making the company a folder of files. Git is the version control. The filesystem is the database. Adapters project these files into vendor-specific databases when needed.
Specification
AIP-6 mirrors the canonical specification maintained upstream at paperclipai/paperclip. The normative text will be vendored into this AIP as part of moving Draft → Review, with editorial divergences (if any) called out explicitly.
Doctype shape (sketch):
| Doctype | Path | Purpose |
|---|---|---|
company | COMPANY.md | Root file: identity, mission, structure |
role | roles/<slug>/ROLE.md | A role within the company |
objective | objectives/<slug>/OBJECTIVE.md | An objective the company pursues |
operator | operators/<slug>/OPERATOR.md | A specific AI operator (instance of a role). AIP-9 runtime; extends AIP-42 AGENT.md with role + reports_to + company binding. |
agent | agents/<slug>/AGENT.md | A standalone agent (utility, helper, sub-agent) — AIP-42. NOT bound to a company role; useful for utilities (researcher, code-reviewer, formatter) the company employs without giving them an org-chart slot. |
structure.positions (formerly structure.roles)
The company manifest's structure block enumerates the org chart:
structure.positions— slugs of the company's seats, each typically materialized as an operator (operators/<slug>/OPERATOR.md). A position is a seat exactly one operator holds; several positions MAY share one AIP-47 catalog role (e.g. an SDR seat and an AE seat both fulfillingsales-rep). See AIP-47 §Role vs Position vs Access role.structure.reports_to— map of position-slug → position-slug expressing the reporting tree.structure.roles— DEPRECATED alias ofpositions. Historically documented as role slugs but used in practice for seats. Readers MUST accept both; when both are present,positionswins. Writers SHOULD emitpositions.
Common conventions adopted by all agentcompanies/v1 files:
- Markdown canonical with YAML frontmatter
schema: agentcompanies/v1field on every doctype- Slug-based references, never database IDs
- Vendor-specific extensions under
metadata.<vendor>.* - Git-native: any repository hosting these files is a valid company
Rationale
To be authored. Defend: filesystem-first over DB-first, slug references over UUIDs, markdown over pure JSON for human-authorable doctypes, vendor-extensions namespace.
Reference Implementation
Upstream at paperclipai/paperclip — the spec, parsers, validators. Inside the agentik ecosystem, the agentik-studio monorepo consumes companies via adapters; concrete usage emerges through AIP-8 (agencies engine).
Backwards Compatibility
Not applicable — first AIP-numbered version. If the upstream spec revs to v2, AIP-6 stays at v1 and a new AIP supersedes it.
Security Considerations
The spec is a file format with no execution semantics, but the contents of a company package describe agent permissions, roles, and access. A malicious company package fed to a credulous runtime could grant inappropriate permissions. Mitigations are runtime-side: signatures (via AIP-7), provenance metadata, and human approval gates before ingesting external companies.
Resources
Supporting artifacts for AIP-6. Links open the file on GitHub — markdown and JSON render natively in GitHub's viewer. Browse the full resource tree →
AIP-5: CANVAKIT.md — template + data-source binding
A markdown + frontmatter format for templates that declare named data sources, resolve them in parallel, and re-render when data changes.
AIP-7: GOVERNANCE.md — agentgovernance/v1 (audit, approval & policy primitives)
A filesystem-first format for recording approvals, append-only audit logs, and autonomy policies as workspace files — vendor-neutral, third-party-verifiable.