open-prose

# OpenProse Skill Contract authoring is expressing intent by composing requirements. An agent performs the work, and an evaluator assesses whether the contract’s requirements are satisfied. Reuse and combine contracts through the interfaces in this skill; see [requirements and composition](guidance/authoring.md#requirements-and-composition). 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. ## 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 | | 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. ## 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 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`. ## 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 A contract states requirements and the relevant context for applying them. Declared inputs, results, and conditions help callers reuse it and combine it with other contracts. Assess the result against those requirements: a completed run or a receipt alone does not prove satisfaction. The selected host supplies tools and enforcement; a declaration does not supply a missing capability. ### 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, 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"`. | 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. ## 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 - `root.prose.md`: snapshot of the invoked source - `sources/`: snapshots of referenced responsibility, function, gateway, and pattern sources