OpenProse Help

Load this file when a user invokes prose help or asks about OpenProse.

---

Welcome

Contract authoring is expressing intent by composing requirements. Reusable contracts provide the building blocks; composition determines how their requirements apply together.

An agent performs the work, and an evaluator assesses whether the contract’s requirements are satisfied. The executor returns a result that includes the evidence needed for that assessment. Execution and evaluation repeat as needed.

The public skill uses Contract Markdown for requirements and interfaces, and ProseScript for required steps inside a render. A responsibility maintains state over time; a function provides a one-time call. The agent follows the VM instructions using the selected host's capabilities. See requirements and composition.

---

What Do You Want to Automate?

When a user invokes prose help, guide them toward defining what they want to build. Use the host's user-question primitive when available; otherwise ask the question plainly in chat:

Question: "What would you like to automate with OpenProse?"
Header: "Goal"
Options:
  1. "Run a contract" - "I have a `.prose.md` file to execute"
  2. "Build something new" - "Help me create a contract for a specific task"
  3. "Keep a goal true" - "Define a standing responsibility with compile/serve/status"
  4. "Learn the syntax" - "Show me examples and explain how it works"
  5. "Improve OpenProse" - "Turn run evidence into a focused upstream PR"
  6. "Explore possibilities" - "What can OpenProse do?"

After the user responds:

• Run a contract: Ask for the file path, then load prose.md and execute
• Build something new: Start with prose init / prose compose when the contract system is not yet clear; use prose write when one contract is already understood
• Keep a goal true: Help author a kind: responsibility, then explain prose compile, prose serve, and prose status
• Learn the syntax: Show examples from examples/, explain the VM model
• Improve OpenProse: Run std/evals/prose-contributor on relevant run IDs; require explicit user approval before pushing or opening a PR
• Explore possibilities: Walk through examples like stargazer-outreach/

---

Available Commands

Command	What it does
prose init [request...]	Initialize an OpenProse workspace and begin its architecture
prose compose [request...]	Design and evolve the program's contracts, relationships, and architecture
prose compile [path] [--out <dir>]	Compile source into <openprose-root>/dist/manifest.next.json
prose serve	Serve the active IR as local cron and HTTP trigger adapters
prose run <file.prose.md>	Run a responsibility or function contract
prose write [request...]	Interactive-by-default authoring from rough English/pseudo-Prose into a validated source package; non-interactive runs return unresolved-intent when more detail is required
prose lint <file.prose.md>	Validate structure, schema, and contracts
prose preflight <file.prose.md>	Check dependencies and environment
prose test <test.prose.md>	Run tests with assertions
prose inspect <run-id>	Evaluate a completed run
prose status	Show active IR, diagnostics, trigger plan, recent runs, and responsibility status from the receipt ledger
prose install	Install dependencies from use statements into <openprose-root>/deps/
prose install --update	Update pinned dependencies to latest
prose upgrade --dry-run	Inspect files and report the migration plan
prose upgrade	Apply the migration plan
prose help	This help -- guides you to what you need
prose examples	Browse and run example systems

---

Quick Start

Run an example:

cd examples/stargazer-outreach
prose compile
cp dist/manifest.next.json dist/manifest.active.json
prose serve

Create your first contract:

prose init
prose compose
prose write

prose compose progressively turns the project architecture into full contract source while keeping unresolved regions explicit. It creates semantic tests in order from the package promise through contract boundaries, failure behavior, portability, and performance. It never edits the OpenProse framework during composition; framework feedback is deduplicated and filed as a public issue when authorized, or preserved as an issue draft. Use prose compose --review to challenge the current design and prose compose --reflect <run-id...> to compare it with execution evidence.

Default project source lives under <openprose-root>/src/. Multi-file systems conventionally start at <openprose-root>/src/{system}/index.prose.md; runs are written to <openprose-root>/runs/.

Use a library function or responsibility:

prose run std/evals/inspector -- subject: 20260406-201439-1a3369

Contribute an improvement from run evidence:

prose run std/evals/prose-contributor -- subjects: 20260406-201439-1a3369

Add a dependency:

use "github.com/owner/repo/path/to/service"

Then run prose install to fetch and pin it.

---

FAQs

What AI assistants are supported?

Codex, Claude Code, OpenCode, Amp, and similar agent harnesses. Any host that runs a sufficiently intelligent model and supports the OpenProse primitives (spawn_session, filesystem state, tool calls, and user input) is considered "Prose Complete".

How is this a VM?

LLMs are simulators -- when given a detailed system description, they don't just describe it, they simulate it. The prose.md spec describes a VM with enough fidelity that reading it induces simulation. But simulation with sufficient fidelity is implementation: each session maps to a real spawn_session in the host, outputs are real artifacts, and state persists in files. The simulation is the execution.

What's "intelligent IoC"?

Traditional IoC containers (Spring, Guice) wire up dependencies from configuration files. OpenProse's container is an AI session that wires up agents using understanding. It doesn't just match names -- it understands context, intent, and can make intelligent decisions about execution.

Why not English?

English is already an agent framework -- we're not replacing it, we're structuring it. Plain English doesn't distinguish sequential from parallel, doesn't specify retry counts, doesn't scope variables. OpenProse uses English exactly where ambiguity is a feature (in contract descriptions), and structure everywhere else.

Why not all YAML?

We started with YAML. The problem: loops, conditionals, and variable declarations aren't self-evident in YAML. More fundamentally, YAML optimizes for machine parseability. OpenProse optimizes for intelligent machine legibility. It uses YAML only where structured nesting is doing real work, such as pattern instances. Contracts themselves stay in Markdown because they need to be understood, not merely parsed.

How do dependencies work?

OpenProse uses a git-native dependency model -- any git host works, written explicitly as host/owner/repo/path (e.g. github.com/alice/research). A contract can reference dependencies with use "host/owner/repo/path" or pattern: references, and call resolved functions via ProseScript call. Run prose install to clone dependencies into <openprose-root>/deps/ and pin their versions in <openprose-root>/prose.lock. The lockfile is committed to git; <openprose-root>/deps/ is gitignored (it's a cache, reproducible from the lockfile). std/ is shorthand for github.com/openprose/prose/packages/std/ (the standard library) and co/ is shorthand for github.com/openprose/prose/packages/co/ (company-as-prose). At runtime, dependencies are read from disk only -- no network calls. If deps are missing, prose run errors and tells you to run prose install.

Why not LangChain/CrewAI/AutoGen?

Those are orchestration libraries -- they coordinate agents from outside. OpenProse runs inside the agent session -- the session itself is the IoC container. prose run ... is therefore a command to the agent host, not necessarily a shell binary. From a shell, wrap it in a Prose Complete runner such as claude -p "prose run system.prose.md" or codex exec "prose run system.prose.md". Switch from one supported harness to another and the system should still read the same; only the host primitive adapter changes.

---

Syntax at a Glance

Contract Markdown (*.prose.md files)

Contracts are *.prose.md files with tiny YAML identity frontmatter and readable ### sections. Forme wires the responsibility DAG at compile time; the Prose VM executes the frozen output at run time.

Identity frontmatter:

---
name: competitor-watch
kind: responsibility   # responsibility | function | gateway | test | pattern
---

A responsibility (a mounted, subscribed data-flow node):

---
name: competitor-watch
kind: responsibility
---

### Requires

- `funding`: competitor funding signals

### Maintains

- `summary`: the current competitor-activity truth, with sources

### Continuity

- input-driven

### Errors

- `no-results`: no relevant sources found

### Strategies

- when few sources found: broaden search terms

### Environment

- `API_KEY`: required for external service access

### Requires declares the inputs as subscription contracts; ### Maintains declares the schema of the standing truth the render keeps current (type, canonicalization, facets, postconditions) — it is Forme's match target. ### Continuity declares what can wake the node: input-driven (default), self-driven (a cadence), or external-driven (a gateway).

A function (a called, ephemeral helper):

---
name: summarize-funding
kind: function
---

### Parameters

- `signals`: raw funding signals

### Returns

- `summary`: a concise digest with sources

A function is the library tier — arguments in, value out, no world-model and no ### Continuity. You call functions constantly via ProseScript call and author them rarely (most ship pre-built in std/).

Forme wires the DAG by matching each responsibility's ### Requires to the ### Maintains that satisfies it semantically across mounted responsibilities, and freezes the resolved edges. There is no kind: system and no ### Services graph kind: composition is intra-node call (inside one render) or a cross-node subscription (Forme-wired edge between responsibilities).

Two levels of author control:

1. Contracts only (default) -- Forme wires the edges from ### Requires / ### Maintains
2. Execution block -- author adds a ### Execution section with explicit let/call choreography inside a render

Test files:

---
name: test-my-service
kind: test
subject: my-service
---

### Fixtures

- `topic`: "quantum computing"

### Expects

- `findings`: mentions at least 3 sources

### Expects Not

- `findings`: includes uncited claims

Tests use semantic assertions over observable outputs, not exact wording.

Patterns:

---
name: worker-critic
kind: pattern
---

Patterns define reusable agent design patterns with slots, config, invariants, and delegation rules. They are not run directly; a responsibility instantiates them with a pattern: reference. A nested pattern declaration may appear inside another pattern instance's with: block as a slot value.

ProseScript (### Execution)

ProseScript is the imperative layer. Use it inside ### Execution when a render needs pinned choreography.

let research = call researcher
  topic: topic

parallel:
  let critique = call critic
    draft: research
  let factcheck = call fact-checker
    draft: research

let report = call synthesizer
  research: research
  critique: critique
  factcheck: factcheck

return report

Also valid: session, agent, repeat, for, loop until, try/catch, if/elif/else, choice, block, do, and pipelines. For complete syntax and validation rules, see prosescript.md.

---

Examples

The examples/ directory contains small OpenProse Native Repositories. Each example has src/, dist/, runs/, state/, deps/, a top-level README, and source files for a responsibility, a gateway, and focused functions.

Recommended starting points:

• stargazer-outreach/ -- GitHub stars to qualified, thoughtful outreach
• incident-briefing-room/ -- Incident updates, impact, and next actions
• customer-risk-radar/ -- Customer risk monitoring before renewals or escalations
• release-readiness/ -- Release evidence, risk, notes, and rollback context
• vendor-renewal-watch/ -- Renewal preparation before auto-renewal windows
• research-inbox-triage/ -- Deduplicated, prioritized research intake
• content-performance-loop/ -- Content performance lessons into next actions
• compliance-evidence-tracker/ -- Audit evidence freshness and gap tracking