Author Company

Author an agentcompanies/v1 workspace (AIP-6)

Use this skill when the user asks to define, draft, or scaffold a company as a portable file-format package. The skill produces a valid AIP-6 agentcompanies/v1 workspace — the COMPANY.md root plus one folder per role and per objective. Every doctype is a markdown file with YAML frontmatter; references between them are slug-based; the result is a git-native package any conforming adapter can load.

When to use

• "Define our company as a file-format package."
• "Draft the org structure for a two-person agency."
• "Scaffold the roles and objectives for our marketing pod."
• "Express this team's reporting tree as agentcompanies/v1."

When NOT to use

• The user wants a single role's prompt with no surrounding org structure → they want an operator definition (AIP-8), not a company.
• The user wants governance policies (caps, approvals, audit) → use AIP-7 once the company doctypes exist.
• The user wants to call an existing company package — no authoring needed.

Process

Eight steps. The order matters: identity first, then mission, then structure, then objectives, then references, then validation. Skip the cross-reference step and you ship a workspace whose roles point at objectives that don't exist.

1. Fix the company identity

• Pick id: kebab-case, 2–64 chars, recognisable as the company's short handle (pricewatch, not company-1). The id is the folder name.
• Write name: the human display name.
• Pick a one-paragraph description. Address it to a reader who has never heard of the company.

The folder layout from this point on is fixed:

<company-slug>/
  COMPANY.md
  roles/
    <role-slug>/ROLE.md
  objectives/
    <objective-slug>/OBJECTIVE.md

Any extra files (READMEs, prompts, fixtures) live alongside but are not normative.

2. Write the mission, values, and tone

Inside COMPANY.md frontmatter:

• mission: one paragraph. Read by every operator at boot — keep it tight.
• values: 3–6 short statements. Surfaced in role prompts.
• description: human-facing summary, longer than mission.

Rules:

• No vendor names in the mission. The company package is portable; bake-in to a vendor breaks portability.
• Mission text is the shared substrate every role inherits. Per-role tone goes in the role file, not here.

3. Pick the structure

Decide the org shape before writing role files. Three common shapes:

Inside COMPANY.md:

structure:
  roles: [founder, ops]
  objectives: [q3-pipeline, retention-90]
  reports_to:
    ops: founder

Roles not present in reports_to are top-level. Roles in reports_to MUST resolve to a slug also listed in structure.roles.

4. Author each role

For every slug in structure.roles, create roles/<slug>/ROLE.md with frontmatter:

schema: agentcompanies/v1
doctype: role
id: founder
name: Founder
mandate: >
  Set product direction, own customer relationships above $5K MRR, unblock other
  roles. Hand off to ops once a process is recurring.
reports_to: ~ # top-level — omit or use ~
scope:
  owns: ["product-direction", "enterprise-customers"]
  capabilities: ["product.write", "customers.write"]
objectives: [q3-pipeline]
tools: [pricing-snapshot, send-email-brevo]
workflows: [contract-send]

Required fields: schema, doctype: role, id, name, mandate.

Conventions:

• mandate is the bounded-autonomy contract. Read by the governance layer (AIP-7) when sizing approvals. Write it intentionally.
• scope.owns is free-text, intentionally informal — names of resources the role is accountable for.
• scope.capabilities is structured — slugs the AIP-7 capability registry recognises. Keep narrow.
• tools and workflows reference the host's AIP-14 TOOL.md and AIP-15 WORKFLOW.md catalogs by slug. Adapter resolves; unresolved slugs error.

5. Author each objective

For every slug in structure.objectives (and any sub-objectives roles list under objectives), create objectives/<slug>/OBJECTIVE.md:

schema: agentcompanies/v1
doctype: objective
id: q3-pipeline
name: Q3 Pipeline
statement: >
  Close $250K of new MRR by Sept 30, with at least 3 logos above $5K MRR.
owner: founder
horizon: quarter
status: active
key_results:
  - id: kr-mrr
    statement: New MRR closed
    target: "$250K"
  - id: kr-logos
    statement: Logos above $5K MRR
    target: "3"

Required fields: schema, doctype: objective, id, name, statement.

Conventions:

• owner MUST be a role slug that exists in the company.
• horizon is informational; use ongoing for objectives without a fixed end date.
• key_results[] is optional but encouraged. Each KR has its own id (kebab-case, scoped to the objective) so progress updates can reference it stably.
• For decomposition, set parent: <slug> on the child and list children: [<slugs>] on the parent. The adapter validates the edges agree both directions.

6. Cross-reference and link

Every reference between doctypes is a slug. Adapter rules:

Walk every reference before declaring the workspace done. A dangling slug is a spec bug.

7. Imports (optional)

To pull a role or objective from a registry, declare under COMPANY.md's imports[]:

imports:
  - from: "open-companies/marketing@^1.0.0"
    as: role
    id: marketer
  - from: "open-companies/standard-okrs@^1.0.0"
    as: objective
    id: nps-90

The adapter resolves from against its package registry, materialises the doctype into the local workspace under roles/<id>/ROLE.md (or objective equivalent), and treats it identically to a hand-authored doctype after that. Use alias if a local slug would collide.

8. Validate

Validate every doctype against ./COMPANY.schema.json:

# Validate the root
npx ajv validate -s ./COMPANY.schema.json -d <pkg>/COMPANY.md

# Validate every role and objective
find <pkg>/roles      -name 'ROLE.md'      -exec npx ajv validate -s ./COMPANY.schema.json -d {} \;
find <pkg>/objectives -name 'OBJECTIVE.md' -exec npx ajv validate -s ./COMPANY.schema.json -d {} \;

Then run the cross-reference check (your adapter's validate helper — see ./ADAPTER.md). Specifically check:

• Every slug in structure.roles resolves to a ROLE.md.
• Every slug in structure.objectives resolves to an OBJECTIVE.md.
• Every reports_to value is a known role.
• Every objective.owner is a known role.
• Every objective.parent ↔ objective.children edge is symmetric.
• No role lists an objective that doesn't list it as owner (warn, don't error — multi-role objectives are allowed).

Fix every error before declaring success.

Output

Produce a folder tree:

<company-slug>/
  COMPANY.md
  roles/
    <role-slug>/ROLE.md
    ...
  objectives/
    <objective-slug>/OBJECTIVE.md
    ...

Reply to the user with:

1. The folder you wrote to.
2. An ASCII tree of the org (roles + reports_to edges) so they can verify the structure.
3. A list of objectives with their owners, so they can verify accountability.
4. Open assumptions — fields you guessed defaults for that the user might want to override (horizon: quarter, default capabilities per role, etc.).

Do NOT install or instantiate the company yourself. Authoring ends with the files written; instantiation (per AIP-8) is a separate step.

See also

• AIP-6 — agentcompanies/v1 spec
• AIP-7 — governance, capabilities, approval
• AIP-8 — agencies engine, operator instances
• AIP-14 — TOOL.md spec — referenced from role.tools
• AIP-15 — WORKFLOW.md spec — referenced from role.workflows
• ./ADAPTER.md — implementer's guide for hosts
• ./EXAMPLES.md — reference workspaces (solo, two-role, tree, decomposed objectives, imports, fork)
• ./COMPANY.schema.json — frontmatter validator