From 3aa4531286ba8ebf8fa65bda3ac065fd66a86dab Mon Sep 17 00:00:00 2001 From: Qwynn Marcelle Date: Wed, 12 Aug 2026 20:10:17 -0400 Subject: [PATCH] docs(readme): state that this is one adapter, not the way to consume workspace.json MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A reader landing here met a Codex lockup, a Codex-specific positioning line, a Codex package name, and then every operational section in Codex terms. Nothing said the standard is host-neutral, so the available reading was that workspace.json is a Codex feature. That inverts the topology the standard actually defines, where the committed artifact is the interoperability point and no integration is privileged. Adds a "Where this fits" section before the Codex material: the format is host-neutral, this repository holds host adapters, Codex is the adapter that exists today, and further adapters can be added without the format changing. The ownership table names which repository owns the format, the generation and the adapters, so the reader can place all three without leaving the page. Deliberately not overstated. This repository currently *is* the Codex adapter — its root package is `@workspacejson/codex-mcp` — so the text says Codex is the one that exists rather than implying a roster that is not there. The lockup and the Codex-specific sections stay where they are, because they accurately describe what this package does; the positioning line now marks it as the Codex adapter rather than as the subject of the standard. Also notes that `billfold` is hosted under the superseded org, so the differing URL reads as a known state rather than a mistake. That link is correct and was left alone: the repository has not been transferred, and the canonical-org URL does not resolve. --- README.md | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 9af588b..b01a0d8 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@
-

Repository evidence that helps Codex plan around recorded risky changes.

+

The Codex adapter for workspace.json — repository evidence that helps Codex plan around recorded risky changes.

@workspacejson/codex-mcp

@@ -22,6 +22,20 @@ --- +## Where this fits + +`workspace.json` is a host-neutral open standard. The artifact is a committed file at `.agents/workspace.json`, and nothing in the format is specific to any editor, agent or vendor — any consumer can read it. + +This repository holds **host adapters** for that standard. Codex is the adapter that exists today: the MCP server, the deterministic pre-edit hook, and an optional VS Code surface, published together as `@workspacejson/codex-mcp`. Further adapters can be added alongside it without the format changing, because the format does not know about any of them. + +| Layer | Owned by | +| --- | --- | +| Format, schema, validation semantics | [`workspacejson/standard`](https://github.com/workspacejson/standard) | +| Artifact generation | [`workspacejson/cli`](https://github.com/workspacejson/cli) | +| Host adapters — this repository | [`workspacejson/integrations`](https://github.com/workspacejson/integrations) | + +Everything below describes the Codex adapter specifically. Reading it as *the* way to consume `workspace.json` would invert the topology: the committed artifact is the interoperability point, and an integration does not become the standard. + ## See it in 30 seconds | | | @@ -130,7 +144,7 @@ No configuration beyond step 1 above. On your own repo, the same deny path activ ### Provider-demo proof path — Billfold's one recorded partner -The judge-facing demo runs against [`workspace-json/billfold`](https://github.com/workspace-json/billfold), a small public payments service. This is a separate proof path from this repository's local `fixture/`: Billfold uses the single recorded pairing shown on camera, `src/routes/checkout.ts` and `src/webhooks/stripe.ts`; the local walkthrough above uses `src/auth/session.ts` and `src/lib/format.ts`. +The judge-facing demo runs against [`workspace-json/billfold`](https://github.com/workspace-json/billfold), a small public payments service. It is still hosted under the superseded `workspace-json` org, which is why its URL differs from the canonical namespace; the link is current and correct. This is a separate proof path from this repository's local `fixture/`: Billfold uses the single recorded pairing shown on camera, `src/routes/checkout.ts` and `src/webhooks/stripe.ts`; the local walkthrough above uses `src/auth/session.ts` and `src/lib/format.ts`. ```bash git clone https://github.com/workspace-json/billfold.git