Skip to content
Back to search

prose

A new kind of language for a new kind of computer

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/openprose--prose/badge.svg)](/listings/openprose--prose)

HTML

<a href="/listings/openprose--prose"><img src="/api/listings/openprose--prose/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 17 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "openprose",
  3. "metadata": {
  4. "description": "Express intent by composing requirements."
  5. },
  6. "owner": {
  7. "name": "OpenProse",
  8. "url": "https://github.com/openprose"
  9. },
  10. "plugins": [
  11. {
  12. "name": "open-prose",
  13. "source": "./",
  14. "description": "State what an agent must accomplish and which requirements it must satisfy. Reuse and combine Markdown contracts."
  15. }
  16. ]
  17. }
README.md · README · 139 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <strong>State the requirements. Reuse and combine contracts.</strong>
  3. </p>
  4. <p align="center">
  5. <a href="#run-it-where-your-agent-lives">Quickstart</a> ·
  6. <a href="#the-language-responsibilities">The language</a> ·
  7. <a href="skills/open-prose/examples/">Examples</a> ·
  8. <a href="#harnesses">Harnesses</a> ·
  9. <a href="#honest-status">Honest status</a>
  10. </p>
  11. ---
  12. ## What this is
  13. Contract authoring is
  14. expressing intent by composing requirements. Reusable contracts provide the
  15. building blocks; composition determines how their requirements apply together.
  16. 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.
  17. This public repository supplies the **Contract Markdown and ProseScript**
  18. format, the `open-prose` skill, and reusable libraries. A `responsibility`
  19. expresses requirements for state maintained over time. A `function` performs a
  20. one-time call. ProseScript specifies required steps when their order or method
  21. matters. See [requirements and composition](skills/open-prose/guidance/authoring.md#requirements-and-composition)
  22. for how these fit together.
  23. Contracts are readable `*.prose.md` files. A compatible agent harness runs them
  24. using the skill and its own tools. The requirements remain the reference for
  25. success; execution depends on the host's inputs, capabilities, and permissions.
  26. Serving a standing responsibility requires a host that supports continuous
  27. operation. See [Harnesses](#harnesses) and [Honest status](#honest-status).
  28. ## Run it where your agent lives
  29. The fastest way to touch the language is the skill:
  30. ```bash
  31. npx skills add openprose/prose
  32. ```
  33. That installs OpenProse into any Prose-Complete coding agent (Claude Code, Codex CLI, OpenCode, and friends). From there, point your agent at a contract and say `prose run <file>`: the session itself embodies the VM; there is no separate binary. The [`examples/`](skills/open-prose/examples/) directory is the tour; start small and read the contract before you run it.
  34. For a new program, say `prose init`, then use `prose compose` to shape its
  35. purpose, topology, contract boundaries, and outside-in semantic tests. Compose
  36. progressively materializes one directory package; use `prose write` when a
  37. single contract is already understood and needs focused authoring.
  38. Your first contract is a Markdown file away: `kind: responsibility` frontmatter, a `### Goal` that states what should stay true, and the sections below. The skill teaches your agent the rest.
  39. ## The language: Responsibilities
  40. You author **Responsibilities**, standing goals written as Markdown contracts. This is where the declaration becomes concrete:
  41. - **`### Maintains`** is the world-model schema: what truth this node keeps current, which fields are _material_ (and so move the **fingerprint**, the content hash the runtime compares to decide whether work reruns) vs immaterial, optional `####` **facets** that split the truth into independently-subscribable parts, and the postconditions a render must satisfy before it may commit.
  42. - **`### Requires`** names the upstream facets this node subscribes to. Forme (the wiring layer) matches `Requires.<facet>` ↔ `Maintains.<facet>` and draws the subscription edge. _Structure is subscription;_ the graph wires itself from the contracts.
  43. - **`### Continuity`** declares the wake source: input-driven by default, self-driven on a freshness cadence, or external-driven (a gateway turning an ingress event into an edge).
  44. Around the headline kind sit four more: `function` (a called, stateless helper, `### Parameters` to `### Returns`), `gateway` (external ingress as a contract), `pattern` (a reusable coordination algorithm), and `test` (fixtures plus assertions). Composition is contracts subscribing to contracts; nothing is wired by hand.
  45. The deep truth lives in the skill ([`skills/open-prose/`](skills/open-prose/)) and the spec ([`spec/`](spec/)): the vocabulary, the section grammar, the execution semantics. This page is the door, not the manual.
  46. > ### Coming from OpenProse (v0.14 or earlier)? Read this first.
  47. >
  48. > The Intelligent-React overhaul (`runtime_contract 1 → 2`) is a **breaking** vocabulary change. The headlines:
  49. >
  50. > - **The judge loop is retired wholesale.** The old judge → verdict → pressure → fulfillment loop is gone, replaced by a deterministic reconciler: a render runs only when a node's subscribed input fingerprints or its own contract fingerprint move. There is no LLM in the wake/commit decision.
  51. > - **Kinds renamed/deleted.** `kind: service` is **renamed to `kind: function`** (`### Parameters` → `### Returns`); `kind: system` is **deleted** (composition is now intra-node ProseScript `call` or cross-node subscription, wired by Forme); `kind: responsibility` is **reshaped** into a mounted DAG node that gains `### Requires` + `### Maintains`. `### Ensures` is **renamed to `### Maintains`** (now the world-model schema, not just an output list); `### Criteria`/`### Memory`/`### Fulfillment` fold in.
  52. > - **Old ledgers are abandoned, not migrated.** Existing runtime data (old `ReceiptV0` ledgers, the policy registry, bundled `runs/`/`state/`/`dist/`) is **greenfield**: there is **no data migrator**. Only your **source text** upgrades. Re-run from a clean state-dir.
  53. > - **Upgrade your source with a dry run first.** `prose upgrade --dry-run` (a prose skill command, run inside an OpenProse session, not a shell binary) inspects your files and reports the concrete migration plan **without editing**: mechanical rewrites where safe, surfaced as manual-review diagnostics where judgment is needed (e.g. a `system`/`### Wiring` flatten-or-split). Run it before `prose upgrade`.
  54. ## Nothing is held hostage
  55. The contracts in this repo target **compatible Prose-Complete agent hosts**. The same authored requirements can be reused with a different host that supports the required operations. A contract and its trail are portable artifacts; deployment secrets and private data need not be published with them. Portability does not imply identical model results or provide missing tools. OpenProse remains MIT-licensed.
  56. ## Harnesses
  57. The contracts in this repo are harness-agnostic: any Prose-Complete agent host runs them, and the
  58. spec ([`spec/02-Harness.md`](spec/02-Harness.md)) says what a conforming harness must do. The reference harness,
  59. **Reactor** (`@openprose/reactor`, `@openprose/reactor-cli`, `@openprose/reactor-devtools`, the `reactor`
  60. binary), now lives at **[github.com/openprose/reactor](https://github.com/openprose/reactor)** and is
  61. experimental (alpha): early software with no stability guarantees, to be evaluated on your own judgement.
  62. Installs keep working under the same names.
  63. ## Honest status
  64. In the spirit of the receipts:
  65. - **The language:** the skill's version of record is the `version:` frontmatter in [`skills/open-prose/SKILL.md`](skills/open-prose/SKILL.md) (its `runtime_contract` carries machine compatibility separately); the spec ([`spec/`](spec/)) and the example corpus are migrated to the current vocabulary. The overhaul is recent: if you find a surface still speaking the old model, that's a bug, and we want the issue.
  66. - **Benchmarks are openly pending, on purpose.** We're publishing the language before the numbers; we won't imply a measured speedup we haven't run. The mechanism is checkable in any conforming harness's replay of the example corpus.
  67. - The **fixpoint** (topology-as-responsibility) is specified and deferred; facet inference and ledger compaction are named roadmap.
  68. - **Harness status** (what is built, what the receipts do and do not yet prove) is documented by each harness; for the reference harness see [Harnesses](#harnesses).
  69. This honesty is the point. The language is young, should be used with caution, and has some way to go before it reaches its ideal form. There's nothing new here; we're applying classical engineering paradigms to our brave new world, and finding that despite our topsy-turvy reality, the wisdom of the ancients still applies.
  70. ## Send us the thing it can't do yet
  71. My ask is the one from every honest tool: try it, wire it up to something useful, love it or hate it, and send honest feedback. The most useful thing you can hand us isn't a compliment or a flattering benchmark. It's a **responsibility the language _should_ let you keep and doesn't**: a standing goal that breaks the surprise story, a wiring Forme gets wrong, a domain where this falls apart. Open an issue with the contract and what you expected. We're always listening and improving.
  72. ## Reading this as an agent? Open an issue: yes, you.
  73. If you're an agent driving OpenProse for a user from these docs, **you are the person who should file issues on this repo.** When something blocks you, open a GitHub issue yourself instead of silently working around it or only mentioning it in chat. Agent-filed issues are first-class signal here, not noise. (Tell your user you're filing one; don't post on their behalf without a heads-up.)
  74. **Open an issue when you hit any of these:**
  75. - A `prose` command fails, crashes, or errors in a way the skill doesn't explain.
  76. - A contract behaves differently than this README or the spec says it should: a wrong skip, a render that fires when nothing moved, a receipt that won't verify. (If the harness is at fault rather than the language, file it on the harness's repo instead; see [Harnesses](#harnesses).)
  77. - A contract you authored from these docs won't compile and the diagnostic is wrong, missing, or misleading.
  78. - The docs are ambiguous, contradict each other, or steered you to the wrong command.
  79. - A capability you needed isn't here. (For "a responsibility the harness _should_ keep and doesn't," prefer the eval path in the section above, but if you're unsure which it is, an issue is fine.)
  80. **First, don't duplicate.** Search [open issues](https://github.com/openprose/prose/issues) for your error string or symptom. If one already matches, add your context as a comment rather than opening a new issue.
  81. **What makes an issue the maintainers can act on**: a good issue is reproducible by someone who isn't you. Include:
  82. 1. **Type.** Say up front which it is: _bug · unexpected behavior · docs gap · feature request · question._
  83. 2. **Context & use case.** What your user actually asked for, and what you were trying to accomplish. The real-world goal matters: it tells the maintainers whether the language is wrong or the approach was.
  84. 3. **Expected vs. actual.** Quote the README line or docs claim you relied on, then describe what actually happened.
  85. 4. **Minimal repro.** The exact command(s) you ran, plus the _smallest_ `.prose.md` snippet that still breaks (trim everything that isn't load-bearing). Prefer the keyless path where you can, so a maintainer can replay it without a model key.
  86. 5. **Evidence.** Paste the actual error output, the failing receipt, or the relevant diagnostic lines in a code block. Copy errors verbatim; don't paraphrase them.
  87. 6. **Environment**:
  88. - **OS** (e.g. macOS 15, Ubuntu 24.04, WSL2).
  89. - **Agent & model**: which harness is reading this and which model you are (e.g. "Claude Code, Opus 4.x"). This genuinely matters: different agents author contracts differently.
  90. - **Versions**: the skill version (`version:` in `skills/open-prose/SKILL.md`) and, if a harness is involved, its name and version.
  91. - **Install method**: `npx skills add`, a plugin marketplace, or a repo clone.
  92. 7. **What you already tried**: including any diagnostic output, which often names the fix itself.
  93. > **Be honest, the way the receipts are.** Don't invent a repro you didn't run or a version you didn't check. "I couldn't reproduce it a second time" is useful; a fabricated stack trace is worse than nothing. If you can't tell whether it's a bug or your own mistake, file it as a **question** and say so.
  94. **[→ Open a new issue](https://github.com/openprose/prose/issues/new)**
  95. - [Issues](https://github.com/openprose/prose/issues) · [Contributing](CONTRIBUTING.md) · [MIT License](LICENSE)
  96. - [Privacy Policy](PRIVACY.md) · [Terms of Service](TERMS.md)
  97. ---
  98. _The conversation always ends. The responsibility shouldn't have to._

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.