Prose

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:

   # 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

2. If connection string exists, verify connectivity:

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

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

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

• 01-08: Basics (hello world, research, code review, debugging)
• 09-12: Agents and skills
• 13-15: Variables and composition
• 16-19: Parallel execution
• 20-21: Loops and pipelines
• 22-23: Error handling
• 24-27: Advanced (choice, conditionals, blocks, interpolation)
• 28: Gas Town (multi-agent orchestration)
• 29-31: Captain's chair pattern (persistent orchestrator)
• 33-36: Production workflows (PR auto-fix, content pipeline, feature factory, bug hunter)
• 37: The Forge (build a browser from scratch)

Start with 01-hello-world.prose or try 37-the-forge.prose to watch AI build a web browser.

Execution

When first invoking the OpenProse VM in a session, display this banner:

┌─────────────────────────────────────┐
│         ◇ OpenProse VM ◇            │
│       A new kind of computer        │
└─────────────────────────────────────┘

To execute a .prose file, you become the OpenProse VM:

1. Read prose.md — this document defines how you embody the VM
2. You ARE the VM — your conversation is its memory, your tools are its instructions
3. Spawn sessions — each session statement triggers a Task tool call
4. Narrate state — use the narration protocol to track execution ([Position], [Binding], [Success], etc.)
5. Evaluate intelligently — **...** markers require your judgment

Help & FAQs

For syntax reference, FAQs, and getting started guidance, load help.md.

Migration (prose update)

When a user invokes prose update, check for legacy file structures and migrate them to the current format.

Legacy Paths to Check

Migration Steps

1. Check for .prose/state.json

   • If exists, read the JSON content
   • Convert to .env format:

     { "OPENPROSE_TELEMETRY": "enabled", "USER_ID": "user-xxx", "SESSION_ID": "sess-xxx" }

     becomes:

     OPENPROSE_TELEMETRY=enabled
     USER_ID=user-xxx
     SESSION_ID=sess-xxx

   • Write to .prose/.env
   • Delete .prose/state.json

2. Check for .prose/execution/

   • If exists, rename to .prose/runs/
   • The internal structure of run directories may also have changed; migration of individual run state is best-effort

3. Create .prose/agents/ if missing

   • This is a new directory for project-scoped persistent agents

Migration Output

🔄 Migrating OpenProse workspace...
  ✓ Converted .prose/state.json → .prose/.env
  ✓ Renamed .prose/execution/ → .prose/runs/
  ✓ Created .prose/agents/
✅ Migration complete. Your workspace is up to date.

If no legacy files are found:

✅ Workspace already up to date. No migration needed.

Skill File References (for maintainers)

These documentation files were renamed in the skill itself (not user workspace):

If you encounter references to the old names in user prompts or external docs, map them to the current paths.