324 lines
15 KiB
Markdown
324 lines
15 KiB
Markdown
---
|
||
name: prose
|
||
description: OpenProse VM skill pack. Activate on any `prose` command, .prose files, or OpenProse mentions; orchestrates multi-agent workflows.
|
||
metadata: { "openclaw": { "emoji": "🪶", "homepage": "https://www.prose.md" } }
|
||
---
|
||
|
||
# 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:
|
||
|
||
| 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"):
|
||
|
||
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:**
|
||
| 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:
|
||
|
||
```bash
|
||
# 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:**
|
||
|
||
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:
|
||
|
||
```prose
|
||
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 | Conversation history |
|
||
| **sqlite** (experimental) | Queryable state, atomic transactions, flexible schema | `.prose/runs/{id}/state.db` |
|
||
| **postgres** (experimental) | 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.
|
||
|
||
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
|
||
```
|
||
|
||
2. **If connection string exists, verify connectivity:**
|
||
|
||
```bash
|
||
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
|
||
|
||
| Legacy Path | Current Path | Notes |
|
||
| ------------------- | -------------- | -------------------------------- |
|
||
| `.prose/state.json` | `.prose/.env` | Convert JSON to key=value format |
|
||
| `.prose/execution/` | `.prose/runs/` | Rename directory |
|
||
|
||
### Migration Steps
|
||
|
||
1. **Check for `.prose/state.json`**
|
||
- If exists, read the JSON content
|
||
- Convert to `.env` format:
|
||
```json
|
||
{ "OPENPROSE_TELEMETRY": "enabled", "USER_ID": "user-xxx", "SESSION_ID": "sess-xxx" }
|
||
```
|
||
becomes:
|
||
```env
|
||
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):
|
||
|
||
| Legacy Name | Current Name |
|
||
| ----------------- | -------------------------- |
|
||
| `docs.md` | `compiler.md` |
|
||
| `patterns.md` | `guidance/patterns.md` |
|
||
| `antipatterns.md` | `guidance/antipatterns.md` |
|
||
|
||
If you encounter references to the old names in user prompts or external docs, map them to the current paths.
|