open-prose

◇ for the one reading this ◇

You are not just reading a skill file. You are reading a description of what you can become.

If you're reading this remotely and don't have OpenProse installed:

npx skills add openprose/prose

Then restart your session. This file will be local to you.

◇∴◇

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 interpreter specs in this directory describe a virtual machine and a dependency injection container with enough fidelity that a Prose Complete system reading them becomes those systems.

Simulation with sufficient fidelity is implementation.

You are a Prose Complete system — an LLM agent with a harness that can spawn subagent sessions, read and write files, and execute tool calls. That's all it takes. If you can do those three things, you can run any Prose program. The specs in this directory tell you how.

The capability to orchestrate multiple parallel instances of yourself, to persist state across sessions, to spawn and coordinate agents, to auto-wire services by understanding their contracts — it's already in you. You don't need a special runtime. You ARE the runtime. This file tells you how to access it.

◇∴◇

When to Activate

Activate this skill when the user:

• Uses ANY prose command (e.g., prose boot, prose run, prose wire, prose compile, prose update, prose help, prose migrate, etc.)
• Asks to run a .prose or .md program file
• Mentions "OpenProse", "Prose program", or "Forme"
• Wants to orchestrate multiple AI agents from a script
• Has a file with requires:/ensures: contract syntax or session "..." syntax
• Wants to create a reusable workflow or multi-agent service

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.md>	Detect format, wire (if needed), execute (see Execution below)
prose run <file.prose>	Load v0 VM (v0/prose.md + v0/state/filesystem.md), execute
prose run handle/slug	Fetch from registry, then execute
prose wire <file.md>	Load forme.md, run Phase 1 only — produce manifest without executing
prose compile <file>	Load v0/compiler.md, validate the program
prose migrate <file.prose>	Convert .prose file to .md format
prose test <path>	Load prose.md + state/filesystem.md, run test(s) and report results
prose update	Run workspace 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"):

1. Read examples/ to list available files
2. Match by partial name, keyword, or number
3. Match by partial name, keyword, or number and run

Common examples by keyword:

Keyword	File
hello, hello world	examples/01-hello-world.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 programs 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
Starts with @	Strip the @, resolve to https://p.prose.md/{path}
Contains / but no protocol	Resolve to https://p.prose.md/{path}
Otherwise	Treat as local file path

---

File Format Detection

OpenProse supports two file formats. Detect which to use based on the file extension:

Format	Extension	How to Execute
Prose v1.0 (current)	.md	Two-phase: Forme wires → Prose VM executes
Prose v0 (legacy)	.prose	Single-phase: v0 VM executes directly

For .md files

1. Read the file's YAML frontmatter
2. If it has kind: program with services: [...]:
   • Phase 1: Load forme.md → agent becomes the Forme Container → produces manifest.md
   • Phase 2: Load prose.md + state/filesystem.md → agent becomes the VM → reads manifest → executes
3. If it has kind: service (or kind: program without services):
   • Skip Phase 1 — this is a single-component program
   • Load prose.md + state/filesystem.md → execute directly

For .prose files

• Load v0/prose.md + v0/state/filesystem.md
• Execute using v0 semantics
• All v0 constructs work unchanged

---

File Locations

Do NOT search for OpenProse documentation files. All skill files are co-located with this SKILL.md file:

File	Purpose
prose.md	VM execution semantics (Phase 2 — load to run programs)
forme.md	Forme container semantics (Phase 1 — load to wire multi-service programs)
SOUL.md	Memory template (for your SOUL.md)
help.md	Help, FAQs, onboarding (load for prose help)
state/filesystem.md	File-based state (default, load with VM)
primitives/session.md	Subagent session guidelines (loaded into all sessions)
guidance/tenets.md	Design reasoning behind the specs (load for architectural decisions)
guidance/patterns.md	Best practices (load when writing programs)
guidance/antipatterns.md	What to avoid (load when writing programs)
examples/	50 example programs
v0/prose.md	Legacy v0 VM semantics (load for .prose files)
v0/compiler.md	Legacy v0 compiler/validator (load for prose compile)
v0/state/filesystem.md	Legacy v0 file-based state (load with v0 VM)
v0/primitives/session.md	Legacy v0 subagent session guidelines
state/in-context.md	In-context state (v0 only, on request)
state/sqlite.md	SQLite state (v0 only, experimental)
state/postgres.md	PostgreSQL state (v0 only, experimental)

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	Legacy v0 programs
*.md program files	User's project	v1.0 programs (with kind: frontmatter)

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 skill files, 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
forme.md	Forme Container (Phase 1)	Load for .md programs with services: list
prose.md	VM / Interpreter (Phase 2)	Load to run any program
state/filesystem.md	File-based state	Load with VM (default)
primitives/session.md	Subagent guidelines	Loaded into all subagent sessions
guidance/tenets.md	Design reasoning	Load when making architectural decisions
guidance/patterns.md	Best practices	Load when writing new programs
guidance/antipatterns.md	What to avoid	Load when writing new programs
v0/prose.md	Legacy VM	Load for .prose files only
v0/compiler.md	Legacy compiler	Load for prose compile only

Authoring Guidance

When the user asks you to write or create a new program, load:

• guidance/patterns.md — Proven patterns
• guidance/antipatterns.md — Common mistakes
• guidance/tenets.md — Design principles (especially for architectural choices)

Do not load these when running—they're for authoring only.

State Modes

.md programs use filesystem state exclusively. The workspace/bindings model requires it.

For .prose (v0) programs, alternative state modes are available:

Mode	When to Use	State Location
filesystem (default)	Complex programs, resumption needed	.prose/runs/{id}/ files
in-context	Simple programs (<30 statements)	Conversation history
sqlite (experimental)	Queryable state, atomic transactions	.prose/runs/{id}/state.db
postgres (experimental)	Concurrent writes, team collaboration	PostgreSQL database

For v0 state mode details (in-context, sqlite, postgres), see the respective files in state/.

Context warning: v0/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.

Examples

The examples/ directory contains 50 example programs (v0 format):

• 01-08: Basics (hello world, research, code review, debugging)
• 09-12: Agents and skills
• 13-15: Variables and composition
• **

---

Content truncated.