nclamvn/openclawvn/prose

OpenProse Skill

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.

OpenClaw Runtime Mapping

• Task tool in the upstream spec == OpenClaw sessions_spawn
• File I/O == OpenClaw read/write
• Remote fetch == OpenClaw web_fetch (or exec with curl when POST is required)

When to Activate

Activate this skill when the user:

• Uses ANY `prose` command (e.g., prose boot, prose run, prose compile, prose update, prose help, etc.)
• Asks to run a .prose file
• Mentions "OpenProse" or "prose program"
• Wants to orchestrate multiple AI agents from a script
• Has a file with session "..." or agent name: syntax
• Wants to create a reusable workflow

Command Routing

When a user invokes prose <command>, intelligently route based on intent:

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"):

1. Read examples/ to list available files
2. Match by partial name, keyword, or number
3. Run with: prose run examples/28-gas-town.prose

Common examples by keyword:

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:

Steps for remote programs:

1. Apply resolution rules above
2. Fetch the .prose content
3. 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:

User workspace files (these ARE in the user's project):

User-level files (in user's home directory, shared across all projects):

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

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:

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.

1. Check for connection configuration first:

``bash # Check .prose/.env for OPENPROSE_POSTGRES_URL cat .prose/.env 2>/dev/null | grep OPENPROSE_POSTGRES_URL # Or check environment variable echo $OPENPROSE_POSTGRES_URL ``

1. If connection string exists, verify connectivity:

``bash psql "$OPENPROSE_POSTGRES_URL" -c "SELECT 1" 2>&1 ``

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. ```

1. 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: