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.

FieldValue
AIP6
TitleCOMPANY (company/v1): the static company profile
StatusFinal
TypeCore
Domaincompanies.sh
RequiresAIP-1, AIP-2
Composes withAIP-9 (operators), AIP-20 (work), AIP-22 (office: positions, seats, reporting), AIP-34 (the company tree), AIP-42 (agents), AIP-47 (roles)
Spec authorPaperclip team (paperclipai/paperclip)
AIP editorJeremy 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:

DoctypePathOwnerNotes
companyCOMPANY.mdAIP-6Root file: identity, mission, values. Exactly one per package.
objectiveobjectives/<id>/OBJECTIVE.mdAIP-6An objective the company pursues.
roleroles/<id>/ROLE.mdAIP-47A role is an AIP-47 role/v1 document. AIP-6 only keeps the conventional path.
operatoroperators/<id>/OPERATOR.mdAIP-9An agent holding a role. Extends AIP-42, see AIP-9.
agentagents/<id>/AGENT.mdAIP-42A standalone agent, NOT bound to a company role. The legacy kind: agent form is covered below.
office, positions, seatsOFFICE.mdAIP-22The org chart of the company.
project, workthe work: field of a nodeAIP-20Not 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.

CanonicalAliasMeaning
doctypekindWhich doctype the file is: company, objective, or the legacy agent.
idslugThe identifier, equal to the folder name (objectives/<id>/).
  • Writers MUST emit doctype and id.
  • Readers MUST accept kind as doctype and slug as id. AIP-6 sets no removal date for either alias: they are part of the format for as long as company/v1 is, 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 for doctype and kind; a host enforces it for id and slug, 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.md is an AIP-47 document (schema: role/v1). AIP-6 does not define a role schema any more: the role doctype and its mandate field are gone from COMPANY.schema.json. A file that still declares schema: company/v1 with doctype: role is a legacy role file. A host MAY keep reading it, SHOULD warn doctype_moved, and migrates it by rewriting the frontmatter as role/v1 (id becomes name, name becomes title, mandate becomes mission and description). 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 alias structure.roles and structure.reports_to stay 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.md its work: field points to. An objective MAY be pursued by a project; the link is the objective's owner and 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) requires COMPANY.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/v1 field 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:

EarlierNowReader behaviour
kind, slugdoctype, id canonicalBoth spellings accepted, no removal date.
kind: agent agent slotAIP-42 schema: agent/v1The legacy form is recognised, no removal date.
doctype: role with mandateAIP-47 ROLE.mdMAY be read, doctype_moved warning. Not validated by COMPANY.schema.json.
structure.positions, structure.roles, structure.reports_toAIP-22 office seatsAccepted as a seed, the office wins. Deprecated, no removal date.
"sketch" of the doctype shapethe doctype table aboveEditorial: 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 →