AIP-6: COMPANY (company/v1): the static company profile
A filesystem-first, vendor-neutral file format for the static profile of an AI company (identity, mission, values, objectives) as a portable git-native package. Roles are AIP-47, seats and reporting lines are the AIP-22 office, projects are AIP-20.
| Field | Value |
|---|---|
| AIP | 6 |
| Title | COMPANY (company/v1): the static company profile |
| Status | Final |
| Type | Core |
| Domain | companies.sh |
| Requires | AIP-1, AIP-2 |
| Composes with | AIP-9 (operators), AIP-20 (work), AIP-22 (office: positions, seats, reporting), AIP-34 (the company tree), AIP-42 (agents), AIP-47 (roles) |
| Spec author | Paperclip team (paperclipai/paperclip) |
| AIP editor | Jeremy André |
| Reference Impl | @agentproto/company |
Abstract
company/v1 is an open file-format standard for the static profile of
an AI company: who the company is, what it is for, what it values, and the
objectives it pursues. It is a set of markdown-with-frontmatter files in a
filesystem-first, vendor-neutral package. Any git repository conforming to
the layout is a valid company package.
AIP-6 owns the company profile and the objective, and nothing else of an
organization. Everything that used to be sketched here now has its own home:
a role is an AIP-47 ROLE.md, the positions (seats) and
reporting lines of the company are items of its AIP-22
office, an operator is AIP-9, an agent is
AIP-42, and a project is an AIP-34 node whose
work: is an AIP-20 WORK.md. AIP-6 anchors the format in
the AIP registry so dependent specs (AIP-7, AIP-8) can reference it by AIP
number. It started from the specification maintained at
paperclipai/paperclip; this text
is normative where the two differ.
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.
company/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
What AIP-6 owns
AIP-6 is the static company profile. The doctypes of a company package and who owns each:
| Doctype | Path | Owner | Notes |
|---|---|---|---|
company | COMPANY.md | AIP-6 | Root file: identity, mission, values. Exactly one per package. |
objective | objectives/<id>/OBJECTIVE.md | AIP-6 | An objective the company pursues. |
role | roles/<id>/ROLE.md | AIP-47 | A role is an AIP-47 role/v1 document. AIP-6 only keeps the conventional path. |
operator | operators/<id>/OPERATOR.md | AIP-9 | An agent holding a role. Extends AIP-42, see AIP-9. |
agent | agents/<id>/AGENT.md | AIP-42 | A standalone agent, NOT bound to a company role. The legacy kind: agent form is covered below. |
| office, positions, seats | OFFICE.md | AIP-22 | The org chart of the company. |
| project, work | the work: field of a node | AIP-20 | Not a company/v1 doctype. |
The JSON Schema in COMPANY.schema.json validates the company and
objective doctypes, and the legacy agent marker. It does not validate a
ROLE.md, an OPERATOR.md, an AGENT.md or an OFFICE.md: each has its
own schema in its own AIP.
Common frontmatter: doctype and id
Every doctype file carries schema: company/v1, a discriminator and an
identifier.
| Canonical | Alias | Meaning |
|---|---|---|
doctype | kind | Which doctype the file is: company, objective, or the legacy agent. |
id | slug | The identifier, equal to the folder name (objectives/<id>/). |
- Writers MUST emit
doctypeandid. - Readers MUST accept
kindasdoctypeandslugasid. AIP-6 sets no removal date for either alias: they are part of the format for as long ascompany/v1is, because files in the wild use them and a Final format does not break its readers. - A file that carries both an alias and its canonical field with different
values is refused with
alias_conflict. The JSON Schema enforces this fordoctypeandkind; a host enforces it foridandslug, which a schema cannot compare. - The folder-name rule uses the resolved identifier, whichever spelling carried it.
Where the company's organization lives
- Roles.
roles/<id>/ROLE.mdis an AIP-47 document (schema: role/v1). AIP-6 does not define a role schema any more: theroledoctype and itsmandatefield are gone fromCOMPANY.schema.json. A file that still declaresschema: company/v1withdoctype: roleis a legacy role file. A host MAY keep reading it, SHOULD warndoctype_moved, and migrates it by rewriting the frontmatter asrole/v1(idbecomesname,namebecomestitle,mandatebecomesmissionanddescription). Reading it has no removal date either. - Positions and seats. A position is a seat one operator holds at a time
(AIP-70
position). Seats, their holders and their reporting lines are items of the company's AIP-22 office, which spans the whole company tree (AIP-22 "An office spans a company tree"). COMPANY.md does not list them.structure.positions, its older aliasstructure.rolesandstructure.reports_tostay in the schema as deprecated fields: readers MUST keep accepting them, with no removal date, and when the company has an office the office is authoritative and these fields are only a seed. Writers SHOULD NOT emit them. - Operators. An operator is an agent holding a role, written as an
operators/<id>/OPERATOR.md(AIP-9). Its home is a node of the company tree and its seats come from the office. COMPANY.md does not list operators either. - Projects. A project is not an AIP-6 doctype. It is an
AIP-34 workspace node of the company tree, and its board,
items and status are the AIP-20
WORK.mditswork:field points to. An objective MAY be pursued by a project; the link is the objective'sownerand the work items, never a field of COMPANY.md. - The company is a tree of its own. A company is an
AIP-34 tree: the root node (type
company) requiresCOMPANY.md, as the AIP-34 example shows, and the guilds and projects are nodes below it. AIP-6 describes the file at the root; AIP-34 describes the tree.
Legacy agent slot
Before AIP-42, an agent in a company package was a
agents/<id>/AGENT.md declaring schema: company/v1, kind: agent and a
slug. That form stays valid: kind: agent is a legacy marker, slug is its
id, and AIP-42 sets no removal date for it (AIP-42 "Backward
compatibility"). COMPANY.schema.json recognises the marker so a company
package with such files still validates; the field set of the agent is
AIP-42's. New agents use schema: agent/v1.
Conventions
Common conventions adopted by all company/v1 files:
- Markdown canonical with YAML frontmatter
schema: company/v1field on every doctype defined here- Slug-based references, never database IDs
- Vendor-specific extensions under
metadata.<vendor>.* - Git-native: any repository hosting these files is a valid company
The implementer's guide is
ADAPTER.md,
the schema is
COMPANY.schema.json,
and worked packages are in
EXAMPLES.md.
Rationale
Filesystem-first over DB-first. A folder of files is diffable, forkable and reviewable in any git host. A database stays a projection that an adapter can rebuild.
Slug references over UUIDs. A slug survives a fork, a merge and a re-import. A database ID does not.
Markdown over pure JSON. The doctypes are written by people. Frontmatter keeps the structure checkable while the body stays prose.
A narrow AIP. The first version of company/v1 carried roles and the org chart. Both outgrew it: a role is reused by operators outside any company (AIP-47), and an org chart has to span guilds, views and holders from other trees (AIP-22). Keeping the profile small is what lets those AIPs evolve without a company/v1 revision.
Why doctype and id canonical. The schema and the examples have always
written them, and kind/slug are the spelling of the older agent slot. One
spelling for writers, both for readers, with no removal date, keeps every
existing package loadable.
Reference Implementation
The spec started from the upstream at paperclipai/paperclip. Inside the agentik ecosystem, the agentik-studio monorepo consumes companies via adapters; concrete usage emerges through AIP-8 (agencies engine).
Backwards Compatibility
AIP-6 is amended in place, as a Final spec. Every change below keeps existing packages loadable:
| Earlier | Now | Reader behaviour |
|---|---|---|
kind, slug | doctype, id canonical | Both spellings accepted, no removal date. |
kind: agent agent slot | AIP-42 schema: agent/v1 | The legacy form is recognised, no removal date. |
doctype: role with mandate | AIP-47 ROLE.md | MAY be read, doctype_moved warning. Not validated by COMPANY.schema.json. |
structure.positions, structure.roles, structure.reports_to | AIP-22 office seats | Accepted as a seed, the office wins. Deprecated, no removal date. |
| "sketch" of the doctype shape | the doctype table above | Editorial: the text is normative. |
Since 2026-10-23 (AIP-70) the canonical schema id is company/v1; documents that declare agentcompanies/v1 remain valid, and hosts MUST accept both.
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.
A legacy kind: agent file or a legacy doctype: role file is no safer
than its modern form: a host applies the same checks to it as to an
agent/v1 or role/v1 document, and a role or an office seat never widens
the policy of its holder (AIP-47, AIP-22).
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 (canvakit/v1): 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 (governance/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.