Show HN: Company-as-Code –> Spec and Validator

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.

Describe your company once — every AI agent works by your rules. The 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. Company 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. One file per resource. A small typed header, then normal language: --- api: company-as-code.org/v0 type: process id: invoicing title: Monthly invoicing owner: role/ops serves: goal/wholesale-growth policies: policy/four-eyes-payments --- Trigger: 1st of each month. Steps: agent drafts invoices from delivery notes; ops reviews; send; log. Done when: all invoices sent and logged. The header connects the files into a graph: this process is owned by a role, serves a goal, and follows a policy. The tool checks every reference. If a reference points to something that does not exist, validation fails. The text below the header is normal language — for people and for agents. Files without the api: key are ignored. Your notes and other documents can stay in the same repository. brew install pirol-ai/tap/charta npm i -g @pirol/charta Works on macOS, Linux, and Windows. Binaries are on the releases page https://github.com/Pirol-ai/company-as-code/releases . To build from source: cargo build --release --manifest-path charta/Cargo.toml . See what happens when a company description breaks: git clone https://github.com/Pirol-ai/company-as-code && cd company-as-code bash demo/demo.sh The demo uses a small example company, a coffee roastery demo/company/ https://github.com/Pirol-ai/company-as-code/blob/main/demo/company — open it, it is just files . It deletes the Operations role — the person who runs invoicing and customer support. Suddenly three processes have no owner. charta validate finds every broken reference. charta plan shows what the change would affect — before it happens. This is the same company as a graph — generated with charta graph . --format mermaid , rendered by GitHub: flowchart LR company aurora roasters "company/aurora-roasters" goal five star service "goal/five-star-service" goal wholesale growth "goal/wholesale-growth" policy agent autonomy "policy/agent-autonomy" policy four eyes payments "policy/four-eyes-payments" process customer follow up "process/customer-follow-up" process invoicing "process/invoicing" process weekly roast plan "process/weekly-roast-plan" role agent "role/agent" role founder "role/founder" role ops "role/ops" goal five star service -- |owner| role ops goal wholesale growth -- |owner| role founder process customer follow up -- |owner| role ops process customer follow up -- |serves| goal five star service process invoicing -- |owner| role ops process invoicing -- |serves| goal wholesale growth process invoicing -- |policies| policy four eyes payments process weekly roast plan -- |owner| role ops process weekly roast plan -- |serves| goal wholesale growth process weekly roast plan -. prose .- role agent role agent -. prose .- policy agent autonomy Delete role/ops and you can see the problem before the tool tells you: four arrows point at it. --format dot gives the same graph as Graphviz DOT for every other tool. You do not need this repository — only the installed tool: mkdir my-company && cd my-company && git init charta init --name "Acme GmbH" creates company.yaml: the root of your description charta validate . check it any time — every reference must resolve With npm, you can start without installing anything: npm init @pirol/charta -- --name "Acme GmbH" The other commands, once you have a few files: charta query orphans . which resources does nothing reference? charta plan . what would your uncommitted change affect? charta graph . --format mermaid the graph, rendered by GitHub charta mcp . serve the company graph to any MCP-capable agent Want 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 repository. You do not write this alone — your agent writes it with you. Tell your agent how your company works, in your own words. The agent writes the files, runs charta validate , and fixes what is broken. Start with what a new coworker would need to know on day one — every agent session is that new coworker. The 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. charta is one small binary Apache-2.0 : | command | what it does | |---|---| | charta validate | checks the description: files are well-formed, every reference resolves, required fields exist | | charta graph / charta query | the graph as JSON, Mermaid, or Graphviz DOT --format ; find orphans and backlinks | | charta plan | compares your working tree with the last git commit and shows what a change would affect | | charta mcp | an MCP server — AI agents can read and query the company graph as tools | Details in charta/ https://github.com/Pirol-ai/company-as-code/blob/main/charta . | Path | What | |---|---| | 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. | | conformance/ https://github.com/Pirol-ai/company-as-code/blob/main/conformance | Test fixtures. The test suite defines the standard, not the prose. | | charta/ https://github.com/Pirol-ai/company-as-code/blob/main/charta | The reference toolchain Rust . | | template/ https://github.com/Pirol-ai/company-as-code/blob/main/template | A minimal starter company. | | demo/ https://github.com/Pirol-ai/company-as-code/blob/main/demo | An example company and the 30-second demo. | Company as Code is 100% compatible with Google's Open Knowledge Format OKF https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md . Every resource file is also a valid OKF concept. The fields type , title , description , and tags have the same meaning as in OKF. Unknown fields are kept, never deleted. OKF files can live in the same repository; charta ignores them. On top of OKF, Company as Code adds: an id , addressing type/id , references that must resolve, and required fields per type. 1. Text first, schema small. The meaning lives in normal language. Structure lives in the header. Every extra field makes adoption harder. 2. Check the structure, not the text. Strict process notations failed because they demanded too much precision from people. Agents can handle normal language. Only references and required fields are enforced. 3. The description belongs to you, not to a tool. The files on disk are the exchange format. Export is git clone . 4. Keep what you do not know. Unknown types and fields are preserved exactly. Read and write must not change a file. 5. No new language. Markdown and YAML — nothing to learn. No query language: fixed commands, JSON output, agents combine them. Toolchain and fixtures: Apache-2.0 LICENSE https://github.com/Pirol-ai/company-as-code/blob/main/LICENSE . Specification text: CC-BY-4.0 spec/LICENSE https://github.com/Pirol-ai/company-as-code/blob/main/spec/LICENSE . An open standard, created and maintained by Pirol Labs https://pirol.ai .