/open-prose

name: open-prose
version: 0.18.1
runtime_contract: 2
description: |
  Activate when the user types `prose ...`, opens a `.prose.md` file with
  `kind:` frontmatter, opens a `.prose` file, or asks for reusable multi-agent
  orchestration. Treat `prose run ...` as an in-session instruction: embody
  the OpenProse VM yourself; do not shell out to a `prose` binary. On
  activation read the Markdown contract, select a state backend, wire responsibilities,
  execute with host primitives, and persist run state under the selected
  OpenProse root.
  Decline for one-shot questions — a plain prompt is often the right answer.

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, re