open-prose

What this skill does

# 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