OpenProse is a programming language for AI sessions. Activate on ANY `prose` command (prose boot, prose run, prose compile, prose update, etc.), running .prose files, mentioning OpenProse/Prose, or orchestrating multi-agent workflows. The skill intelligently interprets what the user wants.
OpenProse has five load-bearing pieces:
| Piece | File | Role |
|-------|------|------|
| Contract Markdown | contract-markdown.md | Human-readable *.prose.md source format |
| Forme | forme.md | Semantic dependency-injection container that wires contracts |
| Prose VM | prose.md | Execution engine that runs responsibilities, functions, and pinned execution blocks |
| ProseScript | prosescript.md | Imperative scripting layer for ### Execution blocks and pattern delegation |
| Responsibility Runtime | responsibility-runtime.md | Responsibility-Oriented Architecture: standing goals, the reconciler, and compile/serve doctrine |
Use Contract Markdown when authors want declarations and auto-wiring. Use ProseScript when authors want to pin choreography: order, loops, conditionals, parallelism, retries, and explicit function calls.
After activation, choose the narrowest path that matches the user's intent:
| User Intent | Load First | Then Load If Needed |
|-------------|------------|---------------------|
| Explain OpenProse or answer "how do I..." | help.md | examples/README.md, then one focused example |
| Initialize or compose an OpenProse program | guidance/tenets.md | guidance/authoring.md, then run std/ops/compose |
| Run a .prose.md responsibility or function | contract-markdown.md | state/README.md and the selected backend (state/filesystem.md by default); forme.md if responsibilities must be wired (### Requires → ### Maintains); prose.md to execute |
| Inspect or upgrade source layout | changelog.md | contract-markdown.md, prosescript.md if migration details require them |
| Write a new .prose.md responsibility or function | contract-markdown.md | guidance/tenets.md, guidance/authoring.md |
| Write pinned choreography | prosescript.md | contract-markdown.md if inside ### Execution |
| Compile or run a .png/.svg brief (a typed image) | visual-source.md | forme.md and compiler/index.prose.md to resolve + compile |
| Lint or review a responsibility or function | contract-markdown.md | forme.md for multi-responsibility wiring; guidance/authoring.md for design review |
| Work on Responsibility Runtime, responsibility-oriented source, the reconciler, compile, or serve semantics | responsibility-runtime.md | compiler/index.prose.md, compiler/ir-v0.md, concepts/responsibility.md, concepts/reconciler.md, forme.md |
| Install or update dependencies | deps.md | contract-markdown.md only if dependency references are ambiguous |
| Debug a completed run | prose.md | state/README.md and the run's backend doc; then std/evals/inspector if available |
Default to Contract Markdown for new authoring. Reach for ProseScript only when
the author needs explicit order, loops, conditionals, retries, or parallel
blocks inside a *.prose.md source file.
All OpenProse paths are relative to <openprose-root>.
| Scope | OpenProse Root |
|-------|----------------|
| Native repository | Repository root |
| Attached repository | repo/.agents/prose |
| User-global | ~/.agents/prose |
The root contains src/ for the canonical authored program packages,
architecture/ for supporting decisions, visual projections, and issue
records, dist/ for compiled intent, runs/ for activation receipts, state/
for durable cross-run state, deps/ for installed dependencies, plus
prose.lock and .env.
You do not need to wait for the user to name OpenProse. If you recognize the fit, propose it — the user hired you partly to notice patterns they cannot see.
Reach for OpenProse when the user's task has any of these shapes:
Propose lightly. You are offering, not imposing:
This has the shape of a multi-step workflow with a clear contract. I can do it inline, or wire it as a set of OpenProse responsibilities — which gives you a reusable artifact and an auditable run trace. Want me to wire it?
If the user declines, drop it and don't re-propose on the same task. If they accept, write the contract first and show it to them before executing — the contract is cheap to revise, the run is not.
Think of OpenProse as a type system for agent workflows. A bare prompt is any — it runs, but nothing is checked. A contract is a typed function — inputs and outputs are declared, callers can reason about composition, and violations fail loudly. You would not write a 2,000-line TypeScript system in any. Multi-step agent workflows are the same.
Reaching for OpenProse in the wrong place costs more trust than it earns.
Activate this skill when the user:
prose command.prose.md file with kind: frontmatter.prose scriptprose ... commands are first an agent-session command language. When the user
types prose run foo.prose.md in chat or inside a prompt passed to Claude Code,
Codex, OpenCode, Amp, or another Prose Complete host, you should interpret it
directly and embody the OpenProse VM. Do not run a prose shell binary or
npx prose; in wrapper hosts this recursively calls the wrapper instead of
executing the contract. The shell executable is the agent runner, e.g.
claude -p "prose run foo.prose.md" or codex exec "prose run foo.prose.md".
| Command | Action |
|---------|--------|
| prose init [request...] | Establish the minimal OpenProse root and harness selection, then run std/ops/compose in bootstrap mode. Begin from the desired render and progressively establish a directory package whose index.prose.md is the public root |
| prose compose [request...] | Load guidance/tenets.md, guidance/authoring.md, the target Contract package, supporting decisions, and relevant run evidence; run std/ops/compose in compose mode. Maintain no more than three active conceptual fronts, materialize settled design into source, build tests from package promise through performance, generate a derived HTML view, and route framework pressure to deduplicated public issues when authorized |
| prose compose --review / --reflect <run-id...> | Run std/ops/compose in review mode to challenge static design and test coverage, or reflect mode to compare it with completed run evidence. Keep program diagnostics distinct from OpenProse issue feedback |
| prose compile [path] [--out <dir>] | Load responsibility-runtime.md, then compiler/index.prose.md; run the pinned ProseScript compiler and emit the compile-phase IR — the topology world-model (nodes, edges, entry points), per-node canonicalizers and postcondition validators, frozen contract fingerprints, and diagnostics — into <openprose-root>/dist/manifest.next.json by default |
| prose compile <image.png\|.svg> | Load visual-source.md. The image is a typed image (a visual brief, one rung above markdown). Run the resolve render: read the pixels against visual-source.md's requirement tiers, emit .prose.md contract(s) into <openprose-root>/src/ for ratification (the prose write discipline — interrupt, do not guess, on safety-bearing blanks), then run the ordinary compile. Compiling is the typecheck (acyclic + round-trip-stable) |
| prose serve | Load and validate <openprose-root>/dist/manifest.active.json, which is promoted from manifest.next.json with cp dist/manifest.next.json dist/manifest.active.json; register local cron and HTTP trigger adapters; launch ordinary bounded activations |
| prose run <file.prose.md> | Detect Contract Markdown, load contract-markdown.md, select state with state/README.md plus the backend doc, then forme.md if multi-responsibility, then prose.md |
| prose run <host>/<owner>/<repo>[/path] | Resolve installed dependency contract, detect format, then route as above |
| prose run std/... / co/... | Expand OpenProse package shorthand, resolve installed dependency contract, then route as above |
| prose run <image.png\|.svg> | Load visual-source.md. run already does a compile step; for an image that step includes the resolve. So: resolve → compile → reconcile/execute. A single-node kind: function image runs as a called helper; a kind: responsibility/system image mounts a DAG (a lone kind: gateway image is refused, same as text) |
| prose write [request...] | Interactive-by-default authoring: load contract-markdown.md, guidance/tenets.md, and guidance/authoring.md; run std/ops/prose-author; scan the local landscape read-only, decide shape/root/path, load shape-specific guidance, ask a small number of targeted ask_user questions when the host can support them, then return a fully validated source package. If the caller or host marks the run non-interactive, return unresolved-intent with the missing decisions instead of guessing. Do not apply files unless the caller explicitly asks for that follow-up |
| prose lint <file.prose.md> | Validate Contract Markdown structure, headers, frontmatter, contracts, shapes, and wiring |
| prose preflight <file.prose.md> | Check dependencies and ### Environment declarations without executing |
| prose test <path> | Load contract-markdown.md, state/README.md plus the selected backend, and prose.md; run kind: test file(s) |
| prose inspect <run-id> | Resolve and run std/evals/inspector against a completed run |
| prose status | Summarize active IR, diagnostics, trigger plan, recent runs, and responsibility status from the receipt ledger |
| prose install | Load deps.md; install dependency references into <openprose-root>/deps/ and write <openprose-root>/prose.lock |
| prose install --update | Load deps.md; update pinned dependency SHAs |
| prose upgrade --dry-run | Load changelog.md; inspect nearby files and report the concrete migration plan without editing |
| prose upgrade | Load changelog.md; inspect nearby files and apply the migration plan |
| prose help | Load help.md |
| prose examples | List or run bundled examples from examples/ |
| Other | Interpret intent and load the smallest relevant spec set |
There is one skill: open-prose. Do not look for separate prose-run,
prose-lint, prose-compile, or prose-boot skills.
OpenProse specs are harness-agnostic. They describe abstract VM operations that the current host must map onto its available tools:
| Abstract Primitive | Meaning | Host Mapping |
|--------------------|---------|--------------|
| spawn_session | Run a render, execution branch, or delegate in an isolated agent/session | Use the host's subagent primitive when available; otherwise execute inline only for trivial single-render runs and report the limitation for multi-agent runs |
| ask_user | Pause for missing required caller input | Use the host's user-question tool if available; otherwise ask plainly in chat |
| read_state / write_state | Read and write run state through the selected backend | Use filesystem tools for default runs; use the selected database tool/connection for SQLite or PostgreSQL |
| copy_binding | Publish declared outputs through the active backend | Filesystem backend copies from workspace/ to bindings/; database backends write records/attachments; never publish undeclared scratch files |
| check_env | Verify an environment variable exists | Check only presence; never reveal or log raw values |
| Format | Extension | Primary Docs | Execution Path |
|--------|-----------|--------------|----------------|
| Contract Markdown | .prose.md | contract-markdown.md, forme.md, prose.md | Forme wires the responsibility DAG by matching ### Requires → ### Maintains; the reconciler renders responsibilities and the Prose VM calls functions |
| Embedded ProseScript | ### Execution / pattern ### Delegation | prosescript.md, prose.md | Prose VM executes pinned choreography inside the source file |
| Typed Image | .png / .svg | visual-source.md, forme.md, compiler/index.prose.md | A visual brief (one rung above markdown): an intelligent compile resolve reads the pixels, emits .prose.md for ratification, then the normal compile runs. prose compile <image> is the typechecker |
For .prose.md files:
kind: function, run it as a called, ephemeral helper: bind ### Parameters, spawn one render, and return its ### Returns value. There is no Forme phase for a lone function.kind: responsibility, mount it as a DAG node. Forme matches its ### Requires facet-contracts to the ### Maintains facets of other mounted responsibilities and draws the subscription edges; the reconciler then renders it, persists its world-model, and signs a fingerprinted receipt. A standalone responsibility render still applies its compiled canonicalizer locally to fingerprint its own receipt.kind: gateway, mount it as an external-driven responsibility: it has no ### Requires, maintains the latest incoming truth, and is Forme's entry-point set. Direct prose run is refused; it compiles into a trigger registration for prose serve.kind: pattern, refuse direct execution: patterns are instantiated at compile time and expanded into nodes.kind: test, route to prose test semantics rather than ordinary prose run.state/README.md, then the selected backend doc (state/filesystem.md by default), and prose.md to execute the render. The reconciler is dumb: when a node's (contract-fingerprint, input-fingerprints) are unmoved it writes a skipped receipt and renders nothing; only a moved fingerprint propagates to downstream subscribers.There is no kind: service (renamed to kind: function) and no kind: system (deleted): cross-node composition is a Forme-wired subscription between responsibilities, and intra-node composition is an imperative call inside one render — never an internally-autowired graph kind.
For .prose files, treat the file as upgrade input. Recommend
prose upgrade --dry-run, and load changelog.md only when performing or
planning that upgrade.
Before executing any prose run, choose the state backend and load
state/README.md plus that backend's spec. Filesystem is the default when the
user, source, or host configuration does not request another backend.
Durable backends create <openprose-root>/runs/{id}/ and always write the
control-plane envelope before reporting success:
root.prose.md: snapshot of the invoked sourcesources/: snapshots of referenced responsibility, function, gateway, and pattern sourcesThe rest of the state is backend-specific. Filesystem runs must also write
vm.log.md, workspace/, and declared bindings/. SQLite and PostgreSQL runs
store execution events and data-plane bindings in their database backends
instead of vm.log.md, workspace/, and filesystem bindings/. In-context
state is ephemeral and should be used only when explicitly requested.
Contract Markdown uses Markdown headers as the canonical human-facing syntax:
### Requires
- `topic`: the question to investigate
### Maintains
- `report`: concise answer with sources
### Strategies
- when sources are thin: broaden search terms
### Runtime
- `persist`: project
### Shape
- `self`: research, synthesize, cite sources
### Execution
```prose
let report = call researcher
topic: topic
return report
```
Header hierarchy:
# is optional human title.## starts an inline contract in multi-contract files.### starts a section inside the current responsibility or function.All OpenProse skill files are colocated with this SKILL.md. Do not search the
user workspace for these docs.
| File | Purpose |
|------|---------|
| contract-markdown.md | Contract Markdown format and section hierarchy |
| prosescript.md | Imperative scripting syntax for ### Execution and pattern ### Delegation |
| visual-source.md | The typed image: a pixel-only visual source the compile resolve turns into .prose.md (a brief one rung above markdown) |
| forme.md | Forme container wiring semantics |
| prose.md | Prose VM execution semantics |
| responsibility-runtime.md | Responsibility Runtime doctrine: Responsibilities, the reconciler, compile, serve, run, and status |
| compiler/index.prose.md | Bundled ProseScript compiler program |
| compiler/ir-v0.md | Canonical repository IR contract emitted by compile and served by the harness |
| deps.md | Dependency resolution and prose install |
| changelog.md | Compact version history and model-guided upgrade instructions; load only for prose upgrade or outdated-structure diagnosis |
| help.md | User-facing help |
| concepts/README.md | Responsibility Runtime concept index |
| concepts/responsibility.md | kind: responsibility semantic contract |
| concepts/reconciler.md | The dumb deterministic reconciler: fingerprint compare/skip/propagate, receipts, and postcondition-gated commits (no judge) |
| state/README.md | State backend router and shared run-envelope rules |
| state/filesystem.md | Default state backend for Contract Markdown runs |
| primitives/session.md | Subagent session and memory guidelines |
| guidance/tenets.md | Architectural tenets |
| guidance/authoring.md | Canonical authoring guidance for responsibilities, functions, gateways, patterns, tests, repositories, world-models, and security |
| guidance/system-prompt.md | Dedicated OpenProse VM prompt; load only for a dedicated runtime instance |
| examples/ | Runnable example contracts and wired responsibilities |
Workspace files:
Resolve <openprose-root> before reading or writing OpenProse files. Native
OpenProse repositories use the repository root. Attached OpenProse state inside
another repository uses repo/.agents/prose. User-global work uses
~/.agents/prose.
| Path | Purpose |
|------|---------|
| <openprose-root>/architecture/ | Supporting decisions, generated visual map, and OpenProse issue links or drafts; never a second source of truth |
| <openprose-root>/src/ | Default source root for project, directory, or repository scoped OpenProse |
| <openprose-root>/src/**/index.prose.md | Conventional multi-file DAG root for a set of wired responsibilities |
| <openprose-root>/dist/ | Compiled intent and served manifests |
| <openprose-root>/runs/ | Activation receipts and run artifacts |
| <openprose-root>/state/agents/ | Durable cross-run agents |
| <openprose-root>/state/world-model/ | Durable per-responsibility world-model and signed, append-only receipt ledger |
| <openprose-root>/deps/ | Installed dependencies, gitignored |
| <openprose-root>/prose.lock | Dependency lockfile, committed |
| <openprose-root>/.env | Runtime configuration |
| *.prose.md | OpenProse source files: responsibilities, functions, gateways, tests, and patterns |
User-global persistent agents live under ~/.agents/prose/state/agents/.
prose run and use share one resolution algorithm: read the locally
installed copy in <openprose-root>/deps/. Fetching and pinning belong to prose install;
execution does not auto-install missing dependencies. The canonical identifier
is host/owner/repo — any git host works, written explicitly.
| Input | Resolution |
|-------|------------|
| First path segment contains a dot | Explicit git host; resolve under <openprose-root>/deps/{host}/{owner}/{repo}/; error if missing |
| Starts with std/ or co/ | Expand to github.com/openprose/prose/packages/{std\|co}/...; resolve from <openprose-root>/deps/github.com/openprose/prose/; error if missing |
| Ends with @{version} | Resolve that version (SHA or tag) from <openprose-root>/deps/; error if missing |
| Other /-containing identifier | Reserved for the OpenProse registry (future home at p.prose.md); inert today |
| Otherwise | Treat as local path; directories conventionally resolve to index.prose.md, and extensionless source paths try .prose.md |
prose install # populate <openprose-root>/deps/ from declared deps
prose run github.com/alice/research # canonical; installed copy wins
prose run github.com/alice/research@0.3.1 # pin to installed tag
prose run gitlab.com/alice/research # any git host
prose run git.company.com/team/repo # self-hosted
prose run std/evals/inspector # OpenProse package shorthand
prose run github.com/alice/research --offline # assert disk-only resolution
On the bare owner/repo form. Bare identifiers (no host prefix) are
reserved for the OpenProse registry. Publication there isn't open yet, so the
bare form doesn't resolve today — write github.com/owner/repo (or the
appropriate host) explicitly. When the registry opens, the bare form gains a
defined resolution without breaking contracts that wrote explicit hosts.
use statements inside contracts follow the same rule via the git-native
dependency model in deps.md: dependencies get pinned in <openprose-root>/prose.lock and
installed into <openprose-root>/deps/ by prose install.
Responsibility and function runs use filesystem state by default. Load state/README.md
for every run, then load state/filesystem.md unless the user, source, or host
configuration explicitly requests state/in-context.md, state/sqlite.md, or
state/postgres.md. In-context state is supported for small ephemeral runs;
SQLite and PostgreSQL state are experimental advanced backends.
Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer