{"slug": "show-hn-company-as-code-spec-and-validator", "title": "Show HN: Company-as-Code –> Spec and Validator", "summary": "Pirol-ai released Company as Code, an open standard and validator tool called charta that lets organizations describe goals, roles, processes and policies as plain markdown files in git so AI agents can follow them. The tool, installable via `brew install pirol-ai/tap/charta` or `npm i -g @pirol/charta` on macOS, Linux and Windows, checks every cross-file reference and fails validation when a reference does not resolve, and `charta plan` previews the impact of a change before it is made. Files without the `api:` key are ignored, allowing existing notes and documents to remain in the same repository.", "body_md": "**Describe your company once — every AI agent works by your rules.**\n\nThe knowledge about how your company works lives in your head, in chat messages, and in wiki pages that nobody updates. That was okay when a new coworker joined every few months. Now every AI agent session is a new coworker — it starts a hundred times a day, and it knows nothing.\n\nCompany as Code is an open standard to write this knowledge down once: goals, roles, processes, and policies as plain markdown files in git. People can read them. Agents follow them. A small tool checks them like code.\n\nOne file per resource. A small typed header, then normal language:\n\n```\n---\napi: company-as-code.org/v0\ntype: process\nid: invoicing\ntitle: Monthly invoicing\nowner: role/ops\nserves: [goal/wholesale-growth]\npolicies: [policy/four-eyes-payments]\n---\n\nTrigger: 1st of each month. Steps: agent drafts invoices from delivery notes;\nops reviews; send; log. Done when: all invoices sent and logged.\n```\n\nThe header connects the files into a graph: this process is **owned by** a role, **serves** a\ngoal, and **follows** a policy. The tool checks every reference. If a reference points to\nsomething that does not exist, validation fails. The text below the header is normal language —\nfor people and for agents.\n\nFiles without the `api:` key are ignored. Your notes and other documents can stay in the same\nrepository.\n\n```\nbrew install pirol-ai/tap/charta\nnpm i -g @pirol/charta\n```\n\nWorks on macOS, Linux, and Windows. Binaries are on the\n[releases page](https://github.com/Pirol-ai/company-as-code/releases). To build from source:\n`cargo build --release --manifest-path charta/Cargo.toml`.\n\nSee what happens when a company description breaks:\n\n```\ngit clone https://github.com/Pirol-ai/company-as-code && cd company-as-code\nbash demo/demo.sh\n```\n\nThe demo uses a small example company, a coffee roastery ([`demo/company/`](https://github.com/Pirol-ai/company-as-code/blob/main/demo/company) —\nopen it, it is just files). It deletes the Operations role — the person who runs invoicing and\ncustomer support. Suddenly three processes have no owner. `charta validate` finds every broken\nreference. `charta plan` shows what the change would affect — before it happens.\n\nThis is the same company as a graph — generated with `charta graph . --format mermaid`, rendered\nby GitHub:\n\n```\nflowchart LR\n  company_aurora_roasters[\"company/aurora-roasters\"]\n  goal_five_star_service[\"goal/five-star-service\"]\n  goal_wholesale_growth[\"goal/wholesale-growth\"]\n  policy_agent_autonomy[\"policy/agent-autonomy\"]\n  policy_four_eyes_payments[\"policy/four-eyes-payments\"]\n  process_customer_follow_up[\"process/customer-follow-up\"]\n  process_invoicing[\"process/invoicing\"]\n  process_weekly_roast_plan[\"process/weekly-roast-plan\"]\n  role_agent[\"role/agent\"]\n  role_founder[\"role/founder\"]\n  role_ops[\"role/ops\"]\n  goal_five_star_service -->|owner| role_ops\n  goal_wholesale_growth -->|owner| role_founder\n  process_customer_follow_up -->|owner| role_ops\n  process_customer_follow_up -->|serves| goal_five_star_service\n  process_invoicing -->|owner| role_ops\n  process_invoicing -->|serves| goal_wholesale_growth\n  process_invoicing -->|policies| policy_four_eyes_payments\n  process_weekly_roast_plan -->|owner| role_ops\n  process_weekly_roast_plan -->|serves| goal_wholesale_growth\n  process_weekly_roast_plan -. prose .-> role_agent\n  role_agent -. prose .-> policy_agent_autonomy\n```\n\nDelete `role/ops` and you can see the problem before the tool tells you: four arrows point at it.\n`--format dot` gives the same graph as Graphviz DOT for every other tool.\n\nYou do not need this repository — only the installed tool:\n\n```\nmkdir my-company && cd my-company && git init\ncharta init --name \"Acme GmbH\"   # creates company.yaml: the root of your description\ncharta validate .                # check it any time — every reference must resolve\n```\n\nWith npm, you can start without installing anything:\n\n```\nnpm init @pirol/charta -- --name \"Acme GmbH\"\n```\n\nThe other commands, once you have a few files:\n\n```\ncharta query orphans .     # which resources does nothing reference?\ncharta plan .              # what would your uncommitted change affect?\ncharta graph . --format mermaid   # the graph, rendered by GitHub\ncharta mcp .               # serve the company graph to any MCP-capable agent\n```\n\nWant a filled-in starting point instead of an empty one? Copy [`template/`](https://github.com/Pirol-ai/company-as-code/blob/main/template) from this\nrepository.\n\n**You do not write this alone — your agent writes it with you.** Tell your agent how your\ncompany works, in your own words. The agent writes the files, runs `charta validate`, and fixes\nwhat is broken. Start with what a new coworker would need to know on day one — every agent\nsession is that new coworker.\n\nThe description then grows while you work: when an agent asks a question that only you can answer, that answer is a missing file. The agent adds it, validates it, and never asks again. Start small. Add more only when you need it.\n\n`charta` is one small binary (Apache-2.0):\n\n| command | what it does | \n|---|---|\n| `charta validate` | checks the description: files are well-formed, every reference resolves, required fields exist | \n| `charta graph` /`charta query` | the graph as JSON, Mermaid, or Graphviz DOT ( `--format` ); find orphans and backlinks | \n| `charta plan` | compares your working tree with the last git commit and shows what a change would affect | \n| `charta mcp` | an MCP server — AI agents can read and query the company graph as tools | \n\nDetails in [`charta/`](https://github.com/Pirol-ai/company-as-code/blob/main/charta).\n\n| Path | What | \n|---|---|\n| [`spec/`](https://github.com/Pirol-ai/company-as-code/blob/main/spec) | The format: purpose, header fields, types, references, conformance levels. Working draft; frozen at 1.0. | \n| [`conformance/`](https://github.com/Pirol-ai/company-as-code/blob/main/conformance) | Test fixtures. The test suite defines the standard, not the prose. | \n| [`charta/`](https://github.com/Pirol-ai/company-as-code/blob/main/charta) | The reference toolchain (Rust). | \n| [`template/`](https://github.com/Pirol-ai/company-as-code/blob/main/template) | A minimal starter company. | \n| [`demo/`](https://github.com/Pirol-ai/company-as-code/blob/main/demo) | An example company and the 30-second demo. | \n\nCompany as Code is **100% compatible with Google's\n[Open Knowledge Format (OKF)](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)**.\nEvery resource file is also a valid OKF concept. The fields `type`, `title`, `description`, and\n`tags` have the same meaning as in OKF. Unknown fields are kept, never deleted. OKF files can\nlive in the same repository; charta ignores them. On top of OKF, Company as Code adds: an `id`,\naddressing (`type/id`), references that must resolve, and required fields per type.\n\n1. **Text first, schema small.** The meaning lives in normal language. Structure lives in the\nheader. Every extra field makes adoption harder.\n2. **Check the structure, not the text.** Strict process notations failed because they demanded\ntoo much precision from people. Agents can handle normal language. Only references and\nrequired fields are enforced.\n3. **The description belongs to you, not to a tool.** The files on disk are the exchange format.\nExport is`git clone` .\n4. **Keep what you do not know.** Unknown types and fields are preserved exactly. Read and write\nmust not change a file.\n5. **No new language.** Markdown and YAML — nothing to learn. No query language: fixed commands,\nJSON output, agents combine them.\n\nToolchain and fixtures: Apache-2.0 ([LICENSE](https://github.com/Pirol-ai/company-as-code/blob/main/LICENSE)). Specification text: CC-BY-4.0\n([spec/LICENSE](https://github.com/Pirol-ai/company-as-code/blob/main/spec/LICENSE)). An open standard, created and maintained by\n[Pirol Labs](https://pirol.ai).", "url": "https://wpnews.pro/news/show-hn-company-as-code-spec-and-validator", "canonical_source": "https://github.com/Pirol-ai/company-as-code", "published_at": "2026-09-23 08:30:50+00:00", "updated_at": "2026-09-23 08:59:35.393036+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "agent-protocols"], "entities": ["Pirol-ai", "Company as Code", "charta", "GitHub", "npm", "Homebrew", "Acme GmbH", "aurora-roasters"], "alternates": {"html": "https://wpnews.pro/news/show-hn-company-as-code-spec-and-validator", "markdown": "https://wpnews.pro/news/show-hn-company-as-code-spec-and-validator.md", "text": "https://wpnews.pro/news/show-hn-company-as-code-spec-and-validator.txt", "jsonld": "https://wpnews.pro/news/show-hn-company-as-code-spec-and-validator.jsonld"}}