Use CorpoSpec in your own repo
Drop a .corpospec/ directory into any Git repository, start with the
pillars you need, and point your editor at the versioned schema URLs. No server,
no account, no lock-in.
1. Create the directory
# From your repository root:
mkdir -p .corpospec/{entity,people,governance/decisions}
2. Write a manifest
The manifest tells tools which spec version you target and which pillars your repository populates.
corpospec_version pins the schema URL prefix — everything else is resolved from there.
# .corpospec/manifest.yaml
# yaml-language-server: $schema=https://corpospec.com/schemas/v0.7.1/manifest.schema.json
corpospec_version: "0.7.1"
schema_version: "0.7.1"
company_id: "acme"
created: "2026-04-01"
pillars:
- entity
- people
- governance
3. Add your first entity
# .corpospec/entity/company.yaml
# yaml-language-server: $schema=https://corpospec.com/schemas/v0.7.1/entity.schema.json
legal_name: "ACME Corporation, Inc."
trade_name: "ACME"
url: "https://acme.example"
email: "hello@acme.example"
address:
street: "1 Market Street"
city: "Berlin"
country: "DE"
4. Wire your editor
Every major YAML language server resolves the $schema header. VS Code,
JetBrains, Neovim, and Sublime all work without configuration — the first line of
the file is enough.
The URL format is always: https://corpospec.com/schemas/<version>/<slug>.schema.json.
Browse slugs on the schemas page.
5. Validate locally
Use the reference validator from the UNSTARTER repo, or any JSON Schema Draft 2020-12 validator.
# Using the reference validator:
cargo install --git https://github.com/beevelop/UNSTARTER corpospec-validate
corpospec-validate validate .
# Using ajv (Node):
npx ajv validate \
-s "https://corpospec.com/schemas/v0.7.1/entity.schema.json" \
-d ".corpospec/entity/company.yaml"
6. Expand one pillar at a time
CorpoSpec is additive. Start with entity/ and people/, add governance/decisions/ when
you want to record architecture decisions as Git-native artefacts, add financials/
when the model becomes load-bearing. Every pillar you adopt is validated; every pillar
you skip is simply not declared in manifest.yaml.
7. Reference across entities
Use PathRefs to link entities. The validator resolves them to real files — broken references fail validation.
# .corpospec/governance/decisions/0001-adopt-corpospec.md
# yaml-language-server: $schema=https://corpospec.com/schemas/v0.7.1/bdr.schema.json
id: governance/decisions/0001-adopt-corpospec
status: accepted
date: "2026-04-21"
decision_makers:
- people/team/alex # PathRef → people/team/alex.yaml
pillars:
- governance