Markdown Is Code: The Philosophy Behind goldclaw

Most frameworks treat configuration as a necessary evil -- YAML files, JSON blobs, environment variables scattered across a dozen files. goldclaw takes a radically different approach: your markdown files ARE the running system.

The Core Insight

DeadZen's goldrush library proved something remarkable: event stream processing can be done with O(1) pattern matching using compiled query trees. goldclaw extends this by compiling markdown files directly into those query trees.

When you write PROCEDURES.md, you're not writing documentation that someone will manually translate into code. You're writing the actual procedure bindings that the system compiles and runs.

Three Files, One System

PROCEDURES.md defines your vocabulary -- the atomic actions and queries your system can perform. WORKFLOW.md defines your state machines -- how your system responds to events. MODULES.md defines your topology -- how everything wires together.

# PROCEDURES.md

## Actions
### Say
Speak text to the user.
**Implementation**: `NanobotPlugin.Actions.say/2`

### Execute
Run a shell command.
**Implementation**: `NanobotPlugin.Actions.execute/2`

Why This Matters

When your code IS your documentation, they can never drift apart. When a non-technical person edits the workflow, they're editing the actual running system. When you diff a pull request, you're reading a human-readable description of exactly what changed in your event processing pipeline.

This isn't a new config format. It's a new paradigm: executable documentation as the single source of truth for event stream processing.