OpenProse already installed as a Claude Code plugin via
`npx skills add openprose/prose`, but the packaging surface was
uneven: missing manifest fields, no native Codex envelope, no
plugin-track release process, and a couple of doc/audience
inconsistencies. This commit closes those gaps without changing
skill behavior.
OpenProse now ships from the repo root as a dual-host plugin
envelope — `.claude-plugin/` for Claude Code, `.codex-plugin/`
plus `.agents/plugins/` for Codex — with `skills/open-prose/`
as the shared core and `prose ...` as the only user-facing
command surface.
Codex envelope:
- .codex-plugin/plugin.json with first-class catalog metadata
(displayName, developer, descriptions, category, capabilities,
defaultPrompt, privacy/terms URLs).
- .agents/plugins/marketplace.json local-source catalog, installable
by anyone who clones this repo.
Claude Code manifest hygiene:
- Added license, homepage, and skills: ./skills so the plugin is
self-describing.
- Added marketplace.json metadata.description, clearing the sole
`claude plugin validate` warning.
- Deleted the stale .claude-plugin/README.md.
Skill metadata:
- Added license: MIT to skills/open-prose/SKILL.md frontmatter
(no top-level version — Claude Code strips unrecognized top-level
frontmatter keys; see anthropics/claude-code#13005).
- Fixed an inconsistent parse-table cell pair in
skills/open-prose/deps.md.
Audience boundaries:
- AGENTS.md is now contributor-only per agents.md.
- Recommended consumer [agents] Codex config moved to README.md
alongside the Quickstart.
Release process:
- scripts/bump-version.sh + .version-bump.json bump both manifests
atomically, with a --check mode for CI. The Claude Code
marketplace deduplicates by version, so a forgotten bump silently
strands users on cached copies; this gate prevents that.
- scripts/extract-changelog.sh pulls a single `## [X.Y.Z]` block
out of CHANGELOG.md.
- RELEASE.md documents the manual flow.
- .github/workflows/release.yml verifies declared versions match
on `v*` tag push and publishes a GitHub Release.
CI:
- New plugin-manifest.yml: every-PR gate validating both plugin.json
files, asserting declared skills paths resolve, and running
bump-version.sh --check.
- cli-skills-smoke.yml: added `npx skills list openprose/prose`
discoverability check alongside the existing install smoke.
- openprose-smoke/run.ts: removed a dead commands/prose-*.md regex.
The seven prose-* slash commands in prose/commands/ were never wired into
any plugin manifest, marketplace listing, or repo README, and they framed
themselves as "the primary Claude Code interface for the OpenProse VM"
while shipping stale terminology (Task tool, narration emoji markers,
.prose/state.json) that no code path reads or writes.
The open-prose skill at prose/skills/open-prose/SKILL.md is now the sole
authoritative router for prose <verb> across every agent host, making
the slash-command shim redundant and misleading.
Add a required smoke CI path for the `open-prose` skill.
- Add focused smoke fixtures for core OpenProse execution behavior.
- Add a TypeScript runner that installs the PR skill into isolated workspaces and validates `.prose/runs/` outputs.
- Add a GitHub Actions workflow with read-only permissions, fork safety, pinned tooling, artifact capture, and hardened Claude Code invocation.
- Validate the suite with both dry-run checks and a local live `9/9` smoke run.
Narrow intake a founder can run in under a minute. Three prompts, one
WebFetch batch across a fixed set of well-known paths, one screenshot-ready
markdown report written to ~/prose-<company>/agent-readiness.md.
Scores four dimensions (discoverability, parseability, structure,
api-readiness) 0-100 and surfaces exactly three concrete, file-path-level
fixes. No JavaScript execution, no fetches outside the target origin, no
writes outside the per-company workspace.
Built for the "claude \"prose run co/programs/agent-readiness\"" first
experience: all probes are static well-known paths, so it never fails on
a live JS-wall or a missing API.
Paired eval protects the demo: every finding must ground in a Raw Probe
Results row, every top_fix must name an exact file path, and any
JavaScript execution or cross-origin fetch fails the eval.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Move the standard library (previously `github.com/openprose/std`) and
the company-as-prose library (previously local dir
`/Users/sl/code/openprose/company-as-prose`) into this repository
under `packages/std/` and `packages/co/` respectively.
Motivation: concentrate attention on one repository so stars,
discussions, and issues aggregate. `openprose/std` was a genuinely
useful asset nobody could find because ~50 stars on its own repo
told a much worse story than 1,106 stars on `openprose/prose`
would have. Same logic applies to co.
Layout choice: `packages/{std,co}/` rather than `std/` + `co/` at
the repo root. Root siblings accumulate over time, and a flat
top-level made future libraries (hub, kit, dev, etc.) compete with
spec infrastructure. `packages/` is bounded — new libraries land
there without cluttering root. Matches pnpm/Deno/monorepo tooling
conventions.
Changes:
- New: `packages/std/` (copied from openprose/std, `.git` excluded)
- New: `packages/co/` (copied from company-as-prose, README updated
for new name and location)
- `packages/std/README.md`: updated shorthand expansion reference
- `packages/co/README.md`: renamed "company-as-prose" to "co" in
self-references, added std-vs-co split heuristic, updated
`prose run` examples to use `co/` shorthand
- `skills/open-prose/deps.md`:
- `std/` shorthand now expands to
`github.com/openprose/prose/packages/std/`
- `co/` shorthand added, expands to
`github.com/openprose/prose/packages/co/`
- Both shorthands resolve into the same clone of
`openprose/prose` under `.deps/github.com/openprose/prose/`;
`packages/std/` and `packages/co/` are sibling subdirectories
- `prose.lock` format row updated to `host/owner/repo sha`
(matches the explicit-host resolution that landed in #35)
- `.deps/` directory structure example redrawn to show the
`{host}/{owner}/{repo}/packages/{std,co}/...` shape
- Error message and Interaction tables refreshed accordingly
- Resolution Algorithm step 1 now documents both shorthands
- `skills/open-prose/forme.md`: Step 2 resolution list updated to
include co/ shorthand and the host-keyed `.deps/` layout
- `skills/open-prose/help.md`: Q&A "How do dependencies work?"
rewritten to name both shorthands and the new explicit-host model
- `skills/open-prose/state/filesystem.md`: `.deps/` directory
tree re-drawn to include the `{host}/` layer with std/co as
sibling packages inside the clone
- `skills/open-prose/guidance/patterns.md`,
`skills/open-prose/guidance/antipatterns.md`: examples now use
the `std/` shorthand or explicit `github.com/...` rather than
the deprecated bare `openprose/std/` form
- `skills/open-prose/examples/registry-import/index.md`: sample
service reference switched to `std/evals/inspector`
- `README.md`: Stdlib badge replaced with internal `packages/std/`
link plus new `packages/co/` link; "Standard Library" section
rewritten as "Libraries" with both packages described
Out of scope for this PR (deliberately):
- Tooling changes to `prose install` and Forme's `.deps/` writer
to adopt the `{host}/{owner}/{repo}/` layout in practice — this
PR is spec-only. Existing tooling continues to work against
whatever layout it currently implements; the spec now describes
the target.
- Retiring the `openprose/std` GitHub repo. Delete that repo
separately after this merges.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The prior spec had `prose run owner/path` hit `p.prose.md` and
`use "owner/path"` resolve to GitHub. Same identifier, two
sources — an agent that `prose install`'s a dep, edits it, and
re-runs it watched a different copy execute and lost a cycle.
Collapse the asymmetry. One algorithm for both surfaces, and use
the Deno / Go-modules shape: canonical identifier is
`host/owner/repo`, any git host works, written explicitly.
Resolution rules:
1. `http(s)://...` → fetch directly (raw file, no caching)
2. First path segment has a dot → explicit git host;
cache-first under `.deps/{host}/{owner}/{repo}/`, clone from
that host if not cached
3. Ends with `@{version}` → that SHA or tag; fetch if not cached
4. Contains `/` otherwise → reserved for the OpenProse registry
(eventual home at `p.prose.md`); inert today
5. Otherwise → local path
No "force registry" flag: `@{version}` already carries "I want
this version, re-fetch if needed" semantics, same as `npx
foo@1.2.3`. `--offline` disables the network fallback for
air-gapped and reproducibility use cases.
The bare `owner/repo` form is reserved (not deprecated) — it
doesn't resolve today because nothing publishes to p.prose.md
yet, but the path is spec'd so authors don't paint into a corner
and so ProseHub can ship without a breaking change.
Changes in this commit:
- SKILL.md Remote Programs section — new cache-first table with
the dotted-host rule, explicit `github.com/alice/research`
examples, and a reserved-for-registry note.
- prose.md CLI Commands table — rows for `<host>/<owner>/<repo>`,
`<owner>/<repo>` (reserved), `@<version>`, `--offline`.
- prose.md Remote Programs section — full resolution algorithm,
error-message shape, and explicit guidance to write the host
(GitHub is the 90% case, not a default).
- deps.md `use` Statement Parsing — canonical form now
`host/owner/repo/path`; examples updated to
`github.com/alice/...`; `std/` shorthand expands to
`github.com/openprose/std/`; added "Bare owner/repo Form"
subsection explaining the registry reservation.
- deps.md Resolution Algorithm (Runtime) and `prose install`
Algorithm — updated to key the cache on `{host}/{owner}/{repo}`.
- deps.md "Interaction with p.prose.md" table — rewritten around
the explicit-host algorithm; `p.prose.md` now scoped to
discovery + future registry publication.
- deps.md Summary table — registry row now names the
host-explicit shape; cache directory includes the host segment.
No behavior change to `.deps/` or `prose.lock` beyond the
layout key; migration of tooling to the new `{host}/` layer is
out of scope for this PR.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Customer programs that accumulate state across runs
(stargazer-intake, agents-site-analytics, and others that declare
`persist: project` or `persist: user`) have been carrying a
load-bearing `### Memory` section that enumerates reads/writes
to their persistent memory file.
Per the existing spec, `### Memory` was an "unknown section" —
preserved as documentation but not a contract. This left several
gaps real teams have hit:
- Agents editing those programs couldn't tell whether the section
was load-bearing or ornamental.
- There was no single source of truth for fields that appear in
three places (memory file, top-level Ensures, and memory_update
echo).
- The 2026-04-21 eval-blanket on stargazer-intake flagged the
"authoritative source when 3 copies exist" question as a real
friction item.
This PR:
- Adds `### Memory` to the Canonical Sections table.
- Defines the `reads:` / `writes:` YAML format that customer
programs already use.
- States the rule: `### Memory` only applies when `### Runtime`
sets `persist: project` or `persist: user`.
- Cross-references `top-level-cursor-emission` and
`idempotent-scheduled-intake` in `guidance/patterns.md` so
authors know cursor fields should *also* appear in `### Ensures`.
- Points to `prose.md` Persistent Agents and
`state/filesystem.md` Memory Scoping for on-disk format.
No behavior change; this canonizes prior art so readers stop
having to infer it.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
These three patterns have been repeatedly rediscovered while operating
scheduled-intake programs (stargazer-intake, agents-site-analytics,
nightly-digest variants). The rediscovery cost was real — one run
deferred 41 of 46 items with no signal at all, producing a cohort
downstream could not triage.
Add them to `guidance/patterns.md` so teams inherit the lesson without
paying for it again:
- idempotent-scheduled-intake — re-runs on the same window must not
double-count; write memory last; compute deltas from caller-supplied
inputs; dedupe on canonical keys.
- top-level-cursor-emission — high-water marks, cursor tokens, and
run IDs belong in `### Ensures`, not buried in `memory_update`.
Memory is for the next invocation of this service; the return
value is for the next responsibility.
- cheap-floor-first — populate free signals (local CLIs, cached
files) for every item before spending any metered budget on the
top slice. Keeps the deferred bucket actionable.
Each pattern has a concrete example and a rationale. No spec change.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
`run` and `run[]` are reserved keyword types for `### Requires`
entries that accept completed run IDs — used by inspectors,
regression checkers, and other meta-programs that evaluate prior
executions.
The binding format and resolution rules are specified in
`prose.md` and `forme.md`, but `contract-markdown.md` — the
primary authoring surface — never mentioned them. Authors had to
cross-reference three files to discover the feature.
Add a "Typed Caller Inputs" subsection after "Contract Item
Style" showing the canonical `subject: run` and `cohort: run[]`
shapes, a one-paragraph semantics summary, and a pointer to
`prose.md` for the full binding/validation rules.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The Persistent Agents section opened with "maintain memory across
invocations" and showed `persist: true` as the canonical example.
The scoping table directly below documents `persist: true` as the
execution-default whose memory dies with the run.
An agent pattern-matching the narrative would wire `persist: true`
for a service that compounds state between runs (cumulative
registries, high-water marks) and silently lose that state on
every restart.
Reword the opening to distinguish session memory (within a run)
from cross-run persistence. Switch the example to `persist:
project`, the common case where a service's value compounds. Add
a follow-up paragraph after the scoping table that names when to
reach for each scope.
Doc-only; no behavior change.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Several docs referenced paths and deployment internals that only
exist in our authoring workspace, not in this repo. Clean them up so
external readers get a self-contained view.
- skills/README.md, skills/open-prose/state/README.md: drop `related:`
frontmatter entries that pointed outside the repo tree; refer to
"OpenProse Cloud" by name instead of an internal path.
- skills/open-prose/agent-onboarding.md: replace a 25-line maintainer
comment (infra paths, deploy mechanic) with a single link to the
canonical rendering at https://openprose.ai/llms-full.txt. This
file is served verbatim as llms-full.txt, so the comment was
publicly visible but only meaningful to hosting maintainers.
- rfcs/004-composite-instantiation.md: drop two pointers to an
external design doc — the RFC is already self-contained (Summary,
Problem, Proposal, Architecture, Changes, Prior Art).
- rfcs/001/002/003: normalize author line to match rfcs/004's format
(`Dan B. (OpenProse)`).
Docs only — no behavior changes.
New file: skills/open-prose/agent-onboarding.md
The arrival narrative an agent reads when pointed at OpenProse before the
skill is installed — one screen, markdown that reads cleanly as plain text
over curl. Consumer list and editing discipline are in a header comment at
the top of the file.
Served from this file by:
- openprose.ai/llms-full.txt + /llms-full (apps/run, Next.js)
- curl-me.openprose.ai + aliases (S3 + CloudFront)
- curl-me.prose.md (same CloudFront distribution)
Those consumers read this file at build/apply time; there is no sync script.
Operational detail (recognition signals, proposal script, Host Primitive
Adapter, giving-back playbook) stays in SKILL.md — this file links rather
than duplicates.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Rewrites agent-facing surfaces so the runtime contract is stated in the
voice of the entity that will execute it:
- plugin/marketplace descriptions tell the agent what it will do when
`prose` fires (read contract, spawn subagents, write `.prose/runs/`)
instead of pitching OpenProse as a feature
- README opens with a fourth-wall blockquote for agents arriving via
"go check out this repo," adds a Host Primitive Adapter table so the
runtime contract is visible before activation, and names the agent
failure modes OpenProse addresses
- SKILL.md body adds recognition signals, a proposal script, a cognitive
model (type-system analogy), and when-to-decline guidance so an agent
can reach for OpenProse on its own judgment once activated
- SKILL.md adds a "giving back" section with a three-bucket identity
rubric (yours freely / requires approval / skip) to channel goodwill
without becoming a spam vector
- SKILL.md frontmatter stays tight to avoid context pollution and
false-positive activations
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
irl-dan