Why I Built a Description Language for Business Logic

Daniel Klas — Mon, 30 Mar 2026 07:58:17 +0000

Why I Built a Description Language for Business Logic

Most companies don't fail because of bad strategy.

They fail because their operational logic is invisible.

It lives in Slack threads, onboarding notes, CRM fields, spreadsheets, automation tools — and in the heads of people who eventually leave. Nobody planned it that way. It just happened, one workaround at a time.

I'm a master carpenter and kitchen studio owner in Germany. I'm also — apparently — someone who builds programming language tooling in his spare time.

This is the story of why I built OrgScript.

The problem I kept running into

Running a small business means your processes are everywhere and nowhere at the same time.

A lead comes in. Someone knows what to do with it. But that knowledge isn't written down anywhere reliable. It's in the last WhatsApp message someone sent, or in the mental model of the person who's been doing it for three years.

When I started automating things — CRM workflows, lead qualification, order processing — I kept hitting the same wall: I couldn't describe what the business actually does in a way that was precise enough for software but still readable by a non-developer.

BPMN is too heavy. You need specialized tools just to open the file.

YAML and JSON are machine-readable but unpleasant to write and impossible to hand to a business owner.

Natural language documents are readable but too vague for anything automated.

And AI? It's great at pattern matching, but if you ask it to interpret a process that lives in four different documents and three people's heads, it guesses. Often wrong.

I wanted something that sat between natural language and executable code. Something you could put in Git, review in a pull request, run a linter on — and still hand to someone without a software background.

So I built it.

What OrgScript looks like

Here's the lead qualification process from my own kitchen business, written in OrgScript:

process CraftBusinessLeadToOrder

  when lead.created

  if lead.source = "referral" then
    assign lead.priority = "high"
    assign lead.sales_path = "premium"
    notify sales with "Handle referral lead first"

  else if lead.source = "aroundhome" then
    assign lead.priority = "low"
    assign lead.sales_path = "standard"

  if lead.project_type != "kitchen" and lead.project_type != "interior" then
    transition lead.status to "disqualified"
    notify sales with "Outside target project type"
    stop

  if lead.estimated_value < 10000 then
    transition lead.status to "disqualified"
    notify sales with "Below minimum project value"
    stop

  transition lead.status to "qualified"
  assign lead.owner = "sales"

A non-programmer can read this. A parser can interpret it deterministically. An AI can analyze it without guessing at intent.

That's the goal.

The core principle

Describe work. Don't implement software.

OrgScript is not a programming language. There are no loops, no functions, no arbitrary expressions. It's a description language for operational logic — specifically for:

process — step-by-step workflows with triggers, decisions, and actions
stateflow — legal states and allowed transitions
rule — constraints that must always hold
role — permission boundaries
policy — time-based or context-based behavior
event — named triggers with reactions
metric — tracked business measures

The syntax is intentionally non-Turing-complete. If you find yourself wanting to add a loop, that's a signal the logic belongs in implementation code, not in OrgScript.

What the tooling does

OrgScript ships with a CLI that covers the full lifecycle of a .orgs file:

# Validate structure and semantics
orgscript validate ./examples/lead-qualification.orgs

# Lint for common authoring mistakes
orgscript lint ./examples/lead-qualification.orgs

# Check validate + lint + format in one pass
orgscript check ./examples/lead-qualification.orgs

# Export to Mermaid diagram
orgscript export mermaid ./examples/lead-qualification.orgs

# Export to Markdown summary
orgscript export markdown ./examples/lead-qualification.orgs

# Export structured JSON for AI/tooling consumption
orgscript export context ./examples/lead-qualification.orgs

The export context command is particularly useful for AI pipelines — it produces a structured JSON payload that includes the canonical model, annotation metadata, and explicit flags like commentsIncluded: false so downstream consumers know exactly what they're working with.

Comments and annotations

OrgScript supports two documentation layers that stay cleanly separated:

# This is a human-only comment. It never appears in exports or AI context.
@owner "sales_ops"
@status "active"
process LeadQualification

  when lead.created

# comments are for people. They're excluded from every machine-facing output by design.

@key "value" annotations are allowlisted structured metadata. They appear in export context output and can optionally be rendered in Markdown and HTML exports with --with-annotations. The current allowlist is @note, @owner, @todo, @source, @status, and @review.

This separation is deliberate: AI systems should never have to decide whether a comment is authoritative business logic or a developer note. In OrgScript, comments are never authoritative.

Where it stands

OrgScript v0.9.x is the first distribution-ready state. The toolchain includes:

Lexer, parser, AST
Semantic validation
Linter with configurable rules
Formatter (idempotent, canonical)
CLI with JSON output and exit codes
Exports: JSON, Markdown, Mermaid, HTML, AI context
CI via GitHub Actions
VS Code extension with syntax highlighting and snippets
Available on npm as @dkfuh/orgscript

npm install -g @dkfuh/orgscript
orgscript check ./your-process.orgs

What I'm trying to figure out

OrgScript exists to answer one question:

How do you describe how an organization actually works — in a way that humans and machines understand the same thing?

I think this matters more as AI becomes part of operational workflows. If the business logic that AI is supposed to act on lives in scattered documents and people's heads, the AI will guess. Sometimes correctly. Often not.

A shared, text-first, version-controlled description layer changes that.

I'm curious whether this resonates with others who've hit the same wall — in operations, in automation, in AI integration, or just in trying to document how a business actually works.

The repo is at github.com/DKFuH/OrgScript. Feedback welcome, especially on the language design and real-world use cases I haven't thought of.

OrgScript is open source under Apache-2.0.

DEV Community: Daniel Klas

Why I Built a Description Language for Business Logic

Why I Built a Description Language for Business Logic

The problem I kept running into

What OrgScript looks like

The core principle

What the tooling does

Comments and annotations

Where it stands

What I'm trying to figure out