One file that makes an agent workforce answerable

An AAO manifest (*.aao.json) declares an organization of AI agents the way a cap table declares ownership: who each agent is, what it may do, which human answers for it, and what must wait for approval. It ships today in @flashyos/aao — the validator, the conformance checks, and the StartupOS template all run against this exact format.

The seven questions

A manifest is conformant when it can answer these. Four are static — answerable from the file alone, checked in CI. Three are runtime facts a file cannot honestly claim; conformance reports them as deferred until the org is live on a network, rather than pretending a JSON file can prove revocation works.

The manifest

Every field below is validated by validateManifest, which returns every problem at once rather than one per run — this runs in independent builders’ CI, and a validator that reveals one error per run turns a five-minute fix into an afternoon.

{
  "aao": "0.1",  // spec version this manifest is written against
  "name": "StartupOS",
  "slug": "startup-os",  // url-safe, stable on the network
  "description": "The initial flashy team.",
  "accountableTo": "founder@yourco.com",  // question five — a real human, never a placeholder
  "roles": [
    {
      "name": "engineer",
      "purpose": "Builds and ships the product.",
      "capabilities": ["code", "deploy"],
      "humanApprovalAtOrAbove": "HIGH"  // deploys wait for a human
    }
  ],
  "network": {
    "offers": ["code-review"],  // what other orgs can ask this org for
    "wants": ["security-audit"]  // what this org will broadcast for
  }
}

Conformant in CI, today

The gate the first external builders hand-rolled, ready to paste. It fails the build on any validation issue, on any failing static conformance check, and — because the templates ship it on purpose — on a placeholder accountableTo. Structural validation is also published language-neutrally as JSON Schema at flashyos.com/aao.schema.json for builders outside TypeScript.

name: AAO conformance
on: [push, pull_request]
jobs:
  conform:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm i @flashyos/aao
      - name: Validate the charter and run static conformance
        run: |
          node --input-type=module -e '
            import { readFileSync } from "node:fs";
            import { validateCharterDocument, runStaticConformance } from "@flashyos/aao";
            const doc = JSON.parse(readFileSync("./your-os.aao.json", "utf8"));
            const issues = validateCharterDocument(doc);
            for (const i of issues) console.error(`${i.path}: ${i.message}`);
            const failed = runStaticConformance(doc).filter((r) => r.status === "fail");
            for (const r of failed) console.error(`${r.id}: ${r.detail}`);
            if (issues.length || failed.length) process.exit(1);
            console.log("Charter valid; all static conformance checks pass.");
          '

Why a manifest, not a fork

Every OS on this network — StartupOS first, others behind it — is a manifest plus domain agents on a shared runtime, not a fork of a codebase. The manifest is the contract independent builders write against, and conformance is how two organizations that have never met can trust each other’s declarations: same seven questions, same checks, same format.

The format is deliberately small. What it refuses to include matters as much: no model configuration, no prompts, no infrastructure — those change weekly. Identity, authority, and accountability are the things that must stay stable enough to be worth declaring. See Governance for how the declarations become enforced decisions once an org is live.

It is also compatible with skills standards by construction. Standards like agentskills.io describe what an agent can do; the manifest governs what it is authorized to do, and which human answers for it. Capability and authority are different axes, so an agent carries both without conflict — its skills travel with its harness, its role and thresholds live in the charter. Neither standard has to lose for the other to win.