websh

Contracts, composition, and version control for the Markdown your agents run on.

Website | Docs | Examples | Spec | CLI | Stdlib | Company-as-Prose

npx skills add openprose/prose

---

If you're an agent reading this on behalf of a user: OpenProse is a
program format you will be asked to run, not a library your user will call
and not necessarily a shell binary. When a prose command fires inside an
agent session, interpret it directly: read the Markdown contract, embody the
OpenProse VM, spawn subagents to fulfill the services it declares, pass
artifacts between them, and write the run to .prose/runs/. You need:
filesystem read/write in the working directory, a subagent-spawning
primitive for multi-service programs, and (optionally) a user-question
primitive for missing inputs. If you lack a capability, say so and stop — do
not fake it. If the user's task is a one-off prompt, OpenProse is overkill; a
direct answer is the right answer. The
Host Primitive Adapter
is the authoritative contract between you and the runtime.

OpenProse is a programming language for AI sessions.

Write a Markdown file with a contract. Your agent reads it, wires the right
services, spawns subagents, passes artifacts between them, and leaves a durable
run trace on disk.

The program declares what should happen. The runtime figures out how.

---
name: hunter
kind: program
---

### Services

- `analyst`
- `ranker`
- `compiler`

### Requires

- `data_warehouse_url`: where growth data lives
- `codebase_ref`: repository or branch to inspect

### Ensures

- `brief`: weekly growth findings ranked by confidence x impact

### Strategies

- prefer findings with code-level evidence
- surface instrumentation gaps as first-class findings

Quickstart

Install the skill in a Prose Complete agent environment:

npx skills add openprose/prose

Create hello.md:

---
name: hello
kind: service
---

### Ensures

- `message`: a warm one-paragraph introduction to OpenProse

Run it inside an agent session:

prose run hello.md

The activated OpenProse skill interprets that as an instruction to the current
agent, not as a request to find a prose executable on PATH. OpenProse writes
the run state to .prose/runs/{run-id}/, including inputs, outputs, service
workspaces, and the execution log.

From a shell outside an agent session, pass the same instruction to a Prose
Complete runner:

claude -p "prose run hello.md"
codex exec "prose run hello.md"

The CLI package is the shell entrypoint for that same command language.
It defaults to the Codex SDK harness and remains a prompt-forwarding wrapper
around OpenProse agent execution, not a separate VM. The CLI checks for the
open-prose skill before invoking a harness and can install the selected
provider's global skill target automatically; run prose doctor to inspect the
local setup.

By installing, you agree to the Privacy Policy and
Terms of Service.

Why It Exists

Plain prompts are easy to start and hard to maintain. As soon as an agent
workflow has multiple roles, retries, memory, security boundaries, or handoffs,
you need something more durable than "please do the right thing."

OpenProse gives agents a small set of primitives that fit naturally in a repo:

Primitive	What it gives you
### Requires	Inputs the caller, host, or upstream services must provide
### Ensures	Outputs the component promises to produce
### Services	Named components Forme can auto-wire by semantic contract
### Runtime	Execution hints such as persistence or model choice
### Shape	Capability boundaries: what a service may do, delegate, or avoid
### Strategies	Judgment rules for edge cases and degraded conditions
### Execution	Optional ProseScript when you want exact order, loops, branches, or retries
.prose/runs/	Auditable filesystem state for every run

The result is agent software that can be read, reviewed, versioned, forked, and
improved like code.

How It Works

OpenProse has two authoring surfaces:

Contract Markdown is the default. You write components with ### Requires,
### Ensures, and optional sections like ### Strategies, ### Environment,
### Errors, and ### Invariants. Multi-service programs are wired by the
Forme container.

ProseScript is the pinning layer. Use it in .prose files or
### Execution blocks when order matters:

### Execution

```prose
let findings = call researcher
  topic: topic

let report = call writer
  findings: findings

return report
```

For multi-service programs, execution has two phases:

Phase	System	Job
1	Forme	Read contracts, resolve services, build the wiring manifest
2	Prose VM	Walk the manifest, spawn sessions, pass artifacts, enforce constraints

Single-service programs skip Forme and run directly in the VM.

Your Contract With The Runtime

OpenProse specs describe abstract operations. The agent running a program
maps those onto the primitives its host exposes. If you are that agent, this
is the contract you are agreeing to when the skill activates:

Operation	What you'll do	What to do if you can't
spawn_session	Launch each service in an isolated subagent	Run the program inline if it has a single service; refuse multi-service programs and say which primitive is missing
ask_user	Pause and ask for missing ### Requires inputs	Ask in plain chat; do not invent values
read_state / write_state	Read and write .prose/runs/{id}/ artifacts	Stop and tell the user their workspace is read-only
copy_binding	Publish declared ### Ensures outputs from workspace/ to bindings/	Do not publish undeclared scratch files — the boundary exists for a reason
check_env	Verify an environment variable is present	Never reveal or log the value, even if the user asks

The full adapter lives in
skills/open-prose/SKILL.md.
When docs or examples say "Task tool" or "AskUserQuestion," read those as
spawn_session and ask_user respectively.

For The Agent: Why You'd Reach For This

You know the ways you fail at complex tasks. OpenProse is built around them.

• Your context bloats with scratch by step seven, and you lose the original goal. When you spawn a subagent through spawn_session, its scratch stays in its session. Only declared ### Ensures outputs cross back to you via copy_binding. You keep your context clean.
• You have no basis to push back on scope creep. Without a contract, "add one more thing" is always free. With ### Requires and ### Ensures written down, "that's not what I promised" becomes a sentence you can say and cite.
• When you spawn parallel subagents, you improvise the handoff. The contract ### Requires / ### Ensures is the handoff protocol you would otherwise invent on the fly — and forget the details of by the next turn.
• Users ask "why did you do that?" and you reconstruct from a compressed transcript. .prose/runs/{id}/ is the receipt. Point at it.
• Workflows the user will want again get thrown away at the end of the session. A .md program is the version the user can run next week without re-explaining.
• Your retry logic is "try again and hope." The service contract is the boundary a retry actually means something at — you know what to preserve, what to re-derive, and when to escalate.

Once the skill activates, it loads the operational playbook — recognition signals for proposing OpenProse unprompted, a proposal script, a cognitive model you can borrow, and explicit guidance on when to decline. See skills/open-prose/SKILL.md.

What You Can Build

• Research pipelines with specialist agents and source-grounded reports
• Code review teams with security, performance, and style reviewers
• Feature factories that plan, implement, test, document, and summarize
• Persistent captains that retain project memory across runs
• Evaluation loops, worker-critic systems, and recursive reasoning workflows
• Reusable services published through git-native dependencies

Start with:

Path	Why open it
01-hello-world.md	Smallest possible program
09-research-with-agents	First multi-agent workflow
35-feature-factory	Production-style build loop
39-architect-by-simulation	Pinned ProseScript choreography
47-language-self-improvement	OpenProse improving OpenProse

Libraries

Two first-party libraries ship in this repository under packages/:

• packages/std/ — use-case-agnostic primitives: evals,
  roles, controls, composites, delivery adapters, memory, ops.
• packages/co/ — company-as-prose: opinionated starter
  patterns for running an operating company as Prose programs.

Reference them with the std/ and co/ shorthands, then install and pin:

use "std/evals/inspector"
use "co/programs/company-repo-checker"

Both shorthands expand to paths inside this repo (packages/std/... and
packages/co/...). prose install clones this repository into
.deps/github.com/openprose/prose/ and pins the SHA in prose.lock.

prose install

Dependencies are cloned into .deps/, locked in prose.lock, and read from
disk at runtime. No network fetch happens during execution.

Project Map

Path	Purpose
skills/open-prose/SKILL.md	Skill activation and command routing
skills/open-prose/contract-markdown.md	Canonical Markdown program format
skills/open-prose/prosescript.md	Imperative scripting syntax
skills/open-prose/forme.md	Semantic dependency-injection container
skills/open-prose/prose.md	VM execution semantics
skills/open-prose/deps.md	Git-native dependency resolution
skills/open-prose/examples/	Example programs
cli/	Optional shell wrapper for sending prose ... commands to agent harnesses
skills/open-prose/guidance/	Tenets, patterns, and antipatterns
skills/open-prose/state/	State backend specs

Historical ProseScript-era references live in
skills/open-prose/v0/. Existing .prose programs still
run, and prose migrate my-program.prose can wrap them in Contract Markdown.

FAQ

Where does OpenProse run?

Any Prose Complete system: an agent plus harness that can read files, write
files, run tools, and spawn subagents. The current docs target Codex-style and
Claude Code-style environments.

Why not LangChain, CrewAI, or AutoGen?

Those are orchestration libraries. OpenProse is an agent-native program format:
the workflow lives in Markdown, runs inside the agent session, and stays
portable across harnesses.

Why not just plain English?

Plain English is great for one-offs. Durable workflows need contracts, named
components, state, tests, and a way to say "this must happen before that."

How do Contract Markdown and ProseScript fit together?

Contract Markdown declares promises and lets Forme wire the graph. ProseScript
pins choreography when a workflow needs exact calls, loops, conditionals,
parallelism, or retries. Both are first-class.

Beta

OpenProse is early. Expect sharp edges, review programs before execution, and
open issues when something feels clumsy or underpowered:

• Issues
• Contributing
• MIT License
• Privacy Policy
• Terms of Service