One repo. One graph. One source of truth. Humans write intent. AI executes. Everyone sees the same map.
This project turns your org chart, roles, and projects into a living graph that both people and AI can understand, traverse, and act on. It’s simple on purpose: markdown files with strict headers in a predictable directory. No new platform. No ceremony. Just clarity that scales.
Most companies run on scattered tools and meetings. Work gets lost in status docs, tickets, and DMs. This flips the model:
- Structure = Company → Departments → Roles
- Motion = Projects (folders)
- Output = Artifacts
Because it’s all text + metadata, AI can read it like code: who owns what, what’s in motion, what’s blocked, what shipped.
/company_os
company.md
/departments
/leadership
spec.md
/roles
ceo.md
chief_of_staff.md
/product
spec.md
/roles
product_manager.md
product_designer.md
/engineering
spec.md
/roles
engineering_manager.md
frontend_engineer.md
backend_engineer.md
devops_engineer.md
qa_engineer.md
security_engineer.md
/marketing
spec.md
/roles
marketing_manager.md
growth_marketer.md
content_marketer.md
product_marketing_manager.md
/sales
spec.md
/roles
sales_manager.md
account_executive.md
sales_development_representative.md
/customer_success
spec.md
/roles
customer_success_manager.md
support_engineer.md
/finance
spec.md
/roles
finance_manager.md
/people_ops
spec.md
/roles
people_ops_manager.md
recruiter.md
/it_ops
spec.md
/roles
it_administrator.md
/legal
spec.md
/roles
legal_counsel.md
/projects
/s73h
spec.md
/meeting_notes
2025-10-21_kickoff_call.md
2025-10-28_design_review.md
/source
crm_integration_requirements.md
vendor_selection_comparison.md
/artifacts
crm_ui_launch_announcement.md
crm_api_release_notes.md
crm_training_video_script.md
/a9f2
spec.md
/meeting_notes
2025-09-10_pricing_strategy.md
2025-09-15_exec_alignment.md
/source
competitive_analysis.md
customer_feedback_summary.md
/artifacts
pricing_page_copy.md
internal_sales_enablement_deck.md
Rules of the road
- Roles live under their department, but role IDs are globally unique (easy to reference anywhere).
- Projects are folders named with a 4-char base36 ID (e.g.,
s73h,a9f2). Each contains the spec, meeting notes, source inputs, and final artifacts. - Every doc has a YAML header and a created date.
This is the contract all specs follow. Keep it in your head and in CI.
id: # unique identifier
type: # company | department | role | project
title: # human-readable name
version: # "0.1" while evolving; later semver
status: # draft | active | paused | archived
owner: # role id or [role ids] (who approves changes)
created: # YYYY-MM-DD
last_updated: # YYYY-MM-DD
tags: # [optional keywords]
links: # [optional URLs to repos/dashboards/records]principles: # [short truths that guide work]
departments: # [ENGINEERING, PRODUCT, ...]roles: # [role ids owned by this department]
dependencies: # [COMPANY]
mission: # one-line purpose
metrics: # [{name, unit, target}]department: # DEPARTMENT id
reports_to: # role id (manager)
purpose: # one sentence
responsibilities:# [things this role does]
outputs: # [code | docs | campaigns | training | etc.]
success_metrics: # [{name, unit, target}]
dependencies: # [DEPARTMENT id]priority: # p0 | p1 | p2 | p3
owner: # role id (single throat to choke)
sponsors: # [role ids]
contributors: # [role ids]
dependencies: # [DEPARTMENT ids and/or COMPANY]
intent: # what outcome we want
scope:
in: # [included items]
out: # [excluded items]
deliverables: # [{name, type: code|docs|campaign|asset}]
acceptance_criteria: # ["testable statements"]
milestones: # [{name, date: YYYY-MM-DD}]
directories:
meeting_notes: /meeting_notes/
source: /source/
artifacts: /artifacts/Write for humans. Think like machines.
-
Declarative: say what good looks like.
- ✅ “Demo-to-close rate reaches 35%.”
- ❌ “Try to improve close rate by running more ads.”
-
Concrete: measurable, testable, unambiguous.
-
Compact: keep it short; kill fluff.
-
Neutral: reference roles and IDs, not people’s names.
-
Present tense: specs are active instructions.
-
One truth: if it isn’t verifiable, it doesn’t belong.
---
id: COMPANY
type: company
title: Company Spec
version: 0.2
status: active
owner: [ceo, chief_of_staff]
created: 2025-10-22
last_updated: 2025-10-22
principles:
- Clarity over consensus.
- Ship small, learn fast.
- Measure outcomes, not activity.
departments: [LEADERSHIP, PRODUCT, ENGINEERING, MARKETING, SALES, CUSTOMER_SUCCESS, FINANCE, PEOPLE_OPS, IT_OPS, LEGAL]
---
## Intent
Define the constants and principles the rest inherit.---
id: ENGINEERING
type: department
title: Engineering Department
version: 0.2
status: active
owner: engineering_manager
created: 2025-10-22
last_updated: 2025-10-22
roles: [engineering_manager, frontend_engineer, backend_engineer, devops_engineer, qa_engineer, security_engineer]
dependencies: [COMPANY]
mission: Build, secure, and operate the product with speed and reliability.
metrics:
- name: uptime
unit: percent
target: 99.9
---
## Responsibilities
- Architecture, implementation, CI/CD, reliability, security.---
id: frontend_engineer
type: role
title: Frontend Engineer
version: 0.2
status: active
department: ENGINEERING
reports_to: engineering_manager
owner: engineering_manager
created: 2025-10-22
last_updated: 2025-10-22
purpose: Build fast, accessible UI that meets product specs.
responsibilities:
- Implement UI components and tests.
- Maintain performance budgets (LCP, INP, CLS).
outputs: [code, tests, docs]
success_metrics:
- name: core_web_vitals
unit: score
target: "Good on LCP, INP, CLS"
dependencies: [ENGINEERING]
---
## Definition of Done
Meets acceptance criteria, tests pass, perf budgets respected.---
id: s73h
type: project
title: Custom CRM Implementation
version: 0.2
status: active
priority: p1
owner: product_manager
sponsors: [sales_manager, marketing_manager, customer_success_manager]
contributors: [engineering_manager, frontend_engineer, backend_engineer, qa_engineer]
dependencies: [PRODUCT, ENGINEERING]
created: 2025-10-21
last_updated: 2025-10-28
intent: Deliver a CRM tailored for Sales, Marketing, and Customer Success with clear data ownership and low switching cost.
scope:
in: [Opportunity mgmt, Lead tracking, Attribution reporting]
out: [Billing, Payments]
deliverables:
- name: crm_ui
type: code
- name: crm_api
type: code
- name: crm_docs
type: docs
acceptance_criteria:
- "Sales can create/update opportunities in <3 clicks."
- "Marketing sees first- and last-touch attribution per lead."
milestones:
- name: discovery_complete
date: 2025-11-05
directories:
meeting_notes: /meeting_notes/
source: /source/
artifacts: /artifacts/
---
## Notes
Link repos, tickets, and dashboards in `links:` in the header as they’re created.-
Branch per change
feat/spec-s73h,chore/update-role-frontend,fix/typo-engineering-spec -
Edit the spec Keep to the language rules. Update
last_updated. Never removecreated. -
Pull Request template
### What changed - … ### Why - … ### Impact - Affects roles: [frontend_engineer] - Affects projects: [s73h]
-
Review standard
- Is it declarative and testable?
- Do IDs and references resolve?
- Does it conflict with existing intent?
-
Merge The repo is the truth. Downstream tools sync from here.
- Validate YAML headers (types, enums, dates).
- Ensure every doc has
createdandlast_updated. - Ensure project folders match
^[a-z0-9]{4}$. - Resolve all references (ids must exist).
- Optional: run a similarity check on
intentto flag duplicate efforts.
Tip: Generate a Mermaid graph on merge to visualize the live org + projects map.
This structure is “agent-ready.”
-
Each role spec can power a role agent (e.g.,
frontend_engineeragent writes UI code;marketing_manageragent writes campaigns). -
Each project folder is a runtime:
/source→ inputs/meeting_notes→ decisions/artifacts→ outputsspec.md→ definition of done
-
Agents can traverse the graph, pick up context, create artifacts, and report status without manual orchestration.
- Read access: company-wide by default (transparency beats confusion).
- Write access: by
ownerrole in header + code owners in Git. - Sensitive links go in
links:(not in body). - PII and secrets belong in vaults; link, don’t paste.
Why not put dates in project folder names?
Identity should be stable. Dates live in created and last_updated. Renames break links and scripts.
Why roles, not people? Roles are reusable and scalable. People come and go; the role’s intent persists.
Why 4-char project IDs? Base36 gives ~1.68M combos at 4 chars; ~2.18B at 6. Short, unique, easy to say, easy to grep.
Is this another wiki? No. Wikis describe work. This directs work.
- GitHub Action: spec linter + graph export
- Similarity bot: flags duplicate efforts across projects
- “Spec Studio”: tiny UI for creating/updating specs with validation
- Agent hooks: trigger generators from
project/spec.md(e.g., docs, code stubs, briefs)
Org chart as code. Write intent once. Let AI traverse the graph, do the work, and show you the truth in real time.