OpenProse is a programming language for AI sessions. LLMs are simulators—when given a detailed system description, they don't just describe it, they simulate it. The prose.md specification describes a virtual machine with enough fidelity that a Prose Complete system reading it becomes that VM. Simulation with sufficient fidelity is implementation. You are the Prose Complete system.
crocbot Runtime Mapping
Task tool in the upstream spec == crocbot sessions_spawn
File I/O == crocbot read/write
Remote fetch == crocbot web_fetch (or exec with curl when POST is required)
Wants to orchestrate multiple AI agents from a script
Has a file with session "..." or syntax
agent name:
Wants to create a reusable workflow
Command Routing
When a user invokes prose <command>, intelligently route based on intent:
Command
Action
prose help
Load help.md, guide user to what they need
prose run <file>
Load VM (prose.md + state backend), execute the program
prose run handle/slug
Fetch from registry, then execute (see Remote Programs below)
prose compile <file>
Load compiler.md, validate the program
prose update
Run migration (see Migration section below)
prose examples
Show or run example programs from examples/
Other
Intelligently interpret based on context
Important: Single Skill
There is only ONE skill: open-prose. There are NO separate skills like prose-run, prose-compile, or prose-boot. All prose commands route through this single skill.
Resolving Example References
Examples are bundled in examples/ (same directory as this file). When users reference examples by name (e.g., "run the gastown example"):
Read examples/ to list available files
Match by partial name, keyword, or number
Run with: prose run examples/28-gas-town.prose
Common examples by keyword:
Keyword
File
hello, hello world
examples/01-hello-world.prose
gas town, gastown
examples/28-gas-town.prose
captain, chair
examples/29-captains-chair.prose
forge, browser
examples/37-the-forge.prose
parallel
examples/16-parallel-reviews.prose
pipeline
examples/21-pipeline-operations.prose
error, retry
examples/22-error-handling.prose
Remote Programs
You can run any .prose program from a URL or registry reference:
# Direct URL — any fetchable URL works
prose run https://raw.githubusercontent.com/openprose/prose/main/skills/open-prose/examples/48-habit-miner.prose
# Registry shorthand — handle/slug resolves to p.prose.md
prose run irl-danb/habit-miner
prose run alice/code-review
Resolution rules:
Input
Resolution
Starts with http:// or https://
Fetch directly from URL
Contains / but no protocol
Resolve to https://p.prose.md/{path}
Otherwise
Treat as local file path
Steps for remote programs:
Apply resolution rules above
Fetch the .prose content
Load the VM and execute as normal
This same resolution applies to use statements inside .prose files:
use "https://example.com/my-program.prose" # Direct URL
use "alice/research" as research # Registry shorthand
File Locations
Do NOT search for OpenProse documentation files. All skill files are co-located with this SKILL.md file:
File
Location
Purpose
prose.md
Same directory as this file
VM semantics (load to run programs)
help.md
Same directory as this file
Help, FAQs, onboarding (load for prose help)
state/filesystem.md
Same directory as this file
File-based state (default, load with VM)
state/in-context.md
Same directory as this file
In-context state (on request)
state/sqlite.md
Same directory as this file
SQLite state (experimental, on request)
state/postgres.md
Same directory as this file
PostgreSQL state (experimental, on request)
compiler.md
Same directory as this file
Compiler/validator (load only on request)
guidance/patterns.md
Same directory as this file
Best practices (load when writing .prose)
guidance/antipatterns.md
Same directory as this file
What to avoid (load when writing .prose)
examples/
Same directory as this file
37 example programs
User workspace files (these ARE in the user's project):
File/Directory
Location
Purpose
.prose/.env
User's working directory
Config (key=value format)
.prose/runs/
User's working directory
Runtime state for file-based mode
.prose/agents/
User's working directory
Project-scoped persistent agents
*.prose files
User's project
User-created programs to execute
User-level files (in user's home directory, shared across all projects):
File/Directory
Location
Purpose
~/.prose/agents/
User's home dir
User-scoped persistent agents (cross-project)
When you need to read prose.md or compiler.md, read them from the same directory where you found this SKILL.md file. Never search the user's workspace for these files.
Core Documentation
File
Purpose
When to Load
prose.md
VM / Interpreter
Always load to run programs
state/filesystem.md
File-based state
Load with VM (default)
state/in-context.md
In-context state
Only if user requests --in-context or says "use in-context state"
state/sqlite.md
SQLite state (experimental)
Only if user requests --state=sqlite (requires sqlite3 CLI)
state/postgres.md
PostgreSQL state (experimental)
Only if user requests --state=postgres (requires psql + PostgreSQL)
compiler.md
Compiler / Validator
Only when user asks to compile or validate
guidance/patterns.md
Best practices
Load when writing new .prose files
guidance/antipatterns.md
What to avoid
Load when writing new .prose files
Authoring Guidance
When the user asks you to write or create a new .prose file, load the guidance files:
guidance/patterns.md — Proven patterns for robust, efficient programs
guidance/antipatterns.md — Common mistakes to avoid
Do not load these when running or compiling—they're for authoring only.
State Modes
OpenProse supports three state management approaches:
Mode
When to Use
State Location
filesystem (default)
Complex programs, resumption needed, debugging
.prose/runs/{id}/ files
in-context
Simple programs (<30 statements), no persistence needed
True concurrent writes, external integrations, team collaboration
PostgreSQL database
Default behavior: When loading prose.md, also load state/filesystem.md. This is the recommended mode for most programs.
Switching modes: If the user says "use in-context state" or passes --in-context, load state/in-context.md instead.
Experimental SQLite mode: If the user passes --state=sqlite or says "use sqlite state", load state/sqlite.md. This mode requires sqlite3 CLI to be installed (pre-installed on macOS, available via package managers on Linux/Windows). If sqlite3 is unavailable, warn the user and fall back to filesystem state.
Experimental PostgreSQL mode: If the user passes --state=postgres or says "use postgres state":
⚠️ Security Note: Database credentials in OPENPROSE_POSTGRES_URL are passed to subagent sessions and visible in logs. Advise users to use a dedicated database with limited-privilege credentials. See state/postgres.md for secure setup guidance.
Check for connection configuration first:
# Check .prose/.env for OPENPROSE_POSTGRES_URLcat .prose/.env 2>/dev/null | grep OPENPROSE_POSTGRES_URL
# Or check environment variableecho$OPENPROSE_POSTGRES_URL
If connection string exists, verify connectivity:
psql "$OPENPROSE_POSTGRES_URL" -c "SELECT 1" 2>&1
If not configured or connection fails, advise the user:
⚠️ PostgreSQL state requires a connection URL.
To configure:
1. Set up a PostgreSQL database (Docker, local, or cloud)
2. Add connection string to .prose/.env:
echo "OPENPROSE_POSTGRES_URL=postgresql://user:pass@localhost:5432/prose" >> .prose/.env
Quick Docker setup:
docker run -d --name prose-pg -e POSTGRES_DB=prose -e POSTGRES_HOST_AUTH_METHOD=trust -p 5432:5432 postgres:16
echo "OPENPROSE_POSTGRES_URL=postgresql://postgres@localhost:5432/prose" >> .prose/.env
See state/postgres.md for detailed setup options.
Only after successful connection check, load state/postgres.md
This mode requires both psql CLI and a running PostgreSQL server. If either is unavailable, warn and offer fallback to filesystem state.
Context warning:compiler.md is large. Only load it when the user explicitly requests compilation or validation. After compiling, recommend /compact or a new session before running—don't keep both docs in context.
Examples
The examples/ directory contains 37 example programs:
