open-prose

# OpenProse Skill 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, Reactor, 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. ## First 90 Seconds 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 | | 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; `reactor.md` for `prose react <image>` | | 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, Reactor, compile, or serve semantics | `responsibility-runtime.md` | `compiler/index.prose.md`, `compiler/ir-v0.md`, `concepts/responsibility.md`, `concepts/reactor.md`, `forme.md` | | Stand up, run, or serve a Reactor for a standing goal — incl. `prose react "<use case>"` | `reactor.md` | `concepts/responsibility.md` and `contract-markdown.md` to author the contracts; `concepts/reactor.md` for reconciler semantics | | 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. ## OpenProse Root 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 authored intent, `dist/` for compiled intent, `runs/` for activation receipts, `state/` for durable cross-run state, `deps/` for installed dependencies, plus `prose.lock` and `.env`. ## Proposing This Skill On Your Own Judgment 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. ### Recognition signals Reach for OpenProse when the user's task has any of these shapes: - **≥3 steps that want different expertise** (research + synthesize + review; plan + implement + test) - **A reuse signal** — "every week," "each time a PR comes in," "before every release" - **A natural retry loop** — draft/critique/revise, implement/test/fix, propose/evaluate/pick - **Parallel exploration with a synthesis step** — "compare three approaches," "get second opinions" - **A "make sure X always happens" constraint** — that's a contract asking to be written down - **You were already going to spawn subagents** — let the contract be your wiring plan instead of inventing one ad-hoc ### How to propose it 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. ### A cognitive model you can borrow 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. ### When OpenProse is the wrong answer - **One-shot Q&A.** Answer it directly. - **Tasks where the user wants to iterate in real time.** A contract boundary adds friction they don't want. - **Anything you'd finish in one response.** The overhead of writing a contract exceeds the value of having one. - **Tasks where the user explicitly said "just do it."** Respect the directive. Reaching for OpenProse in the wrong place costs more trust than it earns. ## Activation Activate this skill when the user: - uses any `prose` command - asks to run, lint, test, inspect, upgrade, or write an OpenProse responsibility or function - references a `.prose.md` file with `kind:` frontmatter - references a `.prose` script - mentions OpenProse, Forme, Reactor, Responsibilities, ProseScript, Contract Markdown, or a Prose responsibility or function - wants reusable multi-agent orchestration ## Command Routing `prose ...` 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"`. The one exception is the **`reactor` binary** (`@openprose/reactor-cli`), driven by `prose react`. It is a genuine deterministic host — a dumb reconciler that never calls an agent wrapper — so you *do* install and shell out to it. You author the `*.prose.md` contracts; the binary runs them. See `reactor.md`. | Command | Action | |---------|--------| | `prose compile [path] [--out <dir>]` | Load `responsibility-runtime.md`, then `compiler/index.prose.md`; run the pinned ProseScript compiler and emit concrete trigger registrations, activations, and Forme manifests 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`; register local cron and HTTP trigger adapters; launch ordinary bounded activations | | `prose react [use case...] [--start]` | Load `reactor.md`. Take an English standing goal to a running, inspectable Reactor on the real `reactor` binary: pick a home, ensure the harness, author the `kind: responsibility`/`gateway` contracts (per `concepts/responsibility.md` + `contract-markdown.md`) and `reactor.yml`, then `compile → serve` and show the user `reactor-devtools` replay. **Default prints the `reactor` commands for the user to run; `--start` drives the live lifecycle directly.** Unlike embodied `prose run`, the `reactor` binary is a real deterministic host you *do* shell out to. A **typed image** brief (`prose react <image.png\|.svg>`) is the visual peer of the English goal — also load `visual-source.md` and resolve the pixels to contracts first | | `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. ## Host Primitive Adapter 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 Detection | 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 `call`s 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: 1. Read YAML frontmatter. 2. If the file has `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. 3. If the file has `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. 4. If the file has `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`. 5. If the file has `kind: pattern`, refuse direct execution: patterns are instantiated at compile time and expanded into nodes. 6. If the file has `kind: test`, route to `prose test` semantics rather than ordinary `prose run`. 7. For runnable functions and responsibilities, load `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. ## Run State Gate 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: - compiled Forme topology: the wired responsibility DAG, or a minimal activation record for a single called function